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 콘솔에서 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 Agent SDK로 구축한 에이전트를 포함하여 타사 개발자가 자신의 제품에 Claude.ai 속도 제한을 적용하도록 허용하지 않습니다. 대신 이 문서에 설명된 API 키 인증 방법을 사용하세요.

​
전체 Claude Code 기능 지원

SDK는 동일한 파일 시스템 기반 구성을 활용하여 Claude Code에서 사용 가능한 모든 기본 기능에 액세스할 수 있습니다:
  • 서브에이전트: ./.claude/agents/에 Markdown 파일로 저장된 특화된 에이전트 시작
  • 에이전트 스킬: ./.claude/skills/에 SKILL.md 파일로 저장된 특화된 기능으로 Claude 확장
  • 훅: ./.claude/settings.json에 구성된 도구 이벤트에 응답하는 맞춤형 명령 실행
  • 슬래시 명령: ./.claude/commands/에 Markdown 파일로 정의된 맞춤형 명령 사용
  • 플러그인: plugins 옵션을 사용하여 맞춤형 플러그인을 프로그래밍 방식으로 로드하여 Claude Code를 맞춤형 명령, 에이전트, 스킬, 훅 및 MCP 서버로 확장합니다. 자세한 내용은 플러그인을 참조하세요.
  • 메모리 (CLAUDE.md): 프로젝트 디렉토리의 CLAUDE.md 또는 .claude/CLAUDE.md 파일, 또는 사용자 수준 지침을 위한 ~/.claude/CLAUDE.md 파일을 통해 프로젝트 컨텍스트를 유지합니다. 이러한 파일을 로드하려면 옵션에서 settingSources: ['project'] (TypeScript) 또는 setting_sources=["project"] (Python)을 명시적으로 설정해야 합니다. 자세한 내용은 시스템 프롬프트 수정을 참조하세요.
이러한 기능은 동일한 파일 시스템 위치에서 읽어 Claude Code 대응 기능과 동일하게 작동합니다.

​
시스템 프롬프트

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

​
도구 권한

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

​
모델 컨텍스트 프로토콜 (MCP)

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

​
버그 보고

Agent SDK에서 버그 또는 문제가 발생하면:

​
변경 로그

SDK 업데이트, 버그 수정 및 새로운 기능에 대한 전체 변경 로그를 확인하세요:

​
관련 리소스