Claude Agent SDK: 에이전트 구축 방법 (2026)

TL;DR

• Claude Agent SDK는 자체 코드에서 AI 에이전트를 구축하기 위한 Anthropic의 라이브러리입니다 — Claude Code를 구동하는 것과 동일한 에이전트 엔진이 Python (3.10+)용 claude-agent-sdk 및 TypeScript용 @anthropic-ai/claude-agent-sdk로 공개된 것입니다.
• 2025년 말에 `claude-code-sdk`에서 이름이 변경되었습니다. 튜토리얼에서 ClaudeCodeOptions라고 한다면 오래된 내용입니다 — 이제 클래스는 ClaudeAgentOptions입니다.
• 전체 에이전트 루프를 무료로 사용할 수 있습니다: 파일 도구, Bash, 웹 검색, @tool을 통한 커스텀 도구, MCP 서버(Jira 또는 Shopify를 연결하는 방식), 서브에이전트, 훅, 권한이 포함됩니다. 비용은 Claude API 토큰에 대해서만 지불합니다.
• Anthropic Messages API와 통신하므로 ANTHROPIC_BASE_URL을 사용해 게이트웨이를 가리키도록 설정할 수 있습니다 — 저희는 [Velokey](https://api.velokey.ai)의 /v1/messages 엔드포인트를 대상으로 테스트했으며, 크레딧 결제가 적용된 하나의 키로 실행됩니다.

지금 모두가 에이전트를 만들고 있지만, 대부분의 가이드는 10줄짜리 퀵스타트에서 멈춥니다. 이 글은 그 이후에 일어나는 일을 다룹니다: 흔한 Node 함정 없이 설치하는 방법, Jira 및 Shopify 같은 실제 도구를 연결하는 방법, 실행 비용이 실제로 얼마나 드는지, 그리고 게이트웨이를 통해 라우팅하는 방법까지 살펴봅니다. 시작해 보겠습니다.

Claude Agent SDK란 무엇인가요?

Claude Agent SDK는 자체 애플리케이션에 Claude Code 내부에서 실행되는 것과 동일한 자율 에이전트 루프를 제공하는 라이브러리입니다 — 파일 읽기 및 쓰기, 명령 실행, 웹 검색, 도구 호출을 수행하며, 도구 호출 루프를 직접 작성할 필요가 없습니다. Anthropic은 Python 및 TypeScript용으로 제공하며, 공식 문서에 따르면 Claude에서 프로덕션 에이전트를 구축하는 데 지원되는 방식입니다.

대부분의 사람들이 놓치는 중요한 맥락: 이전에는 Claude Code SDK라고 불렸습니다. Anthropic은 2025년 말에 이를 Claude Agent SDK로 이름을 변경하여, 이것이 코딩 도구만이 아니라 *모든* 에이전트를 구축하기 위한 것임을 나타냈습니다. 패키지, import, 그리고 하나의 핵심 클래스가 모두 변경되었습니다 — claude-code-sdk는 claude-agent-sdk가 되었고, ClaudeCodeOptions는 ClaudeAgentOptions가 되었습니다. 많은 블로그 게시물과 Stack Overflow 답변은 여전히 이전 이름을 참조하므로, import가 실패한다면 보통 그 이유 때문입니다.

내부적으로 SDK는 Claude Code CLI를 subprocess로 래핑합니다. Python 또는 TypeScript 코드는 SDK와 통신하고, SDK는 번들된 CLI를 구동하며, CLI는 Claude와 통신합니다. 이 아키텍처가 중요한 이유는 두 가지이며, 뒤에서 다시 다루겠습니다: CLI는 Node binary이므로 Python SDK를 사용하더라도 Node가 설치되어 있어야 하고, CLI는 system prompt에 대해 공격적인 prompt caching을 수행합니다(이는 비용 계산을 바꿉니다).

Claude Agent SDK를 설치하고 사용하는 방법은?

PyPI(또는 npm)에서 Claude Agent SDK를 설치하고, API 키를 설정한 뒤 query()를 호출하세요 — 동작하는 에이전트는 약 ten 줄이면 됩니다. Python은 3.10 이상이 필요합니다:

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

다음은 최소한의 일회성 에이전트입니다. query()는 메시지의 비동기 이터레이터를 반환합니다:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List the Python files in this repo and summarize each."):
        print(message)

anyio.run(main)

대화형 또는 멀티턴 작업에는 ClaudeSDKClient를 사용하고 ClaudeAgentOptions로 구성하세요:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

사람들이 자주 막히는 설치 관련 함정이 두 가지 있으며, 둘 다 ten-line 빠른 시작에는 없습니다:

Claude Agent SDK로 무엇을 만들 수 있나요?

파일 액세스, 명령 실행 또는 도구 사용이 필요한 모든 에이전트를 만들 수 있습니다 — 코드 리뷰어부터 고객 지원 분류 담당자, 데이터 파이프라인 운영자까지. SDK는 5개의 빌딩 블록을 제공하며, 전체 설계의 핵심은 에이전트가 무엇을 할 수 있는지 제어하는 것입니다:

커스텀 도구는 가장 깔끔한 부분입니다. 함수에 데코레이터를 붙이면 에이전트가 이를 직접 호출할 수 있습니다 — 별도 프로세스도, 네트워크 홉도 없습니다:

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

훅과 권한은 데모를 무인으로 실행할 수 있는 것으로 바꿔 줍니다. PreToolUse 훅은 위험한 패턴과 일치하는 Bash 명령을 차단할 수 있고, permission_mode는 에이전트가 승인을 위해 일시 중지할지 또는 편집을 자동 수락할지를 결정합니다. 프로덕션에서는 대부분의 팀이 엄격한 allowed_tools 목록으로 시작한 뒤 에이전트를 신뢰하게 될수록 이를 열어 갑니다 — 완전히 개방된 quickstart와는 반대입니다.

여섯 번째 블록이자, 단일 에이전트가 느려지면 사람들이 찾게 되는 것은 서브에이전트입니다. SDK는 자체 컨텍스트를 가진 새로운 서브에이전트를 생성해 범위가 정해진 하위 작업을 처리하게 한 다음, 결과를 다시 전달할 수 있습니다 — Claude Code는 이를 사용해 여러 파일에 걸쳐 작업을 분산합니다. 이는 "여러 작업을 병렬로 처리할 수 있나"와 "메인 컨텍스트가 가득 차지 않게 하려면 어떻게 하나"에 대한 내장된 해답입니다: 여러 파일 읽기, 테스트 매트릭스 실행 같은 시끄러운 작업은 서브에이전트에 위임하여 메인 에이전트가 집중을 유지하게 합니다. 세션 포킹은 진행 중인 대화를 분기하는 관련 기법입니다.

Jira 또는 Shopify를 Claude Agent SDK와 어떻게 통합하나요?

Jira, Shopify 또는 외부 시스템은 해당 MCP server를 ClaudeAgentOptions의 mcp_servers에 추가하여 통합합니다 — SDK에는 Jira 전용 코드가 있는 것이 아니라, 개방형 Model Context Protocol을 사용하며, Atlassian과 Shopify 모두 MCP servers를 제공합니다. 이는 가장 많이 묻는 통합 질문("Claude Agent SDK에 Jira/Shopify를 연결하는 방법")에 대한 답입니다. 특별한 connector는 없으며, MCP server를 등록하고 해당 tools를 허용하면 됩니다.

패턴은 둘 다 동일합니다. SDK가 MCP server(로컬 command 또는 원격 URL)를 가리키도록 한 다음, 해당 server가 노출하는 tools를 허용합니다:

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Find open bugs assigned to me and summarize them.")
    async for msg in client.receive_response():
        print(msg)

server 블록을 @shopify/mcp-server(Shopify token 포함)로 바꾸면 동일한 agent가 orders를 읽거나 products를 업데이트할 수 있습니다. 정확히 맞춰야 할 점은 두 가지입니다. tool 이름은 mcp__<server>__<tool> 규칙을 따르므로 allowed_tools 항목이 정확히 일치해야 하며, 각 MCP server에는 env에 자체 credential이 필요합니다. agent가 tool을 사용할 수 없다고 말한다면, 거의 항상 SDK 버그가 아니라 이름 불일치 또는 누락된 token 때문입니다.

vendor가 로컬 command 대신 원격 MCP server를 호스팅하는 경우, command/args가 아니라 URL로 등록하세요 — {"jira": {"url": "https://mcp.atlassian.com/v1/sse"}} — 그러면 SDK가 네트워크를 통해 연결합니다. 로컬(stdio) servers는 개발에 더 간단하고 token을 내 컴퓨터에 보관할 수 있게 해 주며, 원격(URL) servers는 별도 설치가 필요 없게 해 줍니다. 어느 쪽이든 allowed_tools 및 server별 credential 규칙은 동일합니다.

게이트웨이를 통해 Claude Agent SDK를 실행하려면 어떻게 하나요?

ANTHROPIC_BASE_URL을 게이트웨이의 루트로 설정하면, SDK는 모든 요청을 api.anthropic.com 대신 그곳으로 보냅니다 — 코드 변경은 필요 없습니다. SDK는 표준 Anthropic 환경 변수를 따르므로, Anthropic Messages API (/v1/messages)를 노출하는 모든 백엔드가 작동합니다: 기업용 프록시, 지역 브리지, 또는 통합 게이트웨이.

저희는 Anthropic 호환 /v1/messages 엔드포인트를 노출하는 [Velokey](https://api.velokey.ai)를 대상으로 이를 테스트했습니다. 여기에 보낸 라이브 요청은 표준 Messages 응답(stop_reason: end_turn, Anthropic 형태의 사용량)을 반환했으며, 이는 SDK가 기대하는 것과 정확히 일치합니다:

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-your-velokey-key"
# then run your agent as usual — set the model to one Velokey serves:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # or claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

애초에 왜 에이전트를 게이트웨이를 통해 라우팅할까요? 별도의 Anthropic 계정, 티어, 30-day-retention 설정 대신 하나의 키만 사용하면 되고, 한도를 설정할 수 있는 크레딧 기반 과금이 가능하며, 동일한 키로 [Claude Opus 4.8](/model/claude-opus-4-8), [Claude Sonnet 5](/model/claude-sonnet-5), 그리고 다른 곳에서 사용할 수 있는 기타 모델에 접근할 수 있습니다. 프록시가 x-api-key 헤더 대신 bearer token을 요구한다면, ANTHROPIC_API_KEY가 아니라 ANTHROPIC_AUTH_TOKEN을 설정하세요. 이는 OpenAI 호환 도구가 게이트웨이를 가리키도록 하는 것과 같은 드롭인 방식입니다 — OpenAI 형식의 동등한 예시는 저희 Qwen CLI 가이드를 참고하세요.

Claude Agent SDK 비용은 얼마인가요?

SDK 자체는 무료 오픈 소스입니다 — 비용은 에이전트가 소비하는 Claude API 토큰에 대해 지불하며, 에이전트는 토큰을 많이 소비합니다. 매 턴마다 늘어나는 대화가 다시 전송되고, 모든 도구 결과가 컨텍스트로 돌아오며, 단일 "이 버그를 수정해 줘" 작업도 10회 이상의 턴으로 실행될 수 있습니다. 이것이 비용 측면의 놀라운 점입니다. 코드는 10줄이지만, 토큰 청구액은 에이전트가 얼마나 많이 탐색하느냐에 따라 증가합니다.

이를 제어하는 3가지 레버가 있으며, SDK는 그중 가장 큰 것을 기본으로 제공합니다:

마지막 행은 이론이 아니라 실제입니다. 테스트 요청에서 응답은 수만 개의 cache_read_input_tokens를 보고했으며, 이는 큰 시스템 프롬프트가 매 턴마다 다시 청구되는 대신 입력 가격의 대략 10분의 1 수준으로 캐시에서 제공되었음을 의미합니다. 이것이 에이전트 비용이 턴 수가 시사하는 것만큼 가혹하지 않은 주된 이유입니다. 모델별 전체 토큰 계산은 Claude API pricing guide를 참조하세요. 에이전트를 연결하기 전에 Claude 모델에 대한 작동하는 단일 호출을 원한다면, how to call Claude with an API key에서 기본 사항을 다룹니다.

자주 묻는 질문

Claude Agent SDK란 무엇인가요?

Anthropic의 공식 라이브러리로, Claude Code를 구동하는 것과 동일한 자율 에이전트 루프를 사용해 Python 또는 TypeScript에서 AI 에이전트를 구축할 수 있습니다. 도구 호출 루프, 파일 작업, 명령 실행, MCP 통합을 대신 처리해 주므로, 오케스트레이션이 아니라 목표와 도구만 작성하면 됩니다. 비용은 Claude API 토큰에 대해서만 지불합니다.

Claude Agent SDK는 Claude Code SDK와 같은 것인가요?

예 — 이름이 변경된 버전입니다. Anthropic은 2025년 말에 claude-code-sdk를 claude-agent-sdk로 이름을 바꾸었고, ClaudeCodeOptions는 ClaudeAgentOptions가 되었습니다. 기능은 그대로 이어졌으며, 패키지와 클래스 이름만 변경되었습니다. 튜토리얼에서 이전 이름을 import한다면, 이름 변경 이전의 자료이며 현재 패키지에서는 import가 실패합니다.

Claude Agent SDK는 어떻게 설치하나요?

pip install claude-agent-sdk (Python 3.10+)를 실행하거나 TypeScript의 경우 npm install @anthropic-ai/claude-agent-sdk를 실행한 다음, ANTHROPIC_API_KEY를 설정하세요. SDK는 번들로 제공되는 Claude Code CLI를 서브프로세스로 구동하므로, Python 패키지를 사용하는 경우에도 Node.js가 설치되어 있어야 합니다 — Node가 없는 것이 가장 흔한 설치 실패 원인입니다.

Jira 또는 Shopify를 Claude Agent SDK 에이전트에 어떻게 연결하나요?

벤더의 MCP 서버를 ClaudeAgentOptions의 mcp_servers에 추가하고 해당 도구를 허용하세요. Atlassian (Jira)과 Shopify는 모두 MCP 서버를 제공하므로, 작성해야 할 커스텀 커넥터는 없습니다 — API 토큰으로 서버를 등록하고 해당 도구들(mcp__<server>__<tool>이라는 이름)을 allowed_tools에 나열하면 됩니다.

Claude Agent SDK는 게이트웨이 또는 프록시와 함께 작동하나요?

예. ANTHROPIC_BASE_URL 환경 변수를 따르므로, 코드 변경 없이 Anthropic Messages API (/v1/messages)를 노출하는 모든 백엔드로 라우팅됩니다. Velokey의 Anthropic 호환 엔드포인트에 대해 실제 요청을 검증했습니다. x-api-key 프록시에는 ANTHROPIC_API_KEY를 사용하고, bearer-token 방식에는 ANTHROPIC_AUTH_TOKEN을 사용하세요.

Claude Agent SDK는 어떤 모델을 사용하나요?

지정한 엔드포인트를 통해 Claude 모델을 사용합니다 — 기본값은 Anthropic의 최신 모델이며, model 옵션을 통해 특정 모델을 설정할 수 있습니다(예: claude-sonnet-5 또는 claude-opus-4-8). 게이트웨이를 통해서는 해당 게이트웨이가 제공하는 모든 Claude 모델을 선택할 수 있으며, 이는 일상적인 에이전트 실행에 더 저렴한 모델을 사용할 때 유용합니다.

Claude Agent SDK는 무료인가요?

SDK는 무료이며 오픈 소스이지만, 에이전트를 실행하면 Claude API 토큰 비용이 발생하고, 다중 턴 에이전트 루프는 이를 빠르게 사용합니다. 일상적인 작업에는 더 저렴한 모델을 선택하고, max_turns를 설정하며, 도구 접근을 제한해 지출을 관리하세요 — 또한 반복되는 시스템 프롬프트를 입력 가격의 대략 10분의 1 수준으로 제공하는 내장 프롬프트 캐싱을 활용하세요.