Agent SDK 개요

설치

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

pip install claude-agent-sdk

SDK 옵션

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

• TypeScript SDK - Node.js 및 웹 애플리케이션용
• Python SDK - Python 애플리케이션 및 데이터 과학용
• 스트리밍 vs 단일 모드 - 입력 모드 및 모범 사례 이해하기

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 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에서 버그 또는 문제가 발생하면:

• TypeScript SDK: GitHub에서 문제 보고
• Python SDK: GitHub에서 문제 보고

변경 로그

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

• TypeScript SDK: CHANGELOG.md 보기
• Python SDK: CHANGELOG.md 보기

관련 리소스

• CLI 참조 - 완전한 CLI 설명서
• GitHub Actions 통합 - GitHub 워크플로우 자동화
• MCP 설명서 - Claude를 맞춤형 도구로 확장
• 일반적인 워크플로우 - 단계별 가이드
• 문제 해결 - 일반적인 문제 및 해결책