Anthropic의 에이전트 SDK 릴리스에서 Claude Agent SDK로 이름이 변경된 Claude Code SDK는 애플리케이션 내에서 자율 코딩 에이전트를 실행하기 위한 Python 및 TypeScript 라이브러리입니다. 파일 읽기, 명령어, 코드 편집, 도구 호출, 다단계 반복을 수동 도구 루프 없이 처리합니다. Novita AI의 Anthropic 호환 엔드포인트를 사용하면 동일한 SDK로 지원되는 오픈 웨이트 모델도 실행할 수 있어, 팀이 기본 Anthropic 백엔드 외에도 모델 선택과 비용 제어 경로를 확보할 수 있습니다. 구독 대 API의 선택에 대해서는 Claude API 가격 vs 구독 요금제를 참조하세요.
이 가이드는 개발자가 시작하는 데 필요한 모든 것을 다룹니다: 설치, 핵심 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가 대화형으로 사용하는 것과 동일한 도구, 추론 루프, 컨텍스트 관리를 라이브러리 형태로 제공하여 자체 코드에서 가져와 호출할 수 있습니다. 프로젝트 수준 규칙과 범위에 대해서는 Claude Code 규칙 및 CLAUDE.md를 참조하세요.
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()가 응답 객체 반환 |
| 내장 도구 | 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()를 중심으로 구축되었습니다. 프롬프트와 옵션을 받아 메시지 이벤트의 비동기 이터레이터를 반환합니다.
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: "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="이 코드베이스에서 보안 문제와 코드 악취를 검토해줘",
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="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()}: 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="인증 모듈을 읽고 모든 외부 종속성을 식별해줘",
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를 통한 외부 시스템 연결
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="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 사양을 따르는 모든 서버를 허용합니다. 커뮤니티 MCP 레지스트리(github.com/modelcontextprotocol/servers)에는 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())
Note: The user’s prompt contains a deliberate typo in the code block ("Glob", "Grep", "Bash") which we must preserve exactly as given. Also note the string "테스트 범위 격차" is partially corrupted but we keep as is.
For agents that write back to the repo (automated refactoring, doc generation), pair this with a PostToolUse hook that validates changes before they reach git.
문제 해결
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에 필요한 Pyhon 버전은 무엇인가요?
Pythn 3.10 이상입니다. 패키지는 Pythn 3.9 이하에서 설치되지 않습니다.
TypeScrit SDK를 사용하려면 Claude Code CLI를 설치해야 하나요?
아니요. @anthopic-ai/claude-agent-sdk 패키지는 자체 네이티브 Claude Code 바이너리를 선택적 종속성으로 번들합니다.
Claude Agent SDK는 Antropic의 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 Agents 사용 방법: 설정, 도구, 권한, 샌드박스 워크플로우
- Claude Code 플러그인: MCP 도구가 외부 기능으로 Claude Code를 확장하는 방법
- Claude Code 규칙: CLAUDE.md 작성 및 에이전트 코딩 컨텍스트 관리
- Claude Code CLI 문서: 설정, 슬래시 명령어, LLM API 통합
- Vercel AI SDK: AI 애플리케이션 구축을 위한 완전한 개발자 가이드
- Claude Agent SDK를 Novita Sandbox로 배포 및 호스팅하는 방법
출처 확인: 2026년 7월 3일 — Claude Agent SDK 문서, Novita AI LLM API
