Claude Code Agent SDK는 프로그래밍 가능한 에이전트 루프를 제공합니다. 그것은 좋은 소식입니다.
더 중요한 소식은 그것이 무엇을 제공하지 않는가입니다.
이 SDK는 대부분의 프로덕션 워크플로에 필요한 현실 세계의 기능 계층, 즉 실시간 검색, 이미지 생성, 비디오 생성, 산출물 저장, 퍼블리싱을 에이전트에 제공하지 않습니다. SDK는 셸과 오케스트레이션 계층을 제공합니다. 더 강한 에이전트를 원한다면 그 뒤에서 실행되는 런타임이 여전히 필요합니다.
이 구분이 중요한 이유는 많은 SDK 가이드가 “에이전트를 어떻게 띄우는가”에서 멈추기 때문입니다. 프로덕션 팀이 궁금해하는 다음 질문은 이것입니다. 그 에이전트가 실제로 일을 끝낼 수 있는가?
이 가이드는 두 가지를 모두 다룹니다. Claude Code Agent SDK가 잘하는 일과, 에이전트가 파일을 읽고 bash를 실행하는 것 이상을 해야 할 때 AnyCap 같은 기능 런타임이 어디에 들어가는지 설명합니다.
Claude Code Agent SDK란?
Claude Code Agent SDK는 Claude Code 스타일의 에이전트 동작을 자체 애플리케이션에 내장하기 위한 Anthropic의 Python 및 TypeScript 툴킷입니다.
이렇게 생각하면 됩니다.
- Claude 모델 = 추론
- Agent SDK = 프로그래밍 가능한 에이전트 루프
- 기능 런타임 = 미디어, 검색, 저장, 퍼블리싱을 위한 빠진 실행 계층
SDK는 원래 직접 만들어야 했을 핵심 오케스트레이션 작업을 처리합니다.
- 계획 수립과 반복 실행
- 파일 접근과 편집
- 셸 실행
- 도구 호출
- MCP 통합
- 서브에이전트 패턴
이것만으로도 많은 커스텀 글루 코드를 대체할 수 있습니다. 하지만 여전히 프로덕션 스택의 일부일 뿐입니다.
순수 Claude API와 무엇이 다른가
| 기능 | Claude API | Claude Code Agent SDK |
|---|---|---|
| 에이전트 루프 | 직접 구현 | 내장 |
| 파일 접근 | 없음 | 포함 |
| 셸 실행 | 없음 | 포함 |
| 도구 오케스트레이션 | 수동 | 포함 |
| MCP 지원 | 수동 | 포함 |
| 서브에이전트 패턴 | 수동 | 더 쉽게 구현 가능 |
코드 리뷰 워커, CI 자동화, 저장소 어시스턴트를 만들고 있다면 SDK는 루프를 손수 구현하는 방식보다 큰 업그레이드입니다.
하지만 경계는 이해해야 합니다. 도구 인터페이스가 있다고 해서 저절로 완전한 기능 런타임이 되는 것은 아닙니다.
설치 및 설정
사전 준비
- Python 3.10+ 또는 Node.js 20+
- Anthropic API 키 또는 Claude Code 접근 권한
- 런타임 실행 표면으로서 설치된 Claude Code CLI
Claude Code CLI 설치
npm install -g @anthropic-ai/claude-code
Agent SDK 설치
Python
pip install claude-agent-sdk
TypeScript
npm install @anthropic-ai/claude-agent-sdk
인증
claude login
첫 번째 에이전트
from claude_agent_sdk import Agent, tool
@tool
def read_file(path: str) -> str:
with open(path, "r") as f:
return f.read()
@tool
def list_files(directory: str = ".") -> list:
import os
return os.listdir(directory)
agent = Agent(
system_prompt="You are a careful code reviewer.",
tools=[read_file, list_files],
model="claude-sonnet-4-20250514"
)
result = agent.run("Review ./src for security issues")
print(result.output)
여기서 SDK의 강점이 드러납니다. 도구를 정의하고 작업을 넘기면, 탐색과 반복은 에이전트 루프가 처리합니다.
핵심 개념
1. 에이전트 루프
작업 → 계획 → 도구 호출 → 관찰 → 재계획 → 최종 답변
이 루프가 바로 SDK의 진짜 가치입니다. 매 턴을 수동으로 연결할 필요를 없애 줍니다.
2. 서브에이전트
서브에이전트는 모든 것을 하나의 긴 컨텍스트에 밀어 넣는 대신 작업을 분해할 수 있게 해줍니다.
agent = Agent(
system_prompt="You are a tech lead reviewing a codebase.",
tools=["task"]
)
병렬 디렉터리 리뷰, 분할 조사, 대규모 코드베이스에 활용하세요.
3. MCP 지원
SDK는 MCP 호환 도구와 통신할 수 있으며, 이는 내부 API, 데이터베이스, 특화 서비스에 유용합니다.
agent = Agent(
mcp_servers=[
{
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
"env": {"ALLOWED_DIRECTORIES": "/project"}
}
]
)
하지만 많은 가이드가 놓치는 미묘한 차이가 있습니다. MCP는 프로토콜 계층이지 전체 기능 전략이 아닙니다. 에이전트에 더 넓고 횡단적인 도구 실행면이 필요하다면, 보통은 서로 무관한 포인트 통합 다섯 개보다 기능 런타임이 더 적합합니다.
프로덕션 고려 사항
비용 제어
일상 작업에는 더 저렴한 모델을 사용하고, max_turns를 설정하며, 넓은 범위의 병렬 작업은 하나의 비대한 세션이 아니라 서브에이전트로 분산하세요.
컨텍스트 관리
프롬프트는 간결하게 유지하고, 불필요한 파일 로딩은 피하며, 세션이 길어질 때는 중간 결과를 요약하세요.
권한
에이전트의 파일 접근과 외부 연동 범위는 꼭 필요한 최소 수준으로 제한하세요.
자주 발생하는 오류와 해결 방법
OverloadedError
지수 백오프로 재시도하세요.
import time
from claude_agent_sdk import OverloadedError
def run_with_retry(agent, prompt, max_retries=3):
for attempt in range(max_retries):
try:
return agent.run(prompt)
except OverloadedError:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
ContextLengthExceededError
작업을 하위 작업으로 나누고, 하나의 거대한 실행 대신 서브에이전트를 사용하세요.
MaxTurnsReached
작업 범위가 명확할 때만 max_turns를 늘리세요. 그렇지 않다면 워크플로를 분해해야 합니다.
권한 오류
에이전트가 실제로 필요한 디렉터리와 연동만 확장하세요.
Agent SDK가 여전히 제공하지 않는 것
이 부분이 프로덕션 워크플로에서 가장 중요합니다.
Claude Code Agent SDK가 할 수 있는 일은 다음과 같습니다.
- 파일 읽기와 편집
- 셸 명령 실행
- 도구 호출 오케스트레이션
- 반복형 에이전트 루프 관리
하지만 이것만으로는 다음을 위한 빠진 기능 계층을 제공하지 못합니다.
- 실시간 웹 검색
- 이미지 생성
- 비디오 생성
- 클라우드 저장 및 공유
- 웹 퍼블리싱
그래서 많은 팀이 데모에서는 인상적이지만 실제로는 불완전한 에이전트를 갖게 됩니다. 에이전트는 런치 페이지에 대해 훌륭하게 추론할 수 있지만, 추가 인프라 없이는 히어로 이미지를 만들고, 최종 산출물을 저장하고, 결과물을 게시할 수 없습니다.
AnyCap이 들어가는 위치
여기서 AnyCap은 Claude 기반 에이전트가 실행에 활용할 수 있는 기능 런타임으로 이해하는 것이 가장 적절합니다.
계층을 분리하면 아키텍처가 더 깔끔해집니다.
- Claude 모델 → 생각한다
- Claude Code Agent SDK → 오케스트레이션한다
- AnyCap CLI → 횡단 기능을 실행한다
- AnyCap 스킬 → 에이전트가 그 CLI를 효과적으로 사용하도록 가르친다
기능 런타임 설치
curl -fsSL https://anycap.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
anycap login
스킬 계층 추가
npx -y skills add anycap-ai/anycap -a claude-code
그다음부터 에이전트는 다음과 같은 작업에 일관된 기능 실행면을 사용할 수 있습니다.
anycap search "latest competitor pricing"
anycap image generate "product hero image"
anycap video generate "10-second launch teaser"
anycap drive upload ./report.pdf
anycap page publish ./launch-brief.md
이것이 “에이전트 루프를 만들었다”와 “실제로 일을 끝낼 수 있는 에이전트를 만들었다”의 차이입니다.
언제 Agent SDK를 써야 하나
다음이 필요하다면 Agent SDK를 사용하세요.
- 제품이나 자동화 안에서 동작하는 프로그래밍 가능한 에이전트
- 반복 가능한 코드 리뷰 워커
- CI/CD 내부의 저장소 어시스턴트
- 반복형 에이전트 루프가 필요한 백그라운드 작업
에이전트가 조사, 미디어 생성, 파일 전달, 결과 게시까지 해야 한다면 기능 런타임을 함께 사용해야 합니다.
핵심 정리
Claude Code Agent SDK가 강력한 이유는 오케스트레이션 문제를 해결하기 때문입니다. 개발자가 Claude Code의 루프를 처음부터 만들지 않아도 되도록, 그 프로그래밍 가능한 버전을 제공합니다.
하지만 그것은 여전히 셸과 조정 계층일 뿐입니다.
에이전트가 실제 세계와 상호작용해야 한다면 — 최신 정보를 검색하고, 크리에이티브 자산을 만들고, 결과물을 저장하고, 결과를 게시해야 한다면 — 빠진 기능 계층도 필요합니다.
이 사고방식이 팀이 SDK 단독의 능력을 과대평가하지 않도록 해줍니다.
SDK는 에이전트를 프로그래밍 가능하게 만듭니다.
기능 런타임은 에이전트를 코드 바깥에서도 유용하게 만듭니다。