---
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