Anthropic의 Agent SDK는 Claude Code를 터미널 도우미에서 여러분의 워크플로에 넣어 사용할 수 있는 프로그래밍 가능하고 자동화 가능한 AI 에이전트로 바꿔 줍니다. 이 가이드는 설치, 에이전트 루프, 도구 통합, MCP 서버, 서브에이전트 오케스트레이션, 그리고 실서비스에서 필요한 기능 격차까지 모두 다룹니다.
Claude Code Agent SDK란 무엇인가요?
Claude Code Agent SDK는 Claude Agent SDK 또는 Claude Code SDK라고도 불리며, Claude 기반의 자율 AI 에이전트를 만들기 위한 Anthropic의 Python 및 TypeScript 라이브러리입니다. Claude Code CLI를 구동하는 것과 같은 에이전트 루프, 도구 시스템, 샌드박스 실행 환경을 감싸서, 여러분의 코드에서 호출할 수 있는 SDK 형태로 제공합니다.
이 SDK는 AI 에이전트를 단순히 대화형이 아니라 프로그래밍 가능하게 만들겠다는 Anthropic의 2026년 초 방향성의 일부로 공개되었습니다.
Claude API를 직접 사용하는 것과 다른 점
| 기능 | Claude API | Claude Agent SDK |
|---|---|---|
| 에이전트 루프 | 직접 구현 | 내장됨: 계획 → 실행 → 관찰 → 반복 |
| 파일 시스템 접근 | 없음 | 파일 읽기, 쓰기, 수정 |
| 셸 실행 | 없음 | 샌드박스 안에서 Bash 명령 실행 |
| 도구 호출 | 수동 함수 정의 | 내장 도구 + MCP 서버 지원 |
| 서브에이전트 | 사용 불가 | 병렬 에이전트 워커 실행 |
| 컨텍스트 관리 | 수동 | 자동 압축 및 요약 |
지금 Claude API를 사용하면서 수동 도구 처리가 포함된 에이전트 루프를 직접 만들고 있다면, Agent SDK는 수백 줄의 보일러플레이트를 대체해 줍니다.
설치 및 설정
사전 요구 사항
- Python 3.10+ 또는 TypeScript/Node.js 20+
- Anthropic API 키 또는 Claude Code Pro/Max/Enterprise 구독
- Claude Code CLI 설치 완료, SDK가 런타임으로 사용함
1단계: Claude Code CLI 설치
npm install -g @anthropic-ai/claude-code
또는 claude.ai/download에서 네이티브 설치 프로그램을 사용하세요.
2단계: Agent SDK 설치
Python:
pip install claude-agent-sdk
TypeScript:
npm install @anthropic-ai/claude-agent-sdk
3단계: 인증하기
claude login
OAuth 흐름을 따라가세요. API 키는 로컬에 저장되며 SDK가 자동으로 사용합니다.
첫 번째 에이전트: 버그 탐지기
다음은 디렉터리에서 버그를 찾는 최소한의 Python 에이전트 예시입니다.
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="당신은 코드 리뷰어입니다. 버그를 찾고 수정안을 제안하세요.",
tools=[read_file, list_files],
model="claude-sonnet-4-20250514"
)
result = agent.run("./src의 코드를 보안 문제 관점에서 검토하세요")
print(result.output)
내부에서 실제로 일어나는 일
- 에이전트가 작업을 받고 시스템 프롬프트를 읽습니다
- 코드베이스를 파악하기 위해
list_files("./src")를 호출합니다 - 각 소스 파일에 대해
read_file(path)를 호출합니다 - Claude의 추론 능력으로 코드를 분석합니다
- 줄 번호와 수정 제안을 포함한 결과를 반환합니다
SDK가 전체 루프를 처리하므로, 계획-실행-관찰 로직을 직접 작성할 필요가 없습니다.
핵심 개념
에이전트 루프
작업 → 계획 → 도구 호출 → 결과 관찰 → 재계획 → ... → 최종 답변
각 반복에서:
- Claude가 다음에 무엇을 할지 결정합니다
- 필요하면 도구를 호출해 실행합니다
- 도구 출력을 받아 관찰합니다
- 계속할지 종료할지 결정합니다
SDK는 압축과 서브에이전트 위임을 통해 컨텍스트 창 한계를 자동으로 관리합니다.
도구와 tool 데코레이터
도구는 에이전트에게 노출하는 함수입니다. SDK는 여러 기본 도구를 제공합니다.
# 기본 파일 작업 도구, 자동 사용 가능
agent = Agent(
tools=["read", "write", "edit", "glob", "grep", "bash", "task"]
)
사용자 정의 도구는 @tool 데코레이터를 사용합니다.
from claude_agent_sdk import tool
@tool
def search_docs(query: str, max_results: int = 5) -> str:
"""주어진 검색어로 내부 문서를 찾습니다."""
# 검색 구현
return results
agent = Agent(tools=[search_docs])
서브에이전트: 병렬 처리
서브에이전트는 독립적인 Claude 인스턴스를 띄워 병렬 작업을 수행하게 해 줍니다.
agent = Agent(
system_prompt="당신은 코드베이스를 검토하는 테크 리드입니다.",
tools=["task"] # 서브에이전트 실행 활성화
)
result = agent.run("""
./frontend/와 ./backend/를 병렬로 검토하세요.
각 디렉터리마다 서브에이전트를 사용한 뒤 결과를 통합하세요.
""")
서브에이전트는 분리된 컨텍스트에서 실행되고 독립적으로 결과를 반환합니다. Claude Code 자체가 대규모 작업을 처리하는 방식도 이것과 같습니다.
MCP 서버 통합
SDK는 Model Context Protocol, 즉 외부 서비스가 에이전트에게 도구를 제공하는 MCP 서버를 지원합니다.
agent = Agent(
mcp_servers=[
{
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
"env": {"ALLOWED_DIRECTORIES": "/project"}
}
]
)
MCP 서버는 데이터베이스 접근, API 연동, 제3자 서비스 등을 추가할 수 있습니다.
Agent SDK가 할 수 없는 것과 그 격차를 메우는 방법
Claude Code Agent SDK는 에이전트에게 파일 접근, 셸 실행, 코드 조작 기능을 제공합니다. 하지만 다섯 가지 중요한 기능 격차가 있습니다.
1. 이미지 생성
에이전트는 이미지 API를 호출하는 코드를 작성할 수는 있지만, 이미지를 직접 생성하거나 볼 수는 없습니다. UI를 만들거나 디자인을 시제품화하거나 문서를 만드는 에이전트에게는 이것이 큰 제약입니다.
해결책: 이미지 생성을 처리하는 기능 런타임을 에이전트에 제공하세요. 설정 한 줄만으로 텍스트에서 이미지를 생성하고, 디자인을 반복 개선하며, 결과를 삽입할 수 있습니다.
2. 동영상 생성
동영상은 더 멀리 있습니다. 에이전트는 ffmpeg 명령을 작성할 수 있지만, 새로운 비디오 콘텐츠를 생성할 수는 없습니다.
3. 근거가 있는 결과를 제공하는 웹 검색
Claude Code 에이전트는 curl이나 fetch API를 사용할 수 있지만, 근거와 인용이 포함된 의미 기반 웹 검색은 수행할 수 없습니다. 이는 리서치 에이전트, 콘텐츠 에이전트, 최신 정보가 필요한 모든 워크플로에서 중요합니다.
4. 클라우드 저장소와 파일 공유
SDK의 파일 시스템 접근은 로컬 전용입니다. 결과를 저장하거나, 파일을 사람과 공유하거나, 세션 간 데이터를 유지해야 하는 에이전트라면 클라우드 저장소가 필요합니다.
5. 퍼블리싱과 배포
에이전트가 산출물을 만들 수는 있지만, 그것을 웹페이지나 공유 가능한 보고서, 배포된 앱으로 온라인에 올리려면 별도의 인프라가 필요합니다.
원클릭 해결
각각 별도의 API 키와 유지 관리, 토큰 오버헤드가 있는 다섯 개의 MCP 서버를 따로 설정하는 대신, 이미지 생성, 동영상, 웹 검색, 클라우드 저장소, 퍼블리싱을 하나의 엔드포인트로 묶는 기능 런타임을 사용할 수 있습니다.
예를 들어 AnyCap은 하나의 CLI 안에 이미지 생성, 동영상, 웹 검색, 클라우드 저장소, 페이지 퍼블리싱의 다섯 가지 기능을 제공하므로, 몇 시간 대신 몇 분 만에 설정을 끝낼 수 있습니다.
실서비스 고려 사항
컨텍스트 창 관리
Agent SDK는 컨텍스트 압축을 자동으로 처리하지만, 100턴 이상 길게 실행되는 에이전트라면 다음을 권장합니다.
- 서브에이전트 사용: 큰 병렬 작업은 순차 처리보다 서브에이전트로 처리
- 시스템 프롬프트를 간결하게 유지: 시스템 프롬프트의 모든 토큰은 매 턴 오버헤드
- 큰 파일 로딩을 피하기: 도구가 대신 요약을 반환할 수 있으면 컨텍스트에 넣지 않기
비용 관리
SDK를 사용하는 일반적인 에이전트 세션 비용은 작업 복잡도에 따라 0.50달러에서 3.00달러 정도입니다. 비용을 통제하려면:
max_turns를 설정해 무한 루프 방지- 단순한 서브에이전트에는 Haiku, 메인 에이전트에는 Sonnet 사용
- Anthropic 콘솔 대시보드로 사용량 모니터링
보안
SDK는 명령을 샌드박스에서 실행하지만, 다음은 여전히 지켜야 합니다.
ALLOWED_DIRECTORIES로 파일 시스템 접근 제한- 프로덕션 에이전트에 자격 증명이나
.env파일 접근 권한을 주지 않기 - 비대화형 모드에서는 에이전트 동작을 검토하기
Claude Code SDK vs Claude Agent SDK: 차이점은 무엇인가요?
이 용어들은 종종 같은 의미로 쓰이지만, 차이가 있습니다.
| Claude Code SDK | Claude Agent SDK | |
|---|---|---|
| 범위 | Claude Code와 상호작용하기 위한 하위 수준 API | 더 높은 수준의 에이전트 프레임워크 |
| Python 패키지 | claude-agent-sdk의 일부 |
주 인터페이스인 claude-agent-sdk |
| 사용 사례 | Claude Code 세션의 프로그래밍 제어 | 자율 에이전트 구축 |
| 문서 | code.claude.com/docs/en/agent-sdk | code.claude.com/docs/en/agent-sdk/overview |
실제로는 대부분의 개발자가 Agent SDK를 진입점으로 사용합니다. 더 낮은 수준의 SDK API는 사용자 정의 세션 관리 같은 고급 사용 사례를 위한 것입니다.
Claude Code CLI 대신 Agent SDK를 사용할 때
| 시나리오 | 사용 |
|---|---|
| 대화형 코딩 세션 | Claude Code CLI |
| 일회성 코드 리뷰 | Claude Code CLI |
| 자동화된 PR 리뷰 파이프라인 | Agent SDK |
| 예약된 데이터 처리 | Agent SDK |
| CI/CD 통합 | Agent SDK |
| 다단계 리서치 에이전트 | Agent SDK |
| Claude 위에 제품 구축 | Agent SDK |
간단한 기준은 이렇습니다. 명령을 직접 입력한다면 CLI를 사용하세요. Claude를 호출하는 코드를 작성한다면 SDK를 사용하세요.
요약
Claude Code Agent SDK는 Claude를 터미널 동반자에서 프로그래밍 가능한 에이전트 런타임으로 바꿉니다. 내장된 파일 작업, 셸 접근, 서브에이전트 오케스트레이션, MCP 서버 지원으로 에이전트 인프라의 무거운 작업을 처리합니다.
하지만 파일만 읽고 bash만 실행할 수 있는 에이전트는 절반짜리 에이전트에 불과합니다. 웹 검색, 이미지와 동영상 생성, 결과의 클라우드 저장, 결과 퍼블리싱까지 가능한 에이전트를 만들려면 기능 계층이 필요합니다. SDK는 에이전트에게 두뇌를 주고, AnyCap 같은 기능 런타임은 눈과 손과 목소리를 줍니다.