Claude Agent SDK: Claude Code를 라이브러리로 써서 나만의 에이전트 만들기

Claude Code의 도구, 에이전트 루프, 컨텍스트 관리를 그대로 가져다 쓸 수 있는 SDK가 있다. pip install claude-agent-sdk 한 줄이면 된다.

Claude Agent SDK(구 Claude Code SDK)는 Claude Code를 CLI가 아닌 라이브러리로 쓸 수 있게 해주는 공식 SDK다. 파일 읽기, 명령어 실행, 코드 편집, 웹 검색까지 — Claude Code가 할 수 있는 모든 것을 Python이나 TypeScript 코드에서 프로그래밍 가능하다.

핵심은 query() 함수 하나다. 프롬프트를 넣으면 Claude가 알아서 도구를 호출하고, 파일을 읽고, 코드를 수정한다. 도구 실행 루프를 직접 구현할 필요가 없다.

목차

• 설치와 첫 실행
  • 최소 동작 코드
• Client SDK와 뭐가 다른가
• 빌트인 도구 9가지
• 4가지 핵심 확장 포인트
  • 1. Hooks — 라이프사이클 콜백
  • 2. MCP 서버 — 외부 시스템 연결
  • 3. 서브에이전트 — 작업 위임
  • 4. 세션 — 컨텍스트 유지
• 실전 활용 시나리오
• 비용
• 구 SDK에서 마이그레이션
• 요약

설치와 첫 실행

# Python
pip install claude-agent-sdk

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# API 키 설정
export ANTHROPIC_API_KEY=your-api-key

Amazon Bedrock(CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI(CLAUDE_CODE_USE_VERTEX=1), Microsoft Azure(CLAUDE_CODE_USE_FOUNDRY=1)도 지원한다.

최소 동작 코드

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "What files are in this directory?",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

query()는 async iterator를 반환한다. Claude가 자율적으로 도구를 호출하면서 작업하는 동안, 메시지(추론, 도구 호출, 결과)가 스트리밍으로 들어온다.

Client SDK와 뭐가 다른가

Anthropic Client SDK는 API에 직접 접근한다. 도구 실행 루프를 직접 구현해야 한다. Agent SDK는 Claude가 도구 실행까지 알아서 한다.

# Client SDK: 도구 루프를 직접 구현
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK: query() 한 줄
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

	Client SDK	Agent SDK
도구 실행	직접 구현	자동
빌트인 도구	없음	Read, Write, Edit, Bash, Glob, Grep 등
에이전트 루프	수동	내장
적합 용도	세밀한 제어 필요 시	빠른 에이전트 개발

빌트인 도구 9가지

SDK에 기본 탑재된 도구들이다. 별도 구현 없이 바로 사용할 수 있다.

도구	기능
Read	파일 읽기
Write	파일 생성
Edit	기존 파일 정밀 수정
Bash	터미널 명령어, 스크립트, git 실행
Glob	패턴으로 파일 검색
Grep	정규식으로 파일 내용 검색
WebSearch	웹 검색
WebFetch	웹 페이지 내용 가져오기
AskUserQuestion	사용자에게 질문

4가지 핵심 확장 포인트

1. Hooks — 라이프사이클 콜백

도구 호출 전/후, 세션 시작/종료 등 핵심 시점에 커스텀 코드를 실행할 수 있다.

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

async for message in query(
    prompt="Refactor utils.py",
    options=ClaudeAgentOptions(
        permission_mode="acceptEdits",
        hooks={
            "PostToolUse": [
                HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
            ]
        },
    ),
):
    ...

사용 가능한 훅: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit.

2. MCP 서버 — 외부 시스템 연결

데이터베이스, 브라우저, API 등 외부 시스템을 MCP로 연결한다.

async for message in query(
    prompt="Open example.com and describe what you see",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
        }
    ),
):
    ...

커뮤니티에서 만든 MCP 서버가 1,000개 이상 있다. Slack, 데이터베이스, 커스텀 엔터프라이즈 시스템까지 연결할 수 있다.

3. 서브에이전트 — 작업 위임

전문화된 하위 에이전트를 정의하고 메인 에이전트가 위임하는 구조다.

async for message in query(
    prompt="Use the code-reviewer agent to review this codebase",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Expert code reviewer.",
                prompt="Analyze code quality and suggest improvements.",
                tools=["Read", "Glob", "Grep"],
            )
        },
    ),
):
    ...

4. 세션 — 컨텍스트 유지

여러 query() 호출에 걸쳐 컨텍스트를 유지할 수 있다. 세션 ID로 이전 대화를 이어가거나 포크할 수 있다.

# 첫 번째 쿼리: 세션 ID 캡처
async for message in query(prompt="Read the auth module", ...):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

# 두 번째 쿼리: 컨텍스트 이어가기
async for message in query(
    prompt="Now find all places that call it",
    options=ClaudeAgentOptions(resume=session_id),
):
    ...

실전 활용 시나리오

시나리오	구현 방식
CI/CD 자동 코드 리뷰	Read + Grep + Bash로 PR 변경점 분석
보안 스캐너	커스텀 서브에이전트가 취약점 패턴 탐지
이메일 어시스턴트	MCP로 메일 서버 연결 + WebSearch로 정보 보강
SRE 자동 대응	Bash로 로그 분석 + 장애 패턴 매칭 + 알림
브라우저 자동화	Playwright MCP 서버 연결

공식 데모 레포(anthropics/claude-agent-sdk-demos)에 이메일 어시스턴트, 리서치 에이전트 등 실제 예제가 있다.

비용

별도 SDK 요금은 없다. 일반 API 토큰 단가가 적용된다.

모델	Input (1M 토큰)	Output (1M 토큰)
Haiku 4.5	$1	$5
Sonnet 4.6	$3	$15
Opus 4.6	$5	$25

프롬프트 캐시 히트 시 입력 비용 90% 할인. ResultMessage에 모델별 토큰 수와 비용 분석이 포함된다.

구 SDK에서 마이그레이션

2025년 9월에 Claude Code SDK → Claude Agent SDK로 이름이 바뀌었다. 주요 변경점:

항목	이전	현재
Python 패키지	claude-code-sdk	claude-agent-sdk
TS 패키지	@anthropic-ai/claude-code	@anthropic-ai/claude-agent-sdk
옵션 클래스	ClaudeCodeOptions	ClaudeAgentOptions

Breaking changes 3가지:

1. 시스템 프롬프트가 더 이상 Claude Code 기본값을 사용하지 않는다 — system_prompt={"type": "preset", "preset": "claude_code"} 명시 필요
2. CLAUDE.md, settings.json 등이 자동 로드되지 않는다 — setting_sources=["user", "project", "local"] 명시 필요
3. 옵션 클래스명 변경

요약

• Claude Agent SDK는 Claude Code의 전체 에이전트 런타임을 라이브러리로 제공한다
• query() 함수 하나로 자율적 도구 호출이 가능하다
• 빌트인 도구 9개 + Hooks + MCP + 서브에이전트 + 세션으로 확장한다
• 별도 SDK 요금 없이 API 토큰 단가만 적용된다
• Python과 TypeScript 모두 지원한다

---

관련글:

• Claude Code 해부학 이후: AI 코딩 에이전트 설계 원리 7가지 — 도구 호출, 컨텍스트 관리, 샌드박스의 구조
• MCP를 붙이면 코딩 에이전트는 어디까지 달라지나 — 연결 레이어의 설계 해부