dev: Claude Agent SDK와 Harness 개념 정리

dev/claude-agent-sdk.md

@@ -0,0 +1,113 @@
+---
+title: Claude Agent SDK와 Harness
+updated: 2026-03-25
+tags: [claude, agent-sdk, harness, mcp]
+---
+
+## Harness란
+
+Claude를 원하는 방식으로 동작하게 감싸는 프로그램(껍데기).
+같은 Claude라도 어떤 도구를 주고, 어떤 규칙을 걸고, 어떤 UI로 감싸느냐에 따라 다른 에이전트가 됨.
+
+| harness 예시 | 설명 |
+|-------------|------|
+| Claude Code (CLI) | Anthropic이 코딩용으로 만든 harness |
+| Claude.ai (웹) | 채팅용 harness |
+| 커스텀 인프라 봇 | kubectl/incus 도구 붙인 인프라 관리 harness |
+
+## Claude Agent SDK
+
+Claude Code의 내장 도구를 라이브러리로 사용하여 자체 harness를 만들 수 있음.
+
+### 설치
+
+- Python: `pip install claude-agent-sdk`
+- TypeScript: `npm install @anthropic-ai/claude-agent-sdk`
+
+### 내장 도구
+
+Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, Agent(서브에이전트)
+
+### 기본 사용
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
+
+async for message in query(
+    prompt="작업 지시",
+    options=ClaudeAgentOptions(
+        cwd="/home/kaffa",
+        allowed_tools=["Read", "Bash", "Glob", "Grep"],
+        permission_mode="acceptEdits",
+        max_turns=20,
+    )
+):
+    if isinstance(message, ResultMessage):
+        print(message.result)
+```
+
+### 서브에이전트를 harness로
+
+`AgentDefinition`으로 역할별 서브에이전트 정의. 각 서브에이전트가 전용 도구 + 전용 프롬프트를 가진 독립 harness로 동작.
+
+```python
+from claude_agent_sdk import AgentDefinition
+
+agents={
+    "infra-checker": AgentDefinition(
+        description="K3s/Incus 인프라 점검",
+        prompt="kubectl, incus로 상태 확인 후 보고",
+        tools=["Bash", "Read"]
+    ),
+    "apisix-manager": AgentDefinition(
+        description="APISIX 라우트/SSL 관리",
+        prompt="APISIX Admin API로 관리. SSL ID는 도메인 MD5 앞 16자리",
+        tools=["Bash", "Read", "Write"]
+    ),
+    "obsidian-writer": AgentDefinition(
+        description="Obsidian Vault 문서 작성/업데이트",
+        prompt="~/obsidian에 컨벤션 맞춰 기록",
+        tools=["Read", "Write", "Edit", "Bash"]
+    ),
+}
+```
+
+### 에이전트 간 호출
+
+| 방식 | 구조 | 용도 |
+|------|------|------|
+| `Agent` 도구 | 같은 프로세스 안 서브에이전트 | 역할 분담 |
+| MCP 서버 | 별도 프로세스 간 연결 | 독립 harness 연동 |
+| HTTP/웹훅 | API로 호출 | n8n, 외부 시스템 연동 |
+
+- `tools`에 `Agent` 포함 → 서브에이전트가 다른 서브에이전트 호출 가능
+- MCP 서버로 연결 → 별도 harness 간 통신 가능
+
+### 실행 방식
+
+- CLI: `uv run agent.py "명령"`
+- 크론/스케줄: 정기 점검, 자동 보고
+- 웹훅/봇: Discord, Slack, n8n 워크플로우 연결
+- Claude Code 내부: 서브에이전트로 동작
+
+### vs Claude API 직접 사용
+
+| | Agent SDK | Claude API |
+|---|---|---|
+| 내장 도구 | 파일/셸/웹 등 제공 | 직접 구현 |
+| 유연성 | 중간 | 최대 |
+| 용도 | 코딩/인프라 에이전트 | 완전 커스텀 에이전트 |
+
+### vs Open Interpreter
+
+| | Agent SDK | Open Interpreter |
+|---|---|---|
+| LLM | Claude 전용 | 다양한 LLM |
+| 도구 | 구조화된 도구 체계 | 코드 실행 중심 |
+| MCP | 지원 | 미지원 |
+
+## 참고
+
+- Agent SDK Python: `https://github.com/anthropics/claude-agent-sdk-python`
+- Agent SDK TypeScript: `https://github.com/anthropics/claude-agent-sdk-typescript`
+- [[claude-code-setup]] — Claude Code 설정 및 MCP