Claude Agent SDK는 Claude Code를 움직이는 에이전트 루프·도구·컨텍스트 관리를 그대로 코드에서 호출할 수 있게 해 주는 Python·TypeScript 라이브러리입니다. 터미널 대화 대신 함수 호출로 에이전트를 내 제품·내부 도구·자동화 파이프라인 안에 심을 수 있습니다. 이 글은 일반 클라이언트 SDK와의 차이, 에이전트 루프의 동작, 시작 코드, 주요 옵션을 공식 문서 기준으로 정리합니다. (기준 시점: 2026년 6월. 세부 사항은 변동될 수 있으니 공식 Agent SDK 문서를 확인하세요.)
클라이언트 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로 병행합니다.
비용 관련 참고: 공식 문서에 따르면 2026년 6월 15일부터 구독 플랜에서의 Agent SDK 사용은 대화형 사용 한도와 분리된 별도의 월간 Agent SDK 크레딧에서 차감됩니다. API 키 기반 사용은 일반 API 과금을 따릅니다. 정확한 정책은 공식 문서에서 확인하세요.
이 글의 패키지명·코드·동작은 2026년 6월 공식 문서 기준이며 SDK 버전에 따라 달라질 수 있습니다. 옵션 전체 목록과 최신 변경 사항은 공식 Agent SDK 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.