Agent SDK 개요(Agent SDK overview)

Agent SDK 개요(Agent SDK overview)

Agent SDK는 Claude Code를 구동하는 것과 같은 도구·에이전트 루프·컨텍스트 관리를 Python과 TypeScript에서 프로그래밍 가능하게 만든 라이브러리예요. 에이전트는 스스로 단계를 계획하고 파일을 읽거나 명령을 실행하는 도구를 호출해 작업을 완료하는 애플리케이션이에요. 자신의 프로세스 안에서 에이전트 루프를 직접 구현하고 싶은 개발자에게 적합해요.

출처: 공식문서

본문

Claude 도구들과 Agent SDK 비교

Agent SDK, CLI, Client SDK, Managed Agents는 저마다 다른 필요에 맞아요.

이런 경우 사용 이유
툴 루프를 직접 구현하지 않고 에이전트를 만들 때 Agent SDK Python/TypeScript로 자기 프로세스 안에서 에이전트 루프를 돌리는 라이브러리
터미널에서 대화형 개발이나 일회성 작업 Claude Code CLI 매일 대화형으로 쓰도록 만든 터미널 인터페이스
API를 직접 호출하고 툴 루프를 직접 구현할 때 Client SDK Anthropic API에 직접 접근. 툴 루프는 스스로 구현
샌드박스·세션 인프라 관리 없이 장기/비동기 에이전트 Managed Agents 호스팅 REST API. Anthropic이 에이전트와 샌드박스를 실행

SDK는 Python과 TypeScript용 라이브러리로만 제공돼요. 다른 언어로 같은 에이전트 루프를 구동하려면 -p 플래그와 --output-format json으로 CLI를 서브프로세스로 실행하세요.

SDK에서 쓸 수 있는 기능

Claude Code 기능 상당수가 SDK에 포함돼 있어요.

  • 내장 도구: 파일 읽기·쓰기·편집, 명령 실행, 웹 검색
  • Hooks: 에이전트 생명주기의 핵심 지점에서 커스텀 코드 실행
  • Subagents: 전문화된 에이전트 생성
  • MCP: Model Context Protocol로 외부 도구·데이터 소스 연결
  • Permissions: 자동 실행·승인 필요한 도구 제어
  • Sessions: 교환 간 컨텍스트 유지, 나중에 이어서/포크
  • Skills·commands·memory: Claude Code와 동일하게 프로젝트 .claude/와 ~/.claude/에서 자동 로드
  • Plugins: skills·agents·hooks·MCP 서버를 패키징해 로컬 경로로 로드

시작하기

Quickstart를 따라 SDK 설치, API 키 설정, 첫 에이전트(기존 코드의 버그를 찾아 고치는) 만들기를 진행하세요.

참고: 사전 승인되지 않는 한 Anthropic은 서드파티 개발자가 claude.ai 로그인이나 요금 한도를 자신의 제품(Claude Agent SDK로 만든 에이전트 포함)에 제공하는 것을 허용하지 않아요. 대신 Quickstart에 설명된 API 키 인증 방법을 사용하세요.

브랜딩 지침

파트너가 Claude Agent SDK를 통합할 때 Claude 브랜딩 사용은 선택이에요. 허용: 드롭다운 메뉴의 "Claude Agent"(선호), 이미 "Agents"로 라벨된 메뉴 안의 "Claude", 기존 에이전트 이름이 있을 때 "{YourAgentName} Powered by Claude". 금지: "Claude Code" 또는 "Claude Code Agent", Claude Code 브랜드 ASCII 아트/시각적 요소. 제품은 자신의 브랜딩을 유지하고 Claude Code나 Anthropic 제품처럼 보이지 않아야 해요.

라이선스 및 약관

Claude Agent SDK 사용은 Anthropic's Commercial Terms of Service에 따르되, 특정 컴포넌트가 그 LICENSE 파일에 표시된 대로 다른 라이선스를 받는 경우는 예외예요.

더 알아보기