agents
매개변수를 사용하여 SDK에서 서브에이전트를 정의하고 사용하는 방법을 설명합니다.
개요
SDK를 사용할 때 서브에이전트는 두 가지 방법으로 정의할 수 있습니다:- 프로그래밍 방식 -
query()
옵션에서agents
매개변수 사용 (SDK 애플리케이션에 권장) - 파일시스템 기반 - 지정된 디렉토리(
.claude/agents/
)에 YAML 프론트매터가 있는 마크다운 파일 배치
agents
매개변수를 사용하는 프로그래밍 방식에 중점을 두며, 이는 SDK 애플리케이션에 더 통합된 개발 경험을 제공합니다.
서브에이전트 사용의 이점
컨텍스트 관리
서브에이전트는 메인 에이전트와 별도의 컨텍스트를 유지하여 정보 과부하를 방지하고 상호작용을 집중적으로 유지합니다. 이러한 격리는 전문화된 작업이 관련 없는 세부사항으로 메인 대화 컨텍스트를 오염시키지 않도록 보장합니다. 예시:research-assistant
서브에이전트는 수십 개의 파일과 문서 페이지를 탐색할 수 있으면서도 모든 중간 검색 결과로 메인 대화를 어지럽히지 않고 관련 발견사항만 반환할 수 있습니다.
병렬화
여러 서브에이전트가 동시에 실행되어 복잡한 워크플로우를 극적으로 가속화할 수 있습니다. 예시: 코드 리뷰 중에style-checker
, security-scanner
, test-coverage
서브에이전트를 동시에 실행하여 리뷰 시간을 몇 분에서 몇 초로 단축할 수 있습니다.
전문화된 지침과 지식
각 서브에이전트는 특정 전문 지식, 모범 사례, 제약 조건을 가진 맞춤형 시스템 프롬프트를 가질 수 있습니다. 예시:database-migration
서브에이전트는 SQL 모범 사례, 롤백 전략, 데이터 무결성 검사에 대한 상세한 지식을 가질 수 있으며, 이는 메인 에이전트의 지침에서는 불필요한 노이즈가 될 것입니다.
도구 제한
서브에이전트는 특정 도구로 제한되어 의도하지 않은 작업의 위험을 줄일 수 있습니다. 예시:doc-reviewer
서브에이전트는 Read와 Grep 도구에만 액세스할 수 있어 분석은 할 수 있지만 문서 파일을 실수로 수정하지 않도록 보장할 수 있습니다.
서브에이전트 생성
프로그래밍 정의 (권장)
agents
매개변수를 사용하여 코드에서 직접 서브에이전트를 정의하세요:
AgentDefinition 구성
필드 | 타입 | 필수 | 설명 |
---|---|---|---|
description | string | 예 | 이 에이전트를 언제 사용할지에 대한 자연어 설명 |
prompt | string | 예 | 에이전트의 역할과 행동을 정의하는 시스템 프롬프트 |
tools | string[] | 아니오 | 허용된 도구 이름 배열. 생략하면 모든 도구를 상속 |
model | 'sonnet' | 'opus' | 'haiku' | 'inherit' | 아니오 | 이 에이전트의 모델 오버라이드. 생략하면 메인 모델로 기본값 설정 |
파일시스템 기반 정의 (대안)
특정 디렉토리에 마크다운 파일로 서브에이전트를 정의할 수도 있습니다:- 프로젝트 수준:
.claude/agents/*.md
- 현재 프로젝트에서만 사용 가능 - 사용자 수준:
~/.claude/agents/*.md
- 모든 프로젝트에서 사용 가능
agents
매개변수를 통해)는 같은 이름의 파일시스템 기반 에이전트보다 우선합니다.
SDK가 서브에이전트를 사용하는 방법
Claude Agent SDK를 사용할 때 서브에이전트는 프로그래밍 방식으로 정의하거나 파일시스템에서 로드할 수 있습니다. Claude는:- 프로그래밍 에이전트 로드 - 옵션의
agents
매개변수에서 - 파일시스템 에이전트 자동 감지 -
.claude/agents/
디렉토리에서 (오버라이드되지 않은 경우) - 자동 호출 - 작업 매칭과 에이전트의
description
을 기반으로 - 전문화된 프롬프트 사용 및 도구 제한
- 별도 컨텍스트 유지 - 각 서브에이전트 호출에 대해
agents
매개변수를 통해)는 같은 이름의 파일시스템 기반 에이전트보다 우선합니다.
예시 서브에이전트
코드 리뷰어, 테스트 러너, 디버거, 보안 감사자를 포함한 서브에이전트의 포괄적인 예시는 메인 서브에이전트 가이드를 참조하세요. 이 가이드에는 효과적인 서브에이전트 생성을 위한 상세한 구성과 모범 사례가 포함되어 있습니다.SDK 통합 패턴
자동 호출
SDK는 작업 컨텍스트를 기반으로 적절한 서브에이전트를 자동으로 호출합니다. 에이전트의description
필드가 언제 사용되어야 하는지 명확히 나타내도록 하세요:
명시적 호출
사용자는 프롬프트에서 특정 서브에이전트를 요청할 수 있습니다:동적 에이전트 구성
애플리케이션의 필요에 따라 에이전트를 동적으로 구성할 수 있습니다:도구 제한
서브에이전트는tools
필드를 통해 제한된 도구 액세스를 가질 수 있습니다:
- 필드 생략 - 에이전트가 사용 가능한 모든 도구를 상속 (기본값)
- 도구 지정 - 에이전트가 나열된 도구만 사용 가능
일반적인 도구 조합
읽기 전용 에이전트 (분석, 검토):관련 문서
- 메인 서브에이전트 가이드 - 포괄적인 서브에이전트 문서
- SDK 구성 가이드 - 구성 접근 방식 개요
- 설정 - 구성 파일 참조
- 슬래시 명령 - 사용자 정의 명령 생성