| disable-model-invocation | true |
| name | claude-agent-sdk |
| description | Builds Claude Agent SDK agents in Python. Use when creating custom tools, hooks, sub-agents, or MCP integrations with the Agent SDK. Python 에이전트 구축 시 사용. |
Claude Agent SDK
Python 기반 독립 실행형 AI 에이전트 코드 생성.
vs Claude Code 서브에이전트 정의:
| 항목 | .claude/agents/*.md (harness-engineering 참조) | claude-agent-sdk |
|---|
| 결과물 | 에이전트 정의 markdown | *.py 파일 |
| 실행 환경 | Claude Code 내부 | 독립 Python 앱 |
| 용도 | 작업 위임 | 프로덕션 자동화 |
Instructions
워크플로우 1: 새 에이전트 프로젝트
-
용도 파악
- 무엇을 자동화할 것인가?
- 어떤 도구가 필요한가? (파일, 명령, 웹, 커스텀)
- 서브에이전트 필요 여부
-
템플릿 선택
| 용도 | 템플릿 |
|---|
| 최소 시작 | templates/basic-agent.py |
| 커스텀 도구 | templates/tool-agent.py |
| 훅 (검증/로깅) | templates/hook-agent.py |
| 서브에이전트 | templates/multi-agent.py |
| 프로덕션 | templates/production-agent.py |
-
프로젝트 구조 생성
{project}/
├── pyproject.toml
├── agent.py # 메인 에이전트
├── tools.py # 커스텀 도구 (선택)
└── hooks.py # 훅 정의 (선택)
-
코드 생성: 템플릿 기반으로 사용자 요구에 맞게 수정
워크플로우 2: 기능 추가
기존 에이전트에 기능 추가 시:
-
키워드 → 리소스 매칭
| 키워드 | 리소스 |
|---|
| 설치, pyproject | resources/01-setup.md |
| query, 기본, 옵션 | resources/02-query-options.md |
| 도구, @tool | resources/03-custom-tools.md |
| 훅, hook, 검증 | resources/04-hooks.md |
| 서브에이전트, 위임 | resources/05-subagents.md |
| 세션, resume | resources/06-sessions.md |
| MCP, playwright | resources/07-mcp.md |
-
리소스 로드 → 패턴 적용
워크플로우 3: 코드 리뷰/개선
기존 에이전트 코드 분석 요청 시:
- 구조 확인: 현재 사용 중인 기능 파악
- 개선점 제안:
- 에러 핸들링 추가
- 훅으로 검증/로깅
- 서브에이전트로 분리
- 세션 관리 추가
핵심 패턴
기본 query()
from claude_agent_sdk import query, ClaudeAgentOptions
async for msg in query(
prompt="작업 지시",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Bash"],
cwd="/path/to/project",
permission_mode="acceptEdits"
)
):
if hasattr(msg, "result"):
print(msg.result)
커스텀 도구
from claude_agent_sdk import tool, create_sdk_mcp_server
@tool("search", "검색 수행", {"query": str})
async def search(args):
return {"content": [{"type": "text", "text": f"결과: {args['query']}"}]}
server = create_sdk_mcp_server("my-tools", "1.0.0", tools=[search])
훅
async def validate_bash(input_data, tool_use_id, context):
cmd = input_data.get("tool_input", {}).get("command", "")
if "rm -rf" in cmd:
return {"decision": "block", "reason": "위험한 명령어"}
return {}
options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[validate_bash])]}
)
중요 원칙
- allowed_tools 최소화: 필요한 도구만 허가
- permission_mode 신중히:
bypassPermissions는 프로덕션 전용
- 에러 핸들링:
try/except로 graceful 처리
- 세션 활용: 장기 작업은 session_id 저장 후 resume
Technical Details
REFERENCE.md: SDK API 전체 개요resources/: 기능별 상세 패턴templates/: 완전한 에이전트 코드
