Claude Agent SDK는 Claude Code를 움직이는 에이전트 루프·도구·컨텍스트 관리를 그대로 코드에서 호출할 수 있게 해 주는 Python·TypeScript 라이브러리입니다. 터미널 대화 대신 함수 호출로 에이전트를 내 제품·내부 도구·자동화 파이프라인 안에 심을 수 있습니다. 이 글은 일반 클라이언트 SDK와의 차이, 에이전트 루프의 동작, 시작 코드, 주요 옵션을 공식 문서 기준으로 정리합니다. (세부 사항은 변동될 수 있으니 공식 Agent SDK 문서를 확인하세요.)
🟢 현행 모델 라인업 일치 · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
클라이언트 SDK와 무엇이 다른가
일반 클라이언트 SDK는 Messages API를 감싼 얇은 래퍼라서, 도구 사용 시 "응답 확인 → 도구 직접 실행 → 결과 재전송" 루프를 개발자가 직접 구현해야 합니다. Agent SDK는 이 루프를 통째로 맡습니다. Claude가 도구를 고르면 SDK가 로컬에서 실행하고 결과를 자동으로 되돌려, 작업이 끝날 때까지 반복합니다. 즉 클라이언트 SDK는 "모델 호출 라이브러리", Agent SDK는 "에이전트 실행 라이브러리"입니다.
참고로 Agent SDK는 예전 "Claude Code SDK"가 개명된 것입니다. Python은 claude_code_sdk → claude_agent_sdk, TypeScript는 @anthropic-ai/claude-code → @anthropic-ai/claude-agent-sdk로 임포트만 바꾸면 됩니다(ClaudeCodeOptions는 ClaudeAgentOptions로).
설치와 첫 에이전트
패키지는 Python claude-agent-sdk, TypeScript @anthropic-ai/claude-agent-sdk입니다. 핵심 진입점은 query() — 프롬프트와 옵션을 받아 메시지를 스트리밍하는 비동기 제너레이터입니다.
# pip install claude-agent-sdk
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="auth.py의 버그를 찾아서 고쳐줘",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude가 파일을 읽고, 버그를 찾고, 고친다
asyncio.run(main())루프가 도는 동안 매 반복마다 Claude의 사고, 도구 호출, 도구 결과, 최종 결과가 메시지로 흘러나옵니다. query()는 호출할 때마다 새 세션으로 시작합니다(이전 대화 기억 없음). 멀티턴 대화가 필요하면 세션을 유지하는 클라이언트 인터페이스를 쓰면 됩니다.
Claude Code 기능을 코드에서 그대로
Agent SDK는 Claude Code의 구성 요소를 프로그래밍 방식으로 노출합니다.
- 내장 도구 — 파일 읽기/쓰기/편집, 검색(Glob·Grep), 셸 실행(Bash), 웹 접근 등. 도구 실행 코드를 직접 짤 필요가 없습니다.
- MCP 서버 연결 — 외부 서비스 도구를 에이전트에 붙일 수 있습니다. MCP란? 참고.
- 권한 제어 —
allowed_tools·거부 규칙과 권한 모드로 에이전트가 할 수 있는 일을 제한합니다. 규칙 체계는 Claude Code 권한 설정과 같은 개념을 공유합니다. - 훅·서브에이전트·스킬 — 도구 실행 전후에 커스텀 로직을 끼우고(훅), 작업을 서브에이전트로 나누는 것도 SDK에서 지원됩니다.
언제 무엇을 쓰나
단순 텍스트 생성·분류·단발 호출이면 클라이언트 SDK로 충분하고 더 가볍습니다. 모델이 여러 단계를 스스로 결정하며 파일·명령·웹을 오가야 하는 작업 — 코드 수리 봇, 리서치 에이전트, CI 자동화 — 이라면 Agent SDK가 루프 구현 부담을 없애 줍니다. 많은 팀이 일상 개발은 Claude Code CLI로, 프로덕션 자동화는 Agent SDK로 병행합니다.
비용 관련 참고: Anthropic은 2026년 5월 14일 "6월 15일부터 구독 플랜의 Agent SDK·claude -p 사용을 대화형 한도와 분리해 별도 월간 Agent SDK 크레딧으로 과금"하겠다고 예고했지만, 6월 15일 당일 이 변경을 보류했습니다. 공식 도움말(6월 16일 갱신) 기준 현재는 바뀐 것이 없습니다 — Agent SDK·claude -p·서드파티 앱 사용은 여전히 구독의 사용 한도에서 차감되고, 예고됐던 월간 크레딧은 제공되지 않습니다. 새 안이 정해지면 시행 전에 미리 공지한다고 밝혔습니다. API 키 기반 사용은 일반 API 과금을 따르며, 단 공식 문서는 서드파티 개발자가 자기 제품에 claude.ai 로그인(구독 한도)을 제공하는 것은 사전 승인 없이는 허용하지 않는다고 명시하므로 배포용 제품에는 API 키 인증을 쓰세요.
이 글의 패키지명·코드·동작은 2026년 9월 9일 공식 문서(overview·quickstart·migration guide) 재대조 기준이며 SDK 버전에 따라 달라질 수 있습니다. 옵션 전체 목록과 최신 변경 사항은 공식 Agent SDK 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.