2nd/10_Wiki/Topics/AI_and_ML/ACI.md

---
id: wiki-2026-0508-aci
title: ACI (Agent-Computer Interface)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Agent-Computer Interface, ACI, agent harness interface, tool interface, LLM tool design]
duplicate_of: none
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-09
github_commit: wikification-aci
inferred_by: Claude Opus 4.7 (manual cleanup 2026-05-09)
tech_stack:
  language: TS / Python
  framework: MCP / Anthropic SDK / OpenAI SDK / LangChain
---

# ACI (Agent-Computer Interface)

## 📌 한 줄 통찰 (The Karpathy Summary)
> **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)

### 정의
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 의 발견).

### 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)
- **추상화 수준 의 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)
- 부모: [[Agent-Architecture]] · [[Tool-Use-Function-Calling]] · [[Prompt_Engineering|Prompt-Engineering]]
- 응용: [[Claude-Code]]
- Related: [[Tool Composition — agent 가 tool 사용 / chain]] · [[Anthropic Skills — modular agent capability]] · [[Multi-Agent Coordination — orchestrator / handoff]]

## 🤖 LLM 활용 힌트 (How to Use This Knowledge)

**언제 이 지식을 쓰는가:**
- 새 LLM agent 의 tool design.
- MCP server 의 작성.
- Agent harness 의 evaluation / improvement.
- Production agent 의 quality 개선.
- Browser / desktop automation.
- Code agent (Cursor / Devin alternative) 디자인.

**언제 쓰면 안 되는가:**
- 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)
- **정보 상태:** verified (concept-level).
- **출처 신뢰도:** B (Anthropic MCP spec, SWE-agent Princeton paper, OpenAI function calling docs).
- **검토 이유:** Manual cleanup. ACI design 가 evolving. MCP 의 standardization 가 진행 중.

## 🧬 중복 검사 (Duplicate Check)
- **기존 유사 문서:** [[Tool Composition — agent 가 tool 사용 / chain]] (overlap), [[MCP-Server-Building]] (subset), [[Anthropic Skills — modular agent capability]] (related).
- **처리 방식:** KEEP (focused on interface design).
- **처리 이유:** ACI 가 design discipline. Tool composition 가 algorithm. MCP 가 specific protocol.

## 🕓 변경 이력 (Changelog)
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|------|-----------|-----------|--------|
| 2026-05-08 | P-Reinforce Phase 1 정규화 | UPDATE | A |
| 2026-05-09 | Manual cleanup — code pattern + design principle + MCP integration + 안티패턴 추가 | UPDATE | B |