refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,423 @@
|
||||
---
|
||||
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 |
|
||||
Reference in New Issue
Block a user