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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, inferred_by, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	inferred_by	tech_stack
wiki-2026-0508-aci	ACI (Agent-Computer Interface)	10_Wiki/Topics	verified	self	Agent-Computer Interface ACI agent harness interface tool interface LLM tool design	none	B	0.85	conceptual	aci agent llm tool-design harness infrastructure prompt-engineering mcp		2026-05-09	wikification-aci	Claude Opus 4.7 (manual cleanup 2026-05-09)	language framework TS / Python 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)

{
  "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.

// 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 만.

# Static (옛)
all_tools = [tool1, tool2, ..., tool100]

# Dynamic (modern)
relevant_tools = router(query)   # 매 query 의 relevant 5 tool 만.

💻 코드 패턴 (Code Patterns)

Anthropic tool use

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

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)

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)

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

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
• 응용: 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