- Claude Agent SDK는 Claude Code의 도구 실행, 에이전트 루프, 컨텍스트 관리를 Python·TypeScript 코드에서 제어하게 해 파일 읽기, 명령 실행, 웹 검색, 코드 편집을 자동화함
- 기본 도구로 Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion을 제공해 코드베이스 탐색부터 사용자 확인 질문까지 별도 실행 계층 없이 처리할 수 있음
- 훅, 서브에이전트, MCP, 권한, 세션을 조합하면 파일 변경 감사 로그, 코드 리뷰 전용 서브에이전트, Playwright 기반 브라우저 자동화, 읽기 전용 분석 에이전트 같은 구성이 가능함
- 설치는
@anthropic-ai/claude-agent-sdk또는claude-agent-sdk로 진행하며, Python은 3.10 이상이 필요하고 TypeScript SDK는 플랫폼용 네이티브 Claude Code 바이너리를 선택 의존성으로 포함함 - Agent SDK는 도구 루프를 직접 구현하는 Anthropic Client SDK와 달리 내장 도구 실행을 제공하며, Managed Agents처럼 Anthropic 인프라가 아니라 사용자 프로세스와 인프라에서 실행됨
Claude Agent SDK가 맡는 범위
- Claude Agent SDK는 Claude Code를 구동하는 도구, 에이전트 루프, 컨텍스트 관리를 Python과 TypeScript에서 사용할 수 있게 함
- 에이전트는 파일 읽기, 명령 실행, 웹 검색, 코드 편집을 수행할 수 있음
- 내장 도구 실행이 포함돼 사용자가 별도 도구 실행 계층을 직접 만들지 않아도 에이전트가 작업을 시작할 수 있음
- 기본 예시는
auth.py의 버그를 찾고 고치는 작업에Read,Edit,Bash도구를 허용함
설치와 인증 흐름
- 언어별 패키지로 설치함
- TypeScript:
npm install @anthropic-ai/claude-agent-sdk - Python:
pip install claude-agent-sdk
- TypeScript:
- Python 패키지는 Python 3.10 이상이 필요함
No matching distribution found for claude-agent-sdk오류가 나면 인터프리터가 3.10보다 오래된 버전일 수 있음- macOS 또는 Linux에서는
python3 --version, Windows에서는py --version으로 확인함
- TypeScript SDK는 플랫폼용 네이티브 Claude Code 바이너리를 선택 의존성으로 포함하므로 Claude Code를 별도로 설치할 필요가 없음
- API 키는 Console에서 발급받아
ANTHROPIC_API_KEY환경 변수로 설정함 - 서드파티 API 제공자 인증도 지원함
- Amazon Bedrock:
CLAUDE_CODE_USE_BEDROCK=1설정 후 AWS 자격 증명 구성 - Claude Platform on AWS:
CLAUDE_CODE_USE_ANTHROPIC_AWS=1,ANTHROPIC_AWS_WORKSPACE_ID설정 후 AWS 자격 증명 구성 - Google Vertex AI:
CLAUDE_CODE_USE_VERTEX=1설정 후 Google Cloud 자격 증명 구성 - Microsoft Azure:
CLAUDE_CODE_USE_FOUNDRY=1설정 후 Azure 자격 증명 구성
- Amazon Bedrock:
- Anthropic은 사전 승인 없이는 서드파티 개발자가 Claude Agent SDK 기반 제품에
claude.ai로그인이나 rate limit을 제공하는 것을 허용하지 않음
기본 도구와 에이전트 기능
- SDK는 Claude Code의 주요 기능을 코드에서 다룰 수 있게 함
- 내장 도구
- 훅
- 서브에이전트
- MCP
- 권한
- 세션
- 주요 내장 도구는 다음 역할을 수행함
Read: 작업 디렉터리 안의 파일 읽기Write: 새 파일 생성Edit: 기존 파일에 정밀한 편집 적용Bash: 터미널 명령, 스크립트, git 작업 실행Monitor: 백그라운드 스크립트를 감시하고 각 출력 줄에 이벤트로 반응Glob:**/*.ts,src/**/*.py같은 패턴으로 파일 찾기Grep: 정규식으로 파일 내용 검색WebSearch: 최신 정보를 웹에서 검색WebFetch: 웹 페이지 콘텐츠 가져오기와 파싱AskUserQuestion: 복수 선택 옵션으로 사용자에게 확인 질문하기
- 예시 에이전트는
Read,Glob,Grep를 허용해 코드베이스의 TODO 주석을 찾아 요약함
훅, 서브에이전트, MCP
- 훅(hook) 은 에이전트 생명주기의 주요 지점에서 사용자 코드를 실행함
- 콜백 함수로 에이전트 동작을 검증, 기록, 차단, 변환할 수 있음
- 사용 가능한 훅에는
PreToolUse,PostToolUse,Stop,SessionStart,SessionEnd,UserPromptSubmit등이 있음 - 예시는
PostToolUse에서Edit|Write작업을 감지해audit.log에 파일 변경을 기록함
- 서브에이전트는 집중된 하위 작업을 처리하는 특화 에이전트임
- 메인 에이전트가 작업을 위임하고 서브에이전트가 결과를 반환함
- 커스텀 에이전트는 설명, 프롬프트, 사용할 도구로 정의함
- 서브에이전트 호출은
Agent도구를 통해 이뤄지므로 자동 승인하려면allowedTools에Agent를 포함해야 함 - 서브에이전트 컨텍스트 안의 메시지는
parent_tool_use_id필드를 포함해 어떤 서브에이전트 실행에 속하는지 추적할 수 있음
- Model Context Protocol(MCP) 로 데이터베이스, 브라우저, API 등 외부 시스템에 연결할 수 있음
- Model Context Protocol 서버 목록에서 관련 서버를 확인할 수 있음
- 예시는 Playwright MCP server를 연결해 에이전트에 브라우저 자동화 기능을 제공함
권한과 세션 관리
- 권한 설정은 에이전트가 사용할 수 있는 도구를 제한함
- 안전한 작업은 허용하고, 위험한 작업은 차단하며, 민감한 동작에는 승인을 요구할 수 있음
- 예시는
Read,Glob,Grep만 사전 승인해 코드를 분석하되 수정하지 않는 읽기 전용 에이전트를 구성함
AskUserQuestion도구와 대화형 승인 프롬프트는 사용자 입력 처리 흐름에서 함께 사용됨- 세션은 여러 교환에 걸쳐 컨텍스트를 유지함
- Claude는 읽은 파일, 수행한 분석, 대화 기록을 기억함
- 이후 같은 세션을 재개하거나 다른 접근을 탐색하기 위해 포크할 수 있음
- 예시는 첫 번째 쿼리에서
session_id를 얻고, 두 번째 쿼리에서resume=session_id로 같은 컨텍스트를 이어감
Claude Code 설정 지원
- SDK는 Claude Code의 파일시스템 기반 설정을 지원함
- 기본 옵션에서는 작업 디렉터리의
.claude/와~/.claude/에서 설정을 로드함 - 로드할 설정 소스를 제한하려면 Python에서는
setting_sources, TypeScript에서는settingSources옵션을 사용함 - 지원 기능과 위치는 다음과 같음
- Skills: Claude가 자동 사용하거나
/name으로 호출하는 특화 기능,.claude/skills/*/SKILL.md - Commands: 레거시 형식의 커스텀 명령,
.claude/commands/*.md - Memory: 프로젝트 컨텍스트와 지시사항,
CLAUDE.md또는.claude/CLAUDE.md - Plugins: skills, agents, hooks, MCP servers 확장,
plugins옵션으로 프로그래밍 방식 구성
- Skills: Claude가 자동 사용하거나
다른 Claude 도구와의 차이
- Anthropic Client SDK는 직접 API 접근을 제공하며, 사용자가 프롬프트를 보내고 도구 실행을 직접 구현함
- Agent SDK에서는 Claude가 도구 처리를 자율적으로 수행함
- Client SDK에서는 사용자가 도구 루프를 구현함
- Agent SDK는 Claude에 내장 도구 실행을 제공함
- 용도별 선택 기준은 다음과 같음
- 대화형 개발: CLI
- CI/CD 파이프라인: SDK
- 커스텀 애플리케이션: SDK
- 일회성 작업: CLI
- 프로덕션 자동화: SDK
- 여러 팀은 일상 개발에는 CLI를, 프로덕션에는 SDK를 함께 사용하며 워크플로는 서로 직접 옮길 수 있음
- Managed Agents는 Anthropic이 에이전트와 샌드박스를 실행하는 호스팅 REST API임
- Agent SDK는 사용자 프로세스 안에서 에이전트 루프를 실행하는 라이브러리임
- 실행 위치: Agent SDK는 사용자 프로세스와 인프라, Managed Agents는 Anthropic 관리 인프라
- 인터페이스: Agent SDK는 Python 또는 TypeScript 라이브러리, Managed Agents는 REST API
- 작업 대상: Agent SDK는 사용자 인프라의 파일, Managed Agents는 세션별 관리형 샌드박스
- 세션 상태: Agent SDK는 파일시스템의 JSONL, Managed Agents는 Anthropic 호스팅 이벤트 로그
- 커스텀 도구: Agent SDK는 프로세스 내 Python 또는 TypeScript 함수, Managed Agents는 Claude가 도구를 트리거하고 사용자가 실행 결과를 반환
- 적합한 용도: Agent SDK는 로컬 프로토타이핑과 파일시스템·서비스에 직접 접근하는 에이전트, Managed Agents는 샌드박스나 세션 인프라를 운영하지 않는 프로덕션 에이전트와 장기 실행·비동기 세션
- 일반적인 경로는 Agent SDK로 로컬 프로토타입을 만든 뒤 프로덕션에서는 Managed Agents로 옮기는 방식임
변경 로그, 버그 신고, 브랜딩
- SDK 업데이트, 버그 수정, 새 기능은 각 저장소의 변경 로그에서 확인함
- TypeScript SDK: CHANGELOG.md
- Python SDK: CHANGELOG.md
- 버그나 이슈는 GitHub에서 신고함
- TypeScript SDK: GitHub issues
- Python SDK: GitHub issues
- 파트너가 Claude Agent SDK를 통합할 때 Claude 브랜딩 사용은 선택 사항임
- 허용: “Claude Agent”, “Claude”, “Powered by Claude”
- 금지: “Claude Code”, “Claude Code Agent”, Claude Code 브랜드 ASCII 아트 또는 Claude Code를 모방한 시각 요소
- 제품은 자체 브랜딩을 유지해야 하며 Claude Code 또는 Anthropic 제품처럼 보여서는 안 됨
- Claude Agent SDK 사용에는 Anthropic’s Commercial Terms of Service가 적용됨
- 특정 컴포넌트나 의존성이 해당 컴포넌트의 LICENSE 파일에서 다른 라이선스를 명시한 경우는 예외임