Claude Code SDK는 Anthropic의 에이전트 SDK 출시와 함께 Claude Agent SDK로 이름이 변경된, Python 및 TypeScript 라이브러리로, 애플리케이션 내에서 자율 코딩 에이전트를 실행하기 위한 도구입니다. 파일 읽기, 명령어 실행, 코드 편집, 도구 호출 및 수동 도구 루프 없이 여러 단계를 반복하는 작업을 처리합니다. Novita AI의 Anthropic 호환 엔드포인트를 사용하면 동일한 SDK로 지원되는 오픈 가중치 모델도 실행할 수 있어, 기본 Anthropic 백엔드를 넘어 모델 선택과 비용 제어 경로를 팀에 제공합니다.
이 가이드는 개발자들이 시작하는 데 필요한 모든 것을 다룹니다: 설치, 핵심 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()가 비동기 이터레이터 반환 |
client.messages.create()가 응답 객체 반환 |
| 내장 도구 | 읽기, 쓰기, 편집, Bash, Grep, Glob, 웹 검색 등 | 없음 — 모든 도구를 사용자가 정의하고 실행 |
| 세션 | 내장 — 세션 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()를 중심으로 구축되었습니다. 프롬프트와 옵션을 받아 메시지 이벤트의 비동기 이터레이터를 반환합니다.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="이 디렉토리의 모든 Python 파일을 나열하세요",
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: "이 디렉토리의 모든 Python 파일을 나열하세요",
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="이 코드베이스의 보안 문제와 코드 스멜을 검토하세요",
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()}: {file_path} 수정됨\n")
return {}
async def main():
async for message in query(
prompt="auth.py를 dataclass를 사용하도록 리팩토링하세요",
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()}: ${filePath} 수정됨\n`);
return {};
};
for await (const message of query({
prompt: "auth.ts를 인터페이스를 사용하도록 리팩토링하세요",
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="인증 모듈을 읽고 모든 외부 종속성을 식별하세요",
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="이제 해당 종속성 중 알려진 취약점이 있는지 확인하세요",
options=ClaudeAgentOptions(
resume=session_id,
allowed_tools=["Read", "Bash", "WebSearch"],
),
):
if isinstance(message, ResultMessage):
print(message.result)
asyncio.run(main())
두 번째 프롬프트는 "해당 종속성"을 사용합니다. 이는 세션이 첫 번째 호출의 컨텍스트를 전달하기 때문에 의미가 있는 참조입니다. resume이 없으면 Claude는 사용자가 무엇을 가리키는지 전혀 알 수 없습니다.
6단계: 서브에이전트로 작업 위임
서브에이전트는 메인 에이전트가 Agent 도구를 통해 호출할 수 있는 특수 에이전트입니다. 메인 에이전트는 조정하고, 서브에이전트는 집중 작업을 수행합니다. 결과는 메인 컨텍스트로 다시 흘러갑니다.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="이 코드베이스를 검토하세요: auth 파일은 security-auditor 에이전트를, 나머지는 style-checker 에이전트를 사용하세요",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"security-auditor": AgentDefinition(
description="인증 및 권한 부여 보안 전문가.",
prompt="OWASP Top 10 취약점에 대해 인증 관련 코드를 감사하세요. 라인 번호와 위험 심각도를 구체적으로 명시하세요.",
tools=["Read", "Glob", "Grep"],
),
"style-checker": AgentDefinition(
description="코드 스타일 및 유지보수성 검토자.",
prompt="명명 규칙, 복잡성 및 문서화 격차에 대해 코드를 확인하세요.",
tools=["Read", "Glob"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
서브에이전트 호출을 사전 승인하려면 allowed_tools에 "Agent"를 포함하세요. 서브에이전트의 메시지에는 parent_tool_use_id 필드가 포함되어 있어 어떤 출력이 어떤 서브에이전트에서 왔는지 추적할 수 있습니다.
7단계: MCP를 통해 외부 시스템 연결
MCP(Model Context Protocol)를 사용하면 사용자 정의 도구를 작성하지 않고도 데이터베이스, 브라우저, 내부 API 등 외부 기능을 에이전트에 추가할 수 있습니다. 에이전트는 MCP 도구를 내장 도구와 동일하게 취급합니다.
이 예제는 Playwright MCP 서버를 통해 브라우저 자동화를 추가합니다:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="https://example.com을 열고 페이지 구조를 설명하세요",
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: 자동화된 코드 리뷰 실행
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="이 PR에서 변경된 모든 Python 파일의 정확성과 테스트 커버리지 격차를 검토하세요. JSON 보고서를 출력하세요.",
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() 함수는 에이전트가 작업하는 동안 메시지를 생성하는 비동기 이터레이터를 반환합니다. 이는 최종 답변 전에 중간 결과를 볼 수 있는 스트리밍과 유사한 동작을 제공합니다.
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
