Claude Code SDK가 Claude Agent SDK로 이름이 변경되었습니다. 기존 SDK에서 마이그레이션하는 경우 마이그레이션 가이드를 참조하세요.

​
설치

npm install @anthropic-ai/claude-agent-sdk

​
SDK 옵션

Claude Agent SDK는 다양한 사용 사례에 맞게 여러 형태로 제공됩니다:

​
Claude Agent SDK를 사용하는 이유는?

Claude Code를 구동하는 에이전트 하네스 위에 구축된 Claude Agent SDK는 프로덕션 준비 에이전트를 구축하는 데 필요한 모든 구성 요소를 제공합니다. 다음을 포함한 Claude Code에서 수행한 작업을 활용합니다:
  • 컨텍스트 관리: 에이전트가 컨텍스트를 소진하지 않도록 하는 자동 압축 및 컨텍스트 관리
  • 풍부한 도구 생태계: 파일 작업, 코드 실행, 웹 검색 및 MCP 확장성
  • 고급 권한: 에이전트 기능에 대한 세밀한 제어
  • 프로덕션 필수 요소: 내장된 오류 처리, 세션 관리 및 모니터링
  • 최적화된 Claude 통합: 자동 프롬프트 캐싱 및 성능 최적화

​
SDK로 무엇을 구축할 수 있나요?

다음은 생성할 수 있는 에이전트 유형의 예입니다: 코딩 에이전트:
  • 프로덕션 문제를 진단하고 수정하는 SRE 에이전트
  • 취약점에 대해 코드를 감사하는 보안 검토 봇
  • 인시던트를 분류하는 온콜 엔지니어링 어시스턴트
  • 스타일과 모범 사례를 적용하는 코드 검토 에이전트
비즈니스 에이전트:
  • 계약서와 규정 준수를 검토하는 법무 어시스턴트
  • 보고서와 예측을 분석하는 재무 어드바이저
  • 기술적 문제를 해결하는 고객 지원 에이전트
  • 마케팅 팀을 위한 콘텐츠 제작 어시스턴트

​
핵심 개념

​
인증

기본 인증의 경우 Claude Console에서 Claude API 키를 검색하고 ANTHROPIC_API_KEY 환경 변수를 설정하세요. SDK는 또한 서드파티 API 제공업체를 통한 인증을 지원합니다:
  • Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1 환경 변수를 설정하고 AWS 자격 증명을 구성하세요
  • Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1 환경 변수를 설정하고 Google Cloud 자격 증명을 구성하세요
서드파티 제공업체에 대한 자세한 구성 지침은 Amazon Bedrock 및 Google Vertex AI 문서를 참조하세요.

​
전체 Claude Code 기능 지원

SDK는 동일한 파일 시스템 기반 구성을 활용하여 Claude Code에서 사용할 수 있는 모든 기본 기능에 대한 액세스를 제공합니다:
  • 서브에이전트: ./.claude/agents/에 Markdown 파일로 저장된 전문 에이전트를 실행합니다
  • 훅: 도구 이벤트에 응답하는 ./.claude/settings.json에 구성된 사용자 정의 명령을 실행합니다
  • 슬래시 명령: ./.claude/commands/에 Markdown 파일로 정의된 사용자 정의 명령을 사용합니다
  • 메모리 (CLAUDE.md): 지속적인 지침과 컨텍스트를 제공하는 CLAUDE.md 파일을 통해 프로젝트 컨텍스트를 유지합니다
이러한 기능들은 동일한 파일 시스템 위치에서 읽어와서 Claude Code 대응 기능과 동일하게 작동합니다.

​
시스템 프롬프트

시스템 프롬프트는 에이전트의 역할, 전문성 및 동작을 정의합니다. 여기서 구축하고 있는 에이전트의 종류를 지정합니다.

​
도구 권한

세밀한 권한으로 에이전트가 사용할 수 있는 도구를 제어합니다:
  • allowedTools - 특정 도구를 명시적으로 허용
  • disallowedTools - 특정 도구를 차단
  • permissionMode - 전체 권한 전략 설정

​
Model Context Protocol (MCP)

MCP 서버를 통해 사용자 정의 도구 및 통합으로 에이전트를 확장합니다. 이를 통해 데이터베이스, API 및 기타 외부 서비스에 연결할 수 있습니다.

​
버그 신고

Agent SDK에서 버그나 문제가 발생하는 경우:

​
관련 리소스