Agent SDK 서브에이전트
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
서브에이전트는 격리된 컨텍스트에서 전문 작업을 수행하는 하위 에이전트입니다. 메인 에이전트 context를 비대하게 만들지 않고 연구·리뷰·테스트 실행 등을 위임합니다.
핵심 개념
| 이점 | 설명 |
|---|---|
| Context isolation | 새 대화, 요약만 부모에 반환 |
| Parallelization | 복수 서브태스크 동시 |
| Specialized instructions | 전용 system prompt·지식 |
| Tool restrictions | 읽기 전용 등 최소 권한 |
Agent teams(CLI)와 다름: teams는 독립 인스턴스 간 task list·직접 메시징.
상세
프로그램 정의 (권장)
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Review the auth module and run related tests",
options: {
allowedTools: ["Read", "Grep", "Glob", "Agent"],
agents: {
"code-reviewer": {
description: "Expert code review specialist. Use for quality and security reviews.",
prompt: "You are a code review specialist. Focus on bugs, security, maintainability.",
tools: ["Read", "Grep", "Glob"],
model: "sonnet"
},
"test-runner": {
description: "Runs and analyzes test suites.",
prompt: "You are a test execution specialist.",
tools: ["Bash", "Read", "Grep"]
}
}
}
})) {
if ("result" in message) console.log(message.result);
}
AgentDefinition 필드
| 필드 | 필수 | 설명 |
|---|---|---|
description |
Yes | 언제 쓸지 자연어 |
prompt |
Yes | 서브에이전트 시스템 프롬프트 |
tools / disallowedTools |
No | 허용·차단 도구 (MCP 패턴 포함) |
model |
No | alias 또는 full ID, inherit |
skills |
No | 시작 시 preload skill |
memory |
No | user/project/local |
mcpServers |
No | 이름 또는 인라인 설정 |
initialPrompt |
No | 메인 스레드 에이전트로 쓸 때 첫 턴 (서브 호출 시 무시) |
maxTurns |
No | 턴 상한 |
background |
No | non-blocking 백그라운드 |
effort |
No | reasoning effort |
파일시스템 정의
.claude/agents/*.md는 settingSources에 project 등이 있을 때 로드됩니다. 프로그램 정의와 병행 가능합니다.
상속
서브에이전트는 부모의 일부 설정(권한 정책, advisor pairing 등)을 상속하고, tools/model은 정의로 덮어씁니다. 공식 "What subagents inherit" 표를 확인하세요.
호출
- 자동: description 기반으로 Claude가 Agent 도구 사용
- 명시: 프롬프트에서 에이전트 지정
- 동적 구성: 런타임에 agents 맵 조립
메인에 Agent 도구가 허용되어야 위임됩니다.
감지·재개
메시지 스트림에서 subagent 관련 tool_use·system 이벤트로 위임을 감지합니다. 백그라운드/장시간 작업은 resume API로 이어갈 수 있습니다(버전별 API 확인).
도구 제한 조합 예
- 리뷰어: Read/Grep/Glob only
- 테스터: Bash + Read
- 조사: 광범위 read, write 금지
문제 해결
| 증상 | 조치 |
|---|---|
| 위임 안 함 | Agent 허용, description 명확화 |
| 파일 에이전트 미로드 | settingSources·경로 |
| Windows 긴 prompt 실패 | prompt 길이·파일 기반 정의 |
체크리스트
- agents 맵에 description·prompt 필수 필드
- 메인
allowedTools에 Agent 포함 - 최소 권한 tools 설정
- 서브 vs agent teams 요구사항 구분