Claude Code SDK — 현재 공식 명칭은 Claude Agent SDK — 는 Python 및 TypeScript 라이브러리로, 여러분의 애플리케이션 내에서 Claude를 자율 에이전트로 실행할 수 있게 해줍니다. 프롬프트를 입력하면 나머지 작업(파일 읽기, 명령어 실행, 코드 편집, 작업 완료까지 반복)을 알아서 처리합니다. 도구 루프를 작성하거나 스트리밍 연결을 관리할 필요가 없습니다.
이 가이드는 개발자들이 시작하는 데 필요한 모든 것을 다룹니다: 설치, 핵심 query() API, 내장 도구, 훅, 세션, 하위 에이전트, MCP 통합, 그리고 Novita AI의 LLM API를 모델 백엔드로 사용하는 방법까지.
핵심 요약
- Claude Code SDK는 이제 Claude Agent SDK(Python:
claude-agent-sdk, TypeScript:@anthropic-ai/claude-agent-sdk)로 명칭이 변경되었습니다. - 단일
query()함수가 Anthropic Client SDK에서 필요했던 수동 도구 실행 루프를 대체합니다. - 파일 읽기, 편집, bash 실행, 웹 검색 등 내장 도구가 포함되어 있어 별도 구현이 필요 없습니다.
- 세션을 사용하면 에이전트가 전체 컨텍스트를 유지한 채 여러 호출에 걸쳐 작업을 재개할 수 있습니다.
- 훅을 통해 특정 생명주기 시점에서 도구 호출을 검증, 로깅 또는 차단할 수 있습니다.
- Novita AI의 Anthropic 호환 엔드포인트(
https://api.novita.ai/anthropic)를 사용하면 동일한 SDK 코드로 고품질 오픈 가중치 모델을 활용할 수 있습니다.
Claude Code SDK란 무엇인가요?
Claude Code SDK는 Claude Code의 에이전트 기능에 대한 프로그래매틱 인터페이스입니다. Claude Code CLI가 대화형으로 사용하는 것과 동일한 도구, 추론 루프 및 컨텍스트 관리를 노출하지만 — 라이브러리 형태로 여러분의 코드에서 임포트하여 호출할 수 있습니다.
Anthropic은 4.6 세대부터 이를 Claude Agent SDK 로 명칭을 변경했지만, 원래 검색어인 "claude code sdk"는 여전히 그 기능을 정확히 설명합니다: Claude Code 위에 위치하여 소프트웨어에서 에이전트 작업을 자동화할 수 있게 해주는 SDK 계층입니다.
활용 분야:
- CI/CD에서 자동화된 코드 리뷰, 리팩토링 또는 테스트 생성
- 사용자를 대신해 파일을 읽고 수정하거나, 스크립트를 실행하거나, 웹을 검색하는 에이전트
- 조정자가 전문 작업자를 위해 하위 작업을 위임하는 다중 에이전트 파이프라인
- Claude가 프롬프트에 응답하는 것을 넘어 자율적인 다단계 작업을 수행하길 원하는 모든 워크플로
적합하지 않은 경우: 모든 메시지를 직접 제어해야 하거나, 단일 호출에서 구조화된 출력이 필요하거나, 채팅 UI를 위한 스트리밍 응답이 필요하다면 Anthropic Client SDK가 더 적합합니다.
Claude Code SDK vs. Anthropic Client SDK: 언제 무엇을 사용할까
두 SDK 모두 Claude를 기반으로 하지만, 해결하는 문제가 다릅니다.
| Claude Agent SDK | Anthropic Client SDK | |
|---|---|---|
| 도구 실행 | Claude가 자율적으로 처리 | 사용자가 도구 루프 구현 |
| 인터페이스 | query()가 async iterator 반환 |
client.messages.create()가 응답 객체 반환 |
| 내장 도구 | Read, Write, Edit, Bash, Grep, Glob, WebSearch 등 | 없음 — 모든 도구를 사용자가 정의하고 실행 |
| 세션 | 내장 — 세션 ID로 재개 가능 | 수동 — 대화 기록을 직접 관리 |
| 최적 용도 | 에이전트 파이프라인, CI/CD, 파일 작업 | 채팅 앱, 구조화된 출력, 세밀한 제어 |
Claude가 어떤 파일을 읽고 수정할지 스스로 결정하길 원한다면: Agent SDK. 특정 프롬프트에 응답하고 처리할 값을 반환하길 원한다면: Client SDK.
Claude Agent SDK 설치
Python (Python 3.10+ 필요):
pip install claude-agent-sdk
TypeScript / Node.js:
npm install @anthropic-ai/claude-agent-sdk
TypeScript 패키지는 선택적 종속성으로 플랫폼용 네이티브 Claude Code 바이너리를 번들로 제공합니다. Claude Code를 별도로 설치할 필요가 없습니다.
설치 전 Python 버전 확인:
python3 --version # macOS/Linux
py --version # Windows
pip에서 No matching distribution found for claude-agent-sdk 오류가 발생하면 Python 인터프리터 버전이 3.10보다 오래된 것입니다.
1단계: 인증 구성
Anthropic API 키를 환경 변수로 설정:
export ANTHROPIC_API_KEY=your-api-key
SDK는 클라우드 제공자를 통해 라우팅하는 팀을 위해 Amazon Bedrock, Google Vertex AI 및 Azure AI Foundry도 지원합니다:
# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# 표준 AWS 자격 증명 필요
# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# GOOGLE_CLOUD_PROJECT 및 gcloud 자격 증명 필요
# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# Azure 자격 증명 필요
2단계: 첫 번째 에이전트 쿼리 실행
SDK의 전체 표면은 단일 함수인 query()를 중심으로 구축됩니다. 프롬프트와 옵션을 받아 메시지 이벤트의 async iterator를 반환합니다.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="List all Python files in this directory",
options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "List all Python files in this directory",
options: { allowedTools: ["Bash", "Glob"] }
})) {
if ("result" in message) console.log(message.result);
}
이터레이터는 여러 메시지 유형을 반환합니다. 가장 유용한 두 가지:
ResultMessage(또는result필드가 있는 메시지) — 에이전트의 최종 응답subtype === "init"인SystemMessage— 나중에 재개하기 위한session_id를 포함
3단계: allowedTools로 권한 제어
SDK에는 사전 구현된 도구가 포함되어 있습니다. 에이전트가 사용할 수 있는 도구를 선언하면 Claude가 실행을 처리합니다.
| 도구 | 기능 |
|---|---|
| Read | 작업 디렉토리의 모든 파일 읽기 |
| Write | 새 파일 생성 |
| Edit | 기존 파일에 대상 편집 수행 |
| Bash | 셸 명령어, 스크립트, git 작업 실행 |
| Glob | 패턴(**/*.ts, src/**/*.py)으로 파일 찾기 |
| Grep | 정규식으로 파일 내용 검색 |
| WebSearch | 현재 정보를 위해 웹 검색 |
| WebFetch | 웹 페이지 콘텐츠 가져오기 및 파싱 |
| Monitor | 백그라운드 스크립트를 감시하고 출력 라인에 반응 |
| AskUserQuestion | 작업 중간에 사용자에게 질문 |
| Agent | 정의된 하위 에이전트 호출 |
Bash + Read + Edit 조합은 대부분의 자동화된 코드 작업에 충분합니다. 에이전트가 외부 데이터가 필요할 때 WebSearch 또는 WebFetch를 추가하세요.
allowed_tools(Python) / allowedTools(TypeScript)는 프롬프트 없이 특정 도구를 사전 승인합니다. 도구 세트를 제한하면 에이전트가 의도치 않게 수행할 수 있는 작업도 제한됩니다 — 자동화된 파이프라인에 유용한 보호 장치입니다.
읽기 전용 코드 리뷰 에이전트:
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Review this codebase for security issues and code smell",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
),
):
if hasattr(message, "result"):
print(message.result)
전체 편집 에이전트 (파일 쓰기 사전 승인):
options=ClaudeAgentOptions(
allowed_tools=["Read", "Write", "Edit", "Bash"],
permission_mode="acceptEdits",
)
permission_mode="acceptEdits"는 대화형 프롬프트 없이 파일 편집을 자동 승인하며, CI에서 실행할 때 필요합니다.
4단계: 생명주기 제어를 위한 훅 사용
훅을 사용하면 에이전트 실행의 정의된 지점에서 사용자 정의 코드를 실행할 수 있습니다. 작업을 로깅하거나, 입력을 검증하거나, 위험한 작업을 차단하거나, 외부 상태를 업데이트할 수 있습니다.
사용 가능한 훅 이벤트: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest
다음 예제는 에이전트가 파일을 편집하거나 생성할 때마다 감사 로그를 기록합니다:
import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
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().isoformat()}: modified {file_path}\n")
return {}
async def main():
async for message in query(
prompt="Refactor auth.py to use dataclasses",
options=ClaudeAgentOptions(
permission_mode="acceptEdits",
hooks={
"PostToolUse": [
HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
]
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";
const logFileChange: HookCallback = async (input) => {
const filePath = (input as any).tool_input?.file_path ?? "unknown";
await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
return {};
};
for await (const message of query({
prompt: "Refactor auth.ts to use interfaces",
options: {
permissionMode: "acceptEdits",
hooks: {
PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
}
}
})) {
if ("result" in message) console.log(message.result);
}
{ block: true }를 반환하는 PreToolUse 훅은 도구 호출을 완전히 차단합니다 — 자동화된 컨텍스트에서 "파일을 절대 삭제하지 않음"과 같은 정책을 적용하는 데 유용합니다.
5단계: 세션으로 작업 재개
세션은 에이전트의 전체 컨텍스트(읽은 파일, 찾은 내용, 대화 기록)를 여러 query() 호출에 걸쳐 유지합니다. 이를 통해 긴 작업을 단계로 나누거나 중단된 작업을 계속할 수 있습니다.
세션을 재개하려면 SystemMessage init 이벤트에서 session_id를 캡처한 후 resume에 전달합니다:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage
async def main():
session_id = None
# 첫 번째 쿼리: 코드베이스 읽기 및 분석
async for message in query(
prompt="Read the authentication module and identify all external dependencies",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
session_id = message.data["session_id"]
# 두 번째 쿼리: 첫 번째 쿼리의 전체 컨텍스트로 계속
async for message in query(
prompt="Now check if any of those dependencies have known vulnerabilities",
options=ClaudeAgentOptions(
resume=session_id,
allowed_tools=["Read", "Bash", "WebSearch"],
),
):
if isinstance(message, ResultMessage):
print(message.result)
asyncio.run(main())
두 번째 프롬프트는 "those dependencies"를 사용합니다 — 이는 세션이 첫 번째 호출의 컨텍스트를 전달하기 때문에 의미가 있습니다. resume이 없으면 Claude가 무엇을 참조하는지 전혀 알 수 없습니다.
6단계: 하위 에이전트로 작업 위임
하위 에이전트는 메인 에이전트가 Agent 도구를 통해 호출할 수 있는 특화된 에이전트입니다. 메인 에이전트가 조정하고, 하위 에이전트가 집중 작업을 수행합니다. 결과는 메인 컨텍스트로 다시 흘러갑니다.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"security-auditor": AgentDefinition(
description="Specialist in authentication and authorization security.",
prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
tools=["Read", "Glob", "Grep"],
),
"style-checker": AgentDefinition(
description="Code style and maintainability reviewer.",
prompt="Check code for naming conventions, complexity, and documentation gaps.",
tools=["Read", "Glob"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
하위 에이전트 호출을 사전 승인하려면 allowed_tools에 "Agent"를 포함하세요. 하위 에이전트의 메시지에는 parent_tool_use_id 필드가 포함되어 있어 어떤 출력이 어떤 하위 에이전트에서 왔는지 추적할 수 있습니다.
7단계: MCP를 통해 외부 시스템 연결
Model Context Protocol(MCP)을 사용하면 사용자 정의 도구를 작성하지 않고도 에이전트에 데이터베이스, 브라우저, 내부 API 등 외부 기능을 추가할 수 있습니다. 에이전트는 MCP 도구를 내장 도구와 동일하게 취급합니다.
다음 예제는 Playwright MCP 서버를 통해 브라우저 자동화를 추가합니다:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Open https://example.com and describe the page structure",
options=ClaudeAgentOptions(
mcp_servers={
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
mcp_servers 옵션은 MCP 사양을 따르는 모든 서버를 허용합니다. github.com/modelcontextprotocol/servers의 커뮤니티 MCP 레지스트리에는 Postgres, Puppeteer, Slack, GitHub 및 파일 시스템 변형을 포함한 수백 개의 통합이 나열되어 있습니다.
Novita AI를 모델 백엔드로 사용
Claude Agent SDK는 기본적으로 Anthropic의 API를 사용하지만, 코드 변경 없이 Novita AI의 Anthropic 호환 엔드포인트를 가리켜 비용 효율적인 오픈 가중치 모델을 사용할 수 있습니다.
Novita AI의 엔드포인트는 Anthropic API 형식을 미러링합니다:
https://api.novita.ai/anthropic
에이전트를 실행하기 전에 이 두 환경 변수를 설정하세요:
export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"
기존 query() 호출은 수정 없이 작동합니다. SDK가 ANTHROPIC_BASE_URL을 자동으로 읽습니다.
Novita AI는 Kimi K2.5, GLM 5.2, MiniMax M2.1 및 Qwen 3.5를 포함한 다양한 모델을 호스팅하며, 이 엔드포인트를 통해 접근할 수 있습니다. 수천 개의 작업을 실행하는 에이전트 파이프라인을 구축하는 팀의 경우 토큰당 비용 차이가 상당할 수 있습니다. 현재 모델 카탈로그와 가격은 Novita AI LLM API에서 확인하세요.
에이전트를 격리된 샌드박스 인프라에 배포해야 하는 경우 — 에이전트가 호스트 파일 시스템에 접근하는 것을 원하지 않는 에이전트 코드 실행에 유용 — Novita Agent Sandbox는 Claude Agent SDK를 기반으로 구축된 에이전트를 위해 특별히 설계된 E2B 호환 실행 환경을 제공합니다.
CI/CD 파이프라인에서의 Claude Code SDK
SDK의 permission_mode="acceptEdits" 및 allowed_tools 제한은 무인 에이전트를 CI에서 실행하는 것을 실용적으로 만듭니다. 일반적인 GitHub Actions 패턴:
- name: Run automated code review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
python review_agent.py
review_agent.py는 다음과 같은 내용을 포함합니다:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Bash"],
permission_mode="acceptEdits",
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
리포지토리에 다시 쓰는 에이전트(자동 리팩토링, 문서 생성)의 경우, 변경 사항이 git에 도달하기 전에 검증하는 PostToolUse 훅과 함께 사용하세요.
문제 해결
No matching distribution found for claude-agent-sdk
Python 버전이 3.10 미만입니다. python3 --version을 실행하고 필요한 경우 업그레이드하세요.
ANTHROPIC_API_KEY is not set
SDK에 환경 변수가 필요합니다. 실행 전에 셸이나 .env 파일에서 내보내세요.
TypeScript 에이전트가 완료되기 전에 종료됨
전체 이터레이터 루프를 await해야 합니다. SDK는 프로세스가 종료되기 전에 모든 메시지 이벤트를 처리해야 합니다.
에이전트가 예상치 못한 도구를 사용함
allowed_tools를 사용하여 도구 세트를 명시적으로 제한하세요. 지정하지 않으면 에이전트가 모든 내장 도구에 접근할 수 있습니다.
하위 에이전트 메시지가 출력에 나타나지 않음
parent_tool_use_id가 설정된 메시지를 필터링하여 메인 에이전트와 별도로 하위 에이전트 출력을 식별하세요.
세션이 올바르게 재개되지 않음
첫 번째 쿼리 시작 시 subtype === "init"인 SystemMessage에서 session_id를 캡처하고, 결과 메시지에서는 캡처하지 마세요.
FAQ
Claude Code SDK와 Anthropic SDK의 차이점은 무엇인가요?
Claude Agent SDK(이전 Claude Code SDK)는 도구 실행을 자동으로 처리하는 자율 에이전트를 제공합니다. Anthropic Client SDK는 도구 루프를 직접 구현해야 하는 원시 API 접근을 제공합니다. 에이전트 파이프라인에는 Agent SDK를, 정밀한 제어가 필요한 직접 모델 호출에는 Client SDK를 사용하세요.
claude-agent-sdk에 필요한 Python 버전은 무엇인가요?
Python 3.10 이상입니다. 패키지는 Python 3.9 이하에서는 설치되지 않습니다.
TypeScript SDK를 사용하려면 Claude Code CLI를 설치해야 하나요?
아니요. @anthropic-ai/claude-agent-sdk 패키지는 선택적 종속성으로 자체 네이티브 Claude Code 바이너리를 번들로 제공합니다.
Claude Agent SDK가 Anthropic의 Claude 외에 다른 모델을 사용할 수 있나요?
ANTHROPIC_BASE_URL을 https://api.novita.ai/anthropic과 같은 Anthropic 호환 엔드포인트로 설정하면 해당 제공자가 호스팅하는 모든 모델(Kimi, GLM, MiniMax 또는 Qwen의 오픈 가중치 모델 포함)을 사용할 수 있습니다.
Agent SDK와 Claude Managed Agents의 차이점은 무엇인가요?
Managed Agents는 Anthropic이 자체 인프라에서 에이전트를 실행하는 호스팅 REST API입니다. Agent SDK는 사용자 프로세스에서, 사용자 파일 시스템에서 에이전트 루프를 실행하는 라이브러리입니다. Agent SDK는 로컬 개발과 개인 파일이나 서비스에 접근해야 하는 에이전트에 더 적합합니다.
Claude Agent SDK가 스트리밍 출력을 지원하나요?
query() 함수는 에이전트가 작업하는 동안 메시지를 생성하는 async iterator를 반환합니다. 이는 스트리밍과 유사한 동작을 제공합니다 — 최종 답변 전에 중간 결과를 볼 수 있습니다.
Agent SDK를 Amazon Bedrock 또는 Vertex AI와 함께 사용할 수 있나요?
예. Bedrock의 경우 CLAUDE_CODE_USE_BEDROCK=1과 AWS 자격 증명을, Vertex AI의 경우 CLAUDE_CODE_USE_VERTEX=1과 Google Cloud 자격 증명을 설정하세요.
먼저 읽어야 할 anthropic claude agent sdk 문서는 무엇인가요?
공식 문서는 code.claude.com/docs/en/agent-sdk/overview에 있습니다. 퀵스타트부터 시작한 다음, 작동하는 에이전트가 생기면 세션 및 훅 가이드를 읽으세요.
추천 문서
- Claude Code CLI 문서: 설정, 슬래시 명령어 및 LLM API 통합
- Vercel AI SDK: AI 애플리케이션 구축을 위한 완전한 개발자 가이드
- Novita Sandbox로 Claude Agent SDK 배포 및 호스팅 방법
출처 확인: 2026년 7월 3일, Claude Agent SDK 문서, Novita AI LLM API
