Claude Agent SDK 가이드 — Claude Code의 에이전트 루프를 코드로

Claude Agent SDK는 Claude Code를 움직이는 에이전트 루프·도구·컨텍스트 관리를 그대로 코드에서 호출할 수 있게 해 주는 Python·TypeScript 라이브러리입니다. 터미널 대화 대신 함수 호출로 에이전트를 내 제품·내부 도구·자동화 파이프라인 안에 심을 수 있습니다. 이 글은 일반 클라이언트 SDK와의 차이, 에이전트 루프의 동작, 시작 코드, 주요 옵션을 공식 문서 기준으로 정리합니다. (세부 사항은 변동될 수 있으니 공식 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년 10월 31일 공식 도움말 기준): Anthropic은 5월 14일 구독 플랜의 Agent SDK·claude -p 사용을 별도 월간 크레딧으로 분리하겠다고 예고했다가 6월 15일 보류했습니다. 이후 2026년 10월 7일 공지로 Max·Team 플랜에 월간 API 크레딧이 포함됐습니다. 이 크레딧은 연결된 Claude Console 조직의 API 키로 실행할 때 Claude API·Claude Managed Agents·Agent SDK·claude -p에 쓸 수 있고, Claude 플랜으로 로그인해 쓰는 Agent SDK·claude -p는 지금처럼 구독 사용 한도에서 차감됩니다. 크레딧 금액과 세부 조건은 이 도움말에 나와 있지 않으니 공식 도움말과 연결된 "Monthly API credits for Max and Team plans" 문서에서 확인하세요(Pro 플랜은 해당 안내에 없음). API 키 기반 사용은 일반 API 과금을 따르며, 단 공식 문서는 서드파티 개발자가 자기 제품에 claude.ai 로그인(구독 한도)을 제공하는 것은 사전 승인 없이는 허용하지 않는다고 명시하므로 배포용 제품에는 API 키 인증을 쓰세요.

이 글의 패키지명·코드·동작은 2026년 9월 9일 공식 문서(overview·quickstart·migration guide) 재대조 기준이며 SDK 버전에 따라 달라질 수 있습니다. 옵션 전체 목록과 최신 변경 사항은 공식 Agent SDK 문서를 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.

더 보기: Claude SDK 스트리밍 응답 처리

관련 글

• Claude SDK 시작하기 — Python·TypeScript 공식 클라이언트 사용법
• Claude SDK 스트리밍 응답 처리 — SSE 이벤트·실시간 출력·에러 복구
• Claude Opus 4.7 완벽 가이드: 새 기능과 사양 총정리
• Claude Code 설치 가이드: native vs npm, Windows까지
• Claude 프롬프트 작성법: 공식 문서 기반 핵심 원칙 6가지