Agent SDK 개요
Claude Code를 라이브러리로 사용하여 프로덕션 AI 에이전트 구축하기
에이전트는 자신의 단계를 계획하고 파일을 읽거나, 명령을 실행하거나, 코드를 편집하는 도구를 호출하여 작업을 완료하는 애플리케이션입니다. Agent SDK는 Claude Code를 강화하는 동일한 도구, 에이전트 루프, 및 컨텍스트 관리를 Python 및 TypeScript로 프로그래밍할 수 있도록 제공합니다.
Agent SDK를 다른 Claude 도구와 비교
Agent SDK, CLI, Client SDK, Managed Agents는 에이전트를 누가 실행하는지, 무엇이 기본으로 제공되는지, 어떻게 접근하는지에 따라 다릅니다. 에이전트를 구축하고 실행하려는 방식과 일치하는 행을 찾으십시오.
| 원하는 작업 | 사용 | 제공되는 것 |
|---|---|---|
| Claude Code의 에이전트를 자신이 운영하는 프로세스에서 자신의 Python 또는 TypeScript 애플리케이션에 포함시키기 | Agent SDK | Claude Code 바이너리를 실행하는 라이브러리로, 기본 제공 도구, 권한, 세션, 훅 등 Claude Code의 기능을 포함합니다. |
| 터미널에서 대화형 개발을 수행하거나 일회성 작업 실행 | Claude Code CLI | 일일 대화형 사용을 위해 구축된 터미널 인터페이스입니다. |
| 자신의 코드에서 Claude API를 직접 호출 | Client SDK | 모든 Client SDK 언어에서 Claude API에 직접 액세스합니다. 도구 루프를 직접 작성하거나 Client SDK의 베타 도구 실행기가 이를 구동하도록 할 수 있습니다. |
| Anthropic이 에이전트를 호스팅하고 Claude API를 통해 구성 | Managed Agents | 에이전트 루프를 실행하는 호스팅된 에이전트 하네스로, Anthropic 관리 클라우드 샌드박스 또는 자신의 인프라에 있는 자체 호스팅 샌드박스의 세션을 포함합니다. 자신의 언어용 SDK, ant CLI 또는 REST API에서 사용합니다. |
Python 또는 TypeScript 이외의 언어에서 동일한 에이전트 루프를 구동하려면 -p 플래그 및 --output-format json과 함께 CLI를 서브프로세스로 실행하십시오.
기능
이러한 Claude Code 기능은 SDK에서 사용 가능합니다:
| 기능 | 기능 | 자세히 알아보기 |
|---|---|---|
| 기본 제공 도구 | 파일 읽기, 쓰기, 편집, 명령 실행 및 웹 검색 | 도구 참조 |
| Hooks | 에이전트 라이프사이클의 주요 지점에서 사용자 정의 코드 실행 | Hooks |
| Subagents | 집중된 부작업을 위해 특화된 에이전트 생성 | Subagents |
| MCP | Model Context Protocol을 통해 외부 도구 및 데이터 소스 연결 | MCP |
| 권한 | 어떤 도구가 자동으로 실행되는지, 어떤 도구가 승인이 필요한지 제어 | 권한 |
| 세션 | 교환 전체에서 컨텍스트 유지, 나중에 재개 또는 포크 | 세션 |
| Skills, 명령 및 메모리 | 프로젝트의 .claude/ 및 ~/.claude/에서 자동으로 로드, Claude Code와 동일 |
Skills, 명령, 메모리, 구성 로드 |
| Plugins | Skills, 에이전트, Hooks 및 MCP 서버를 패키징하고 로컬 경로로 로드 | Plugins |
시작하기
빠른 시작을 따라 SDK를 설치하고, API 키를 설정하고, 기존 코드의 버그를 찾아 수정하는 첫 번째 에이전트를 구축합니다.
변경 로그
SDK 업데이트, 버그 수정 및 새로운 기능에 대한 전체 변경 로그를 보십시오:
- TypeScript SDK: CHANGELOG.md 보기
- Python SDK: CHANGELOG.md 보기
버그 보고
Agent SDK에서 버그 또는 문제가 발생하면:
- TypeScript SDK: GitHub에서 문제 보고
- Python SDK: GitHub에서 문제 보고
브랜딩 지침
Claude Agent SDK를 통합하는 파트너의 경우 Claude 브랜딩 사용은 선택 사항입니다. 제품에서 Claude를 참조할 때:
허용됨:
- "Claude Agent" (드롭다운 메뉴에 권장)
- "Claude" (이미 "Agents"로 표시된 메뉴 내)
- "{YourAgentName} Powered by Claude" (기존 에이전트 이름이 있는 경우)
허용되지 않음:
- "Claude Code" 또는 "Claude Code Agent"
- Claude Code 브랜드 ASCII 아트 또는 Claude Code를 모방하는 시각적 요소
제품은 자체 브랜딩을 유지해야 하며 Claude Code 또는 Anthropic 제품으로 보이지 않아야 합니다. 브랜딩 준수에 대한 질문은 Anthropic 영업팀에 문의하십시오.
라이선스 및 약관
Claude Agent SDK의 사용은 Anthropic의 상용 서비스 약관에 의해 관리되며, 이는 자신의 고객 및 최종 사용자가 사용할 수 있도록 제공하는 제품 및 서비스를 강화하기 위해 사용할 때도 포함됩니다. 단, 특정 구성 요소 또는 종속성이 해당 구성 요소의 LICENSE 파일에 표시된 대로 다른 라이선스로 적용되는 경우는 제외합니다.
다음 단계
이러한 리소스는 Agent SDK로 구축하기 위한 더 깊이 있는 기술 세부 정보와 예제 프로젝트를 다룹니다.
- 빠른 시작: 버그를 찾고 수정하는 첫 번째 에이전트 구축하기
- 마이그레이션 가이드: Claude Code SDK 패키지에서 Agent SDK로 마이그레이션하기
- 에이전트 루프: Claude가 계획하고, 도구를 호출하고, 작업이 완료되었을 때를 결정하는 방법
- 예제 에이전트: 로컬 개발을 위한 데모 앱
- TypeScript SDK: 전체 TypeScript API 참조 및 예제
- Python SDK: 전체 Python API 참조 및 예제
- 에이전트 하네스 설계: Claude Code 팀이 동적 워크플로우를 사용하여 많은 서브에이전트를 한 번에 오케스트레이션하는 방법