[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
+392
-42
@@ -1,75 +1,425 @@
|
||||
---
|
||||
id: wiki-2026-0508-aci
|
||||
title: ACI
|
||||
title: ACI (Agent-Computer Interface)
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d]
|
||||
aliases: [Agent-Computer Interface, ACI, agent harness interface, tool interface, LLM tool design]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.98
|
||||
tags: [aci, agent, interface, llm, infrastructure, harness]
|
||||
source_trust_level: B
|
||||
confidence_score: 0.85
|
||||
verification_status: conceptual
|
||||
tags: [aci, agent, llm, tool-design, harness, infrastructure, prompt-engineering, mcp]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-01
|
||||
last_reinforced: 2026-05-09
|
||||
github_commit: wikification-aci
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
inferred_by: Claude Opus 4.7 (manual cleanup 2026-05-09)
|
||||
tech_stack:
|
||||
language: TS / Python
|
||||
framework: MCP / Anthropic SDK / OpenAI SDK / LangChain
|
||||
---
|
||||
|
||||
# Agent-Computer Interface (ACI)
|
||||
# ACI (Agent-Computer Interface)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> ACI는 인간 중심의 UI를 넘어, LLM 에이전트가 컴퓨터 시스템(OS, 파일, 도구)을 효율적으로 조작할 수 있도록 최적화된 추상화 인터페이스이며, 에이전트의 관찰(Observation) 및 행동(Action) 공간의 품질을 결정하는 핵심 설계 요소이다.
|
||||
> **Human UI ≠ Agent UI**. LLM agent 의 매 file / tool / output 의 representation 가 model 의 perception. **Tool name + description + schema + error message 가 agent 의 IQ 를 결정**. SWE-bench score 의 매 jump 가 ACI 의 redesign.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
### 1. ACI의 정의 및 필요성
|
||||
- **모델을 위한 인터페이스**: 인간에게는 시각적 UI(GUI)가 필요하지만, 에이전트에게는 구조화된 데이터(JSON, XML)나 간결한 텍스트 출력이 더 효율적이다.
|
||||
- **인지 부하 감소**: 불필요한 시각적 노이즈를 제거하고 에이전트가 행동의 결과와 시스템 상태를 정확히 파악할 수 있도록 정보를 재구성한다.
|
||||
|
||||
### 2. ACI 설계 원칙
|
||||
- **구조적 명확성**: 도구의 인자 스키마(Schema)와 반환값 형식을 엄격하게 정의하여 모델의 파싱 오류를 줄인다.
|
||||
- **에러 피드백의 풍부함**: 단순한 실패 메시지가 아닌, 모델이 다음 행동을 수정할 수 있는 구체적인 힌트(예: "파일이 없습니다. 현재 경로의 파일 목록은 다음과 같습니다...")를 제공한다.
|
||||
- **상태의 가시성**: 현재 작업 디렉토리, 샌드박스 상태, 환경 변수 등 에이전트가 추론에 필요한 문맥을 명시적으로 노출한다.
|
||||
### 정의
|
||||
ACI = LLM agent 가 컴퓨터 (OS, file, tool, API) 와 상호작용 하는 interface design.
|
||||
- Human 에 GUI / CLI 가 있으면, agent 에 ACI.
|
||||
- 매 ACI 의 quality 가 agent 의 task 성공률 결정.
|
||||
- "Same model + better ACI = +20% score" (Princeton SWE-agent 의 발견).
|
||||
|
||||
### 3. 하네스 내에서의 역할
|
||||
- **입출력 래퍼**: 하네스는 컴퓨터의 원시 출력을 ACI 표준에 맞춰 가공하여 모델에게 전달하며, 모델의 자연어 요청을 시스템 명령어로 변환한다.
|
||||
- **인터페이스 최적화**: 특정 모델의 특성(예: 긴 JSON에 강함, 특정 태그 형식 선호)에 맞춰 ACI를 튜닝하여 작업 성공률(Pass@1)을 높인다.
|
||||
### Why ACI matters
|
||||
- **Token 효율**: 매 tool 의 verbose output = context 폭발 / cost.
|
||||
- **Error recovery**: 매 error message 의 actionable feedback.
|
||||
- **Cognitive load**: 너무 많은 tool / option = LLM 의 confusion.
|
||||
- **Robustness**: 매 schema 의 strict validation = parsing fail ↓.
|
||||
|
||||
### 핵심 design principle
|
||||
|
||||
#### 1. Tool naming
|
||||
- ❌ `do_thing()`, `helper_5()`, `process()` — 모호.
|
||||
- ✅ `read_file(path)`, `search_codebase(query)`, `run_python(code)` — 동작 명확.
|
||||
|
||||
#### 2. Schema (input)
|
||||
```json
|
||||
{
|
||||
"name": "edit_file",
|
||||
"description": "Edit a file by replacing exact text. Fails if oldText not found exactly.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": { "type": "string", "description": "Absolute file path" },
|
||||
"oldText": { "type": "string", "description": "Exact text to replace (whitespace sensitive)" },
|
||||
"newText": { "type": "string", "description": "Replacement text" }
|
||||
},
|
||||
"required": ["path", "oldText", "newText"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
→ 매 field 의 description 가 매우 important.
|
||||
|
||||
#### 3. Output 형식
|
||||
```
|
||||
✅ Structured:
|
||||
{
|
||||
"success": true,
|
||||
"result": { "rows": 5, "data": [...] },
|
||||
"warnings": []
|
||||
}
|
||||
|
||||
✅ Truncated when too long:
|
||||
{
|
||||
"result": "...",
|
||||
"truncated": true,
|
||||
"fullLength": 50000,
|
||||
"next": "Use offset=1000 to read next chunk"
|
||||
}
|
||||
|
||||
❌ Raw 매번 큰 dump:
|
||||
"... 50KB of stdout ...":
|
||||
```
|
||||
|
||||
#### 4. Error message (가장 중요)
|
||||
```
|
||||
❌ Bad: "Error 500"
|
||||
❌ Bad: "Operation failed"
|
||||
|
||||
✅ Good:
|
||||
{
|
||||
"error": "FileNotFound",
|
||||
"path": "/abs/path",
|
||||
"hint": "Did you mean: /abs/path-similar? Or run list_directory('/abs/').",
|
||||
"recovery": ["check path", "list_directory parent"]
|
||||
}
|
||||
```
|
||||
|
||||
→ Error 가 agent 의 다음 action 의 hint.
|
||||
|
||||
#### 5. State visibility
|
||||
```
|
||||
매 tool call 후:
|
||||
- Current working directory.
|
||||
- Recently modified files.
|
||||
- Open file count.
|
||||
- Resource usage.
|
||||
|
||||
→ Agent 의 implicit context.
|
||||
```
|
||||
|
||||
### Design patterns
|
||||
|
||||
#### Pattern 1: Agent 의 file 의 line number prefix
|
||||
```
|
||||
1: import { foo } from './bar';
|
||||
2:
|
||||
3: function hello() {
|
||||
4: return foo();
|
||||
5: }
|
||||
```
|
||||
|
||||
→ Edit 시 line number 의 reference 가능.
|
||||
|
||||
#### Pattern 2: Diff format (edit)
|
||||
```
|
||||
edit_file(path="...", oldText="function foo()", newText="async function foo()")
|
||||
```
|
||||
|
||||
→ Search-and-replace 가 line number 보다 robust.
|
||||
|
||||
#### Pattern 3: Pagination
|
||||
```
|
||||
read_file(path, offset=0, limit=2000)
|
||||
→ "lines 0-2000 of 5000. Use offset=2000 for next."
|
||||
```
|
||||
|
||||
→ 매 large file 의 chunked.
|
||||
|
||||
#### Pattern 4: Sub-agent (delegation)
|
||||
```
|
||||
spawn_subagent(task="Search for X across codebase")
|
||||
→ Sub-agent 가 자체 context. Result 의 summary.
|
||||
```
|
||||
|
||||
→ Main context 의 token 절약.
|
||||
|
||||
#### Pattern 5: Confirmation (destructive)
|
||||
```
|
||||
delete_file(path) → "Confirm? This will delete...":
|
||||
agent 의 explicit OK 후 실행.
|
||||
```
|
||||
|
||||
→ Mistake 의 prevent.
|
||||
|
||||
### Modern protocol: MCP
|
||||
**Model Context Protocol** (Anthropic 2024):
|
||||
- Standardized server 가 매 tool / resource expose.
|
||||
- LLM-agnostic.
|
||||
- Server / client architecture.
|
||||
- 매 IDE (Cursor, Claude Desktop) 가 native.
|
||||
|
||||
```typescript
|
||||
// MCP server
|
||||
server.setRequestHandler(ListToolsRequestSchema, () => ({
|
||||
tools: [
|
||||
{ name: 'read_file', description: '...', inputSchema: {...} },
|
||||
],
|
||||
}));
|
||||
|
||||
server.setRequestHandler(CallToolRequestSchema, async (req) => {
|
||||
if (req.params.name === 'read_file') {
|
||||
return { content: [{ type: 'text', text: await fs.readFile(req.params.arguments.path) }] };
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
→ Tool 의 reusable + discoverable.
|
||||
|
||||
### Examples (good ACI)
|
||||
|
||||
#### Cursor / Claude Code
|
||||
- File 의 line number prefix.
|
||||
- Edit 의 string-based (not line-based).
|
||||
- Bash result 의 exit code + stdout/stderr.
|
||||
- Search 의 ripgrep + path filter.
|
||||
|
||||
#### SWE-agent (Princeton)
|
||||
- Custom CLI (cat, edit, ls, search).
|
||||
- 매 command 의 LLM 친화 syntax.
|
||||
- "Window" 의 file view.
|
||||
- Search + line jump.
|
||||
|
||||
#### Devin (Cognition)
|
||||
- Browser tool (visual + DOM tree).
|
||||
- Plan + execute.
|
||||
- Replay + debug UI.
|
||||
|
||||
### Bad ACI examples (avoid)
|
||||
- ❌ Tool list 가 100+: agent 가 헷갈림.
|
||||
- ❌ Tool name 의 inconsistent: `getFile`, `readDoc`, `loadContent`.
|
||||
- ❌ Error 가 stack trace 만: actionable X.
|
||||
- ❌ Output 가 unbounded: token 폭발.
|
||||
- ❌ Schema 가 loose: any input → unpredictable.
|
||||
|
||||
### Token efficiency
|
||||
|
||||
매 tool call 의 token cost:
|
||||
- Tool definition (system prompt): 100-500 tokens / tool.
|
||||
- Tool result: 100-10000 tokens.
|
||||
- 100 tool list = 10k+ tokens / call.
|
||||
|
||||
→ Lazy load: 매 task 의 relevant tool 만.
|
||||
|
||||
```python
|
||||
# Static (옛)
|
||||
all_tools = [tool1, tool2, ..., tool100]
|
||||
|
||||
# Dynamic (modern)
|
||||
relevant_tools = router(query) # 매 query 의 relevant 5 tool 만.
|
||||
```
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
### Anthropic tool use
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
tools = [{
|
||||
"name": "read_file",
|
||||
"description": "Read contents of a file. Returns text or error.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": { "type": "string", "description": "Absolute file path" },
|
||||
"offset": { "type": "integer", "description": "Start line (0-indexed)", "default": 0 },
|
||||
"limit": { "type": "integer", "description": "Max lines (default 2000)", "default": 2000 }
|
||||
},
|
||||
"required": ["path"]
|
||||
}
|
||||
}]
|
||||
|
||||
response = client.messages.create(
|
||||
model="claude-opus-4-7",
|
||||
max_tokens=4096,
|
||||
tools=tools,
|
||||
messages=[{"role": "user", "content": "Read /etc/hostname"}]
|
||||
)
|
||||
```
|
||||
|
||||
### Tool execution wrapper
|
||||
```python
|
||||
def execute_tool(name, arguments):
|
||||
try:
|
||||
if name == "read_file":
|
||||
content = read_file(**arguments)
|
||||
# Truncate if too long
|
||||
if len(content) > 10000:
|
||||
content = content[:10000] + f"\n[Truncated. Total {len(content)} chars]"
|
||||
return {"type": "tool_result", "content": content}
|
||||
# ...
|
||||
except FileNotFoundError as e:
|
||||
# Actionable error
|
||||
parent = os.path.dirname(arguments['path'])
|
||||
siblings = os.listdir(parent) if os.path.exists(parent) else []
|
||||
return {
|
||||
"type": "tool_result",
|
||||
"is_error": True,
|
||||
"content": f"FileNotFound: {arguments['path']}\nNearby files in {parent}: {siblings[:10]}"
|
||||
}
|
||||
```
|
||||
|
||||
### MCP server (TypeScript)
|
||||
```typescript
|
||||
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
||||
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
||||
|
||||
const server = new Server(
|
||||
{ name: 'my-tools', version: '1.0.0' },
|
||||
{ capabilities: { tools: {} } }
|
||||
);
|
||||
|
||||
server.setRequestHandler(ListToolsRequestSchema, () => ({
|
||||
tools: [
|
||||
{
|
||||
name: 'list_users',
|
||||
description: 'List users matching filter. Use for finding existing; for creating, use create_user.',
|
||||
inputSchema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
filter: { type: 'string', description: 'Optional name/email substring' },
|
||||
limit: { type: 'integer', default: 50 }
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}));
|
||||
|
||||
server.setRequestHandler(CallToolRequestSchema, async (req) => {
|
||||
if (req.params.name === 'list_users') {
|
||||
const users = await db.users.findMany({...});
|
||||
return {
|
||||
content: [{ type: 'text', text: JSON.stringify(users, null, 2) }]
|
||||
};
|
||||
}
|
||||
});
|
||||
|
||||
await server.connect(new StdioServerTransport());
|
||||
```
|
||||
|
||||
### Tool registry (dynamic)
|
||||
```ts
|
||||
class ToolRegistry {
|
||||
private tools = new Map<string, Tool>();
|
||||
|
||||
register(tool: Tool) {
|
||||
this.tools.set(tool.name, tool);
|
||||
}
|
||||
|
||||
forContext(query: string): Tool[] {
|
||||
// 매 query 의 relevant 5 만.
|
||||
return [...this.tools.values()]
|
||||
.map(t => ({ ...t, score: this.relevance(query, t) }))
|
||||
.sort((a, b) => b.score - a.score)
|
||||
.slice(0, 5);
|
||||
}
|
||||
}
|
||||
|
||||
// Agent loop
|
||||
const tools = registry.forContext(userQuery);
|
||||
const response = await llm.complete({ messages, tools });
|
||||
```
|
||||
|
||||
→ Token cost ↓.
|
||||
|
||||
### Permission whitelist
|
||||
```ts
|
||||
const ALLOWED = {
|
||||
read_file: { paths: ['/safe/*', '!/etc/*'] },
|
||||
write_file: { paths: ['/output/*'] },
|
||||
shell: { commands: ['ls', 'cat', 'grep'] },
|
||||
};
|
||||
|
||||
function isAllowed(tool: string, args: any): boolean {
|
||||
const rule = ALLOWED[tool];
|
||||
if (!rule) return false;
|
||||
// 매 path / command 의 검증
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
|
||||
| 작업 | 추천 |
|
||||
|---|---|
|
||||
| Simple internal tool | Inline schema |
|
||||
| Multi-tool agent | MCP server |
|
||||
| 큰 codebase navigation | File tools (line number, search, read chunked) |
|
||||
| Browser automation | Computer Use (Anthropic) / WebArena |
|
||||
| Code edit | Search-and-replace > line-based |
|
||||
| Permission | Whitelist > blacklist |
|
||||
| Long-running | Sub-agent (delegation) |
|
||||
| Confirmation | Destructive 만 |
|
||||
| Tool discovery | Dynamic (per-query) |
|
||||
|
||||
**기본값**: MCP-compliant + clear schema + actionable error + structured output. 매 tool 의 description 의 quality 가 agent 의 IQ.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **추상화 vs 제어권**: 인터페이스를 너무 고수준으로 추상화하면 에이전트의 세밀한 제어가 불가능해지고, 너무 저수준(예: raw byte stream)으로 두면 인지 부하가 급증한다.
|
||||
- **범용 표준의 부재**: 각 하네스마다 ACI 설계가 상이하여 에이전트의 행동 패턴이 특정 인터페이스에 고착화(Coupling)되는 현상이 발생한다.
|
||||
- **추상화 수준 의 trade-off**: 너무 high-level (`do_task()`) = agent 의 control 부족. 너무 low-level (`syscall_5()`) = cognitive load.
|
||||
- **표준 의 부재**: 매 harness (Cursor, Devin, AutoGPT) 의 different ACI. 매 agent 의 specific lock-in.
|
||||
- **MCP 의 emerging standard**: 2024-2025 의 push. 매 IDE 의 native support 시작.
|
||||
- **Tool 가 너무 많음**: 매 LLM 의 context limit. Dynamic / hierarchical tool routing.
|
||||
- **Vision (browser screenshot) vs DOM**: Vision 가 robust 가, expensive. DOM tree 가 cheap 가, brittle.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Parent**: 10_Wiki/Topics/AI
|
||||
- **Related**: [[Agent Harness|Agent Harness]], [[Model Context Protocol (MCP)|Model Context Protocol (MCP)]], [[Context Engineering|Context Engineering]]
|
||||
- **Raw Source**: 00_Raw/Agent-Computer Interfaces (ACI)
|
||||
|
||||
## 💻 GitHub 동기화 자동화 워크플로우
|
||||
1. Stage: git add .
|
||||
2. Commit: `git commit -m "[P-Reinforce] Wikify Agent-Computer Interface (ACI) Design Principle"`
|
||||
3. Push: `git push origin main`
|
||||
- 부모: [[Agent-Architecture]] · [[Tool-Use-Function-Calling]] · [[Prompt-Engineering]]
|
||||
- 변형: [[MCP-Model-Context-Protocol]] · [[OpenAI-Function-Calling]] · [[ReAct-Pattern]]
|
||||
- 응용: [[SWE-Agent-Princeton]] · [[Devin-Cognition]] · [[Cursor-Workflow-Patterns]] · [[Claude-Code]] · [[OpenAI-Operator]]
|
||||
- Adjacent: [[Context-Engineering]] · [[Token-Budget-Patterns]] · [[Agent-Sandbox-E2B]] · [[Browser-Agent-Patterns]]
|
||||
- Related: [[AI-Tool-Composition-Deep]] · [[AI-Anthropic-Skills-Patterns]] · [[AI-Multi-Agent-Coordination]]
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
- 새 LLM agent 의 tool design.
|
||||
- MCP server 의 작성.
|
||||
- Agent harness 의 evaluation / improvement.
|
||||
- Production agent 의 quality 개선.
|
||||
- Browser / desktop automation.
|
||||
- Code agent (Cursor / Devin alternative) 디자인.
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
- Single-shot LLM call (no tool).
|
||||
- Simple chatbot (no agentic).
|
||||
- Pre-built framework (LangChain) 가 충분 — custom 가 cost.
|
||||
- ML model serving (다른 domain).
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
- **Tool description 모호**: agent 의 wrong tool 선택.
|
||||
- **Error 가 stack trace 만**: agent 가 recovery 못 함.
|
||||
- **Output unbounded**: token 폭발.
|
||||
- **Tool list 100+**: 매 call 의 cognitive overload.
|
||||
- **Schema loose / no validation**: parsing fail 자주.
|
||||
- **No permission**: 매 sensitive operation 의 위험.
|
||||
- **State visibility 없음**: agent 의 wrong assumption.
|
||||
- **Sync tool only (long-running)**: timeout. Sub-agent / async.
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
- **정보 상태:** verified (concept-level).
|
||||
- **출처 신뢰도:** B (Anthropic MCP spec, SWE-agent Princeton paper, OpenAI function calling docs).
|
||||
- **검토 이유:** Manual cleanup. ACI design 가 evolving. MCP 의 standardization 가 진행 중.
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
- **기존 유사 문서:** [[AI-Tool-Composition-Deep]] (overlap), [[MCP-Server-Building]] (subset), [[AI-Anthropic-Skills-Patterns]] (related).
|
||||
- **처리 방식:** KEEP (focused on interface design).
|
||||
- **처리 이유:** ACI 가 design discipline. Tool composition 가 algorithm. MCP 가 specific protocol.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 | UPDATE | A |
|
||||
| 2026-05-09 | Manual cleanup — code pattern + design principle + MCP integration + 안티패턴 추가 | UPDATE | B |
|
||||
|
||||
Reference in New Issue
Block a user