Agent SDK 개요
Claude Code를 라이브러리로 사용하여 프로덕션 AI 에이전트 구축하기
에이전트는 자신의 단계를 계획하고 파일을 읽거나, 명령을 실행하거나, 코드를 편집하는 도구를 호출하여 작업을 완료하는 애플리케이션입니다. Agent SDK는 Claude Code를 강화하는 동일한 도구, 에이전트 루프, 및 컨텍스트 관리를 Python 및 TypeScript로 프로그래밍할 수 있도록 제공합니다.
Agent SDK를 다른 Claude 도구와 비교
Agent SDK, CLI, Client SDK, Managed Agents는 각각 다른 요구사항에 맞습니다. 구축 중인 것에 맞는 도구를 찾으려면 표를 사용하십시오.
| 다음의 경우... | 사용 | 이유 |
|---|---|---|
| 도구 루프를 직접 구현하지 않고 에이전트를 구축하는 경우 | Agent SDK | Python 또는 TypeScript에서 자신의 프로세스에서 에이전트 루프를 실행하는 라이브러리입니다. |
| 터미널에서 대화형 개발을 수행하거나 일회성 작업을 실행하는 경우 | Claude Code CLI | 일일 대화형 사용을 위해 구축된 터미널 인터페이스입니다. |
| API를 직접 호출하고 도구 루프를 직접 구현하는 경우 | Client SDK | Claude Code가 아닌 Anthropic API에 직접 액세스합니다. 도구 루프를 직접 구현합니다. |
| 자신의 샌드박스 또는 세션 인프라를 관리하지 않고 장기 실행 또는 비동기 에이전트를 실행하는 경우 | Managed Agents | 호스팅된 REST API로, Agent SDK와는 별개의 제품입니다. Anthropic이 에이전트와 샌드박스를 실행합니다. |
SDK는 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 팀이 동적 워크플로우를 사용하여 많은 서브에이전트를 한 번에 오케스트레이션하는 방법