obsidian/dev/claude-agent-sdk.md

title, updated, tags

title	updated	tags
Claude Agent SDK와 Harness	2026-03-25	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(서브에이전트)

기본 사용

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로 동작.

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