Claude Agent SDK 사용법: 커스텀 에이전트 빌드 실전 가이드

claude agent sdk 한 줄 요약

claude agent sdk는 Python이면 pip install claude-agent-sdk, TypeScript면 npm install @anthropic-ai/claude-agent-sdk로 바로 시작돼요. 2025년 9월부터 Claude Code SDK의 새 이름이고, 서드파티 제품에 붙일 때는 claude.ai 구독 로그인 대신 API 키를 써야 하거든요. 장기 비동기 작업까지 Anthropic 인프라에 맡기고 싶으면 Managed Agents가 맞고, 로컬 제어나 내 서버 통합이 우선이면 Agent SDK 쪽이 더 낫죠.

Claude Code SDK로 검색하면 문서 제목이 다르고, GitHub 이슈는 Agent SDK라고 써 있어서 처음엔 다른 제품인 줄 알았어요. 이름만 바뀐 줄 알았는데, 막상 붙여보니 더 얽히더라고요. Python 패키지, TypeScript 패키지, API 키 정책, GitHub Copilot 연동, Managed Agents까지 한 번에 섞여 있거든요. 거기다 allowed_tools 하나 넣었다고 도구가 제한되는 줄 알았다가, 실제론 자동 승인만 붙는다는 걸 나중에 알면 시간 꽤 날려요. 저도 spawn node ENOENT 한 번 맞고, thinking이 왜 안 보이냐고 로그만 뒤지다가 문서랑 이슈를 다시 봤어요.

이번 글은 그 삽질 구간만 잘라서 정리한 버전이에요. claude agent sdk를 내 파이프라인에 라이브러리로 붙일 때 뭐부터 깔아야 하는지, 권한 옵션들이 각각 무슨 역할인지, 세션 재개와 비용 상한을 어디서 걸어야 하는지, 마지막에 claude managed agents로 넘어갈 기준까지 한 번에 보이게 묶어둘게요. 기본적인 Claude Code 감부터 다시 잡고 싶으면 Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드를 먼저 보고 오세요. 여기서는 실전 코드와 함정 위주로 가볼게요.

Claude Agent SDK가 Claude Code SDK였다는 점부터 짚고 갈게요

이름부터 정리해야 설치와 인증이 덜 꼬여요. Claude Agent SDK는 Claude Code SDK의 새 이름이고, 지금은 Python과 TypeScript 라이브러리 기준으로 문서가 묶여 있어요.

왜 claude agent sdk 이름만 바꿨는데 이렇게 헷갈리나요

2025년 9월 리네임 뒤에도 주변 글은 예전 이름을 계속 쓰더라고요. 거기다 비슷한 시기에 Managed Agents, Console, GitHub Copilot의 Anthropic Claude coding agent까지 같이 나오면서 “도대체 어디서 뭘 시작해야 하지?”부터 바로 떠올라요.

구분	지금 진입점	쓸 수 있는 환경	언제 맞나
Claude Agent SDK	`claude-agent-sdk`, `@anthropic-ai/claude-agent-sdk`	Python 앱, Node/TypeScript 앱, CI 파이프라인, 자체 서버, AWS Bedrock, Google Vertex AI, Microsoft Azure AI Foundry 인증 흐름	내 코드 안에서 에이전트를 직접 돌리고 싶을 때
Claude Code	`claude` CLI와 데스크톱, 웹, IDE	터미널, 데스크톱 앱, 웹, VS Code, JetBrains	인터랙티브하게 일 시키고 바로 수정할 때
Claude Managed Agents	Console + API	Claude Console, API 세션, 클라우드 런타임	오래 도는 작업과 비동기 실행을 맡길 때
GitHub Copilot의 Anthropic Claude	GitHub Copilot coding agent	GitHub Copilot 클라우드 에이전트 실행 환경	기존 Copilot 구독 안에서 Claude 기반 작업을 맡길 때

네 가지 진입점 중 내 상황에 맞는 건 뭘까

실무 기준으로는 이렇게 보면 편해요. 로컬에서 코드 읽고 고치게 할 거면 Agent SDK, 사람이 붙어서 바로바로 보정할 거면 Claude Code, 세션과 런타임까지 Anthropic이 들고 가길 원하면 Managed Agents인 셈이죠. GitHub Copilot 쪽 Anthropic Claude는 “Agent SDK가 다른 플랫폼에도 올라간다”는 예로 보면 그림이 빨리 잡혀요.

Claude Agent SDK 공식 overview 문서 상단의 개요 화면 — 공식 overview 문서 첫 섹션에 어떤 환경에서 SDK를 쓰는지 정리돼 있어요. (출처: Anthropic 공식 문서)

로컬에서 Claude Code 감부터 다시 잡고 싶으면 Claude Code CLI 첫 실행 절차부터 보고 오는 편이 빨라요. SDK도 결국 Claude Code가 쓰는 도구와 루프를 코드로 끌어다 쓰는 거거든요.

claude agent sdk 설치와 첫 쿼리, 여기서 막히면 계속 꼬여요

설치는 짧아요. 근데 인증 경로를 먼저 정해야 뒤에서 안 미끄러져요.

API 키는 어디에 저장해야 할까요?

셸 환경변수나 시크릿 매니저에 ANTHROPIC_API_KEY를 넣는 게 기본이에요. 공식 문서는 서드파티 제품이나 앱에 붙이는 Agent SDK 흐름에서 claude.ai 로그인이나 구독 한도를 가져다 쓰지 말고, API 키 인증을 쓰라고 못 박아놨어요. 로컬에서 장난감처럼 한 번 돌리는 수준이 아니라 내 제품에 붙일 생각이면, 처음부터 API 키 기준으로 세팅하는 게 맞아요.

claude agent sdk 설치 순서는 이렇게 잡으면 돼요.

Python이면 3.10+ 환경부터 잡기
TypeScript면 Node.js 18+ 런타임과 패키지 설치 확인하기
ANTHROPIC_API_KEY를 셸 또는 시크릿 매니저에 넣기
첫 쿼리는 읽기 전용 도구부터 좁게 열기

# Python 설치
pip install claude-agent-sdk

# TypeScript 설치
npm install @anthropic-ai/claude-agent-sdk

# API 키 세팅
export ANTHROPIC_API_KEY="sk-ant-..."

첫 쿼리는 공식 예제 흐름을 거의 그대로 쓰면 돼요. 처음부터 Write나 Bash를 다 열지 말고, Read, Glob, Grep처럼 읽기 쪽만 먼저 주는 편이 덜 무서워요.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="TODO 주석을 찾아서 한 번에 요약해줘",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            max_turns=3,
        ),
    ):
        print(message)


asyncio.run(main())

이 정도만 돌아도 흐름이 보여요. 에이전트가 어떤 파일을 읽고, 어떤 도구를 고르고, 결과를 어디서 끊는지 보이거든요. 루프 자체가 아직 추상적으로 느껴지면 AI 에이전트 만들기: 도구 호출부터 워크플로우까지 실전 가이드를 같이 읽어보세요. SDK가 뭘 줄여주는지 훨씬 또렷해져요.

Claude Agent SDK 공식 Quickstart 문서의 Prerequisites와 Setup 구간 — Quickstart 문서는 “Node.js 18+ 또는 Python 3.10+”와 Anthropic 계정 준비를 먼저 확인하라고 알려줘요. (출처: Anthropic 공식 문서)

claude agent sdk 권한 세팅, tools와 allowed_tools를 헷갈리면 손해예요

여기가 제일 많이 꼬여요. tools는 도구 세트 자체를 잡는 옵션이고, allowed_tools는 자동 승인 목록일 뿐이라 역할이 달라요.

이름 비슷한 옵션이 다섯 개나 있는데 왜 이렇게 헷갈릴까요?

문서가 여러 군데로 나뉘어 있어서 그래요. 비슷해 보이지만 실제 의미는 꽤 달라요. allowed_tools를 넣었다고 도구가 사라지는 게 아니고, 목록에 없는 도구는 permission_mode랑 can_use_tool 쪽으로 흘러가요. 여기서 한 번만 틀리면 “왜 막혔지?” 아니면 “왜 이게 그냥 실행됐지?” 둘 중 하나로 바로 빠져요.

옵션	실제 역할	자주 하는 착각
`tools`	세션에 어떤 도구 세트를 싣는지 정의	allowlist라고 착각하기 쉬움
`allowed_tools`	명시한 도구를 자동 승인	목록 밖 도구가 아예 안 보인다고 착각함
`disallowed_tools`	특정 도구를 무조건 차단	`allowed_tools`가 이길 거라고 생각함
`permission_mode`	남은 도구를 어떤 모드로 처리할지 결정	모든 권한 판단을 대신한다고 생각함
`can_use_tool`	위 단계에서 안 끝난 요청을 런타임에 판단	무조건 제일 먼저 불린다고 생각함

공식 문서 기준 권한 판단 순서는 이 순서예요.

Hooks(도구 실행 전후에 끼워 넣는 콜백)
disallowed_tools와 deny 규칙
permission_mode
allowed_tools와 allow 규칙
can_use_tool

공식 overview에 먼저 나오는 핵심 도구 묶음도 한 번 기억해두세요. Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, TodoWrite, AskUserQuestion가 먼저 나오고, 서브에이전트는 Task 도구로 따로 붙어요.

실전에서는 텍스트 응답만 길게 받는 것보다, 필요한 구조를 도구로 빼는 쪽이 더 안정적일 때가 많아요. 코드 리뷰 결과를 JSON 비슷하게 억지로 뽑게 하기보다, 저장용 도구를 하나 붙이고 그걸 호출하게 만드는 식이죠.

from claude_agent_sdk import tool, create_sdk_mcp_server


@tool("save_issue", "이슈를 저장해요", {"title": str, "severity": str})
async def save_issue(args):
    return {
        "content": [
            {
                "type": "text",
                "text": f"saved: {args['title']} ({args['severity']})",
            }
        ]
    }


review_tools = create_sdk_mcp_server(
    name="review-tools",
    version="1.0.0",
    tools=[save_issue],
)

이 패턴을 저는 “텍스트 대신 도구로 받기”라고 기억해요. 출력 포맷 강제보다 덜 흔들리고, 후처리도 쉬워지거든요. 외부 도구를 더 깊게 붙일 생각이면 MCP 서버 직접 만들기: Python FastMCP 30분 빌드 가이드까지 이어서 보면 흐름이 바로 연결돼요.

세션 재개와 비용 상한, 프로덕션에 넣으려면 여기까지

한 번 끊긴 작업을 이어가고, 예상 못 한 비용을 막는 건 초반부터 넣어야 해요. 이거 빠지면 데모는 되는데 운영에서 금방 새기 시작해요.

한 번 끊긴 세션을 매번 처음부터 다시 읽게 둘 건 아니죠?

공식 overview 예제대로 가면 system/init에서 session_id를 잡아서 이어붙일 수 있어요. 여기에 max_turns, max_budget_usd, 그리고 파일 변경 감사 로그까지 묶어두면 프로덕션 기본 골격은 거의 나와요.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage


async def main():
    session_id = None

    async for message in query(
        prompt="auth 모듈을 읽고 구조를 요약해줘",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob"],
            max_turns=3,
        ),
    ):
        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", "Glob", "Grep"],
            max_turns=4,
            max_budget_usd=0.50,
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)


asyncio.run(main())

처음 붙일 때는 아래 다섯 개부터 넣으면 돼요.

session_id 캡처해서 재개 흐름 만들기
max_turns로 루프 길이 자르기
max_budget_usd로 비용 상한 걸기
읽기 전용 도구와 수정 도구를 처음부터 분리하기
PostToolUse 훅으로 변경 로그 남기기

비용 감도 같이 잡아둘 만해요. 2026-04-18 기준 API 가격은 Claude Haiku 4.5가 입력 $1 / 출력 $5, Claude Sonnet 4.6이 입력 $3 / 출력 $15, Claude Opus 4.6이 입력 $5 / 출력 $25예요. 백만 토큰 기준이고, 캐시 히트는 입력 가격의 10%라서 같은 긴 프롬프트를 자주 읽히는 워크로드에선 체감 차이가 꽤 나요.

파일 변경 감사나 자동 검수 훅을 같이 붙일 생각이면 Claude Code Hooks 완벽 가이드 – 자동화 훅 설정법을 같이 보는 게 좋아요. Agent SDK에서도 같은 습관이 그대로 먹히거든요.

설치하고 나서 다들 한 번씩 밟는 함정 5가지

설치 명령은 쉬운데, 실제 앱이나 파이프라인에 얹는 순간 다른 문제가 튀어나와요. 여기서 시간을 제일 많이 버려요.

Claude Agent SDK에서 왜 node를 spawn하는 거죠

SDK 내부가 Claude Code 쪽 실행 흐름을 감싼 형태라서 그래요. 로컬 개발에선 멀쩡한데 패키징, Electron, 서브에이전트, thinking 디버깅 쪽으로 가면 바로 까다로워져요. 제가 먼저 체크하는 건 아래 다섯 가지예요.

증상	왜 생기나	바로 할 조치
`spawn node ENOENT`	하위 프로세스가 Node 런타임을 못 찾거나 번들 환경에서 PATH 환경 변수가 꼬임	실행 환경 PATH부터 확인하고, 번들러면 런타임 외부화 검토
Electron 패키징 후 경로 깨짐	Electron 패키징 아카이브인 `asar` 안에서 CLI 경로나 종속 파일이 기대대로 안 보임	SDK 관련 의존성 unpack 여부 확인
API 키가 내가 준 값이 아닌 것처럼 동작	환경 변수와 파일 기반 설정이 섞여 우선순위가 헷갈림	`setting_sources`를 최소 범위로 두고 실제 적용 설정 로그 확인
thinking이 안 보임	SDK가 tool 결과는 보여줘도 thinking 블록은 그대로 노출하지 않음	디버깅이 중요하면 Messages API 쪽도 같이 검토
서브에이전트 여러 개에서 메모리 급증	역할이 넓고 도구 범위가 과해서 병렬 작업이 비대해짐	에이전트 수 줄이고 read-only 역할부터 분리

특히 서브에이전트는 “똑똑한 팀”처럼 상상하면 거의 망해요. 블랙박스 함수처럼 좁은 입출력만 주는 쪽이 훨씬 안정적이에요. 역할이 겹치지 않게 쪼개고, 도구도 최소 범위만 주는 게 좋아요. 이 감은 Claude Code 서브에이전트 만들기 실전 가이드: 자동 위임·비용 절감 세팅까지 읽을 때도 그대로 이어져요.

thinking 미노출은 claude agent sdk 버그인가요

thinking 미노출도 자주 걸려요. 2026-04-18 기준 GitHub 이슈 #25는 아직 Open 상태라, reasoning을 그대로 보고 싶다면 아직은 SDK만으로 끝나지 않을 수 있어요. 디버깅 가시성이 중요하면 Messages API 직접 호출이나 별도 로깅을 같이 두는 편이 안전해요.

claude managed agents랑 언제 갈라야 할까

여기서 결정만 잘해도 시행착오가 크게 줄어요. 둘 다 에이전트를 만든다는 점은 같지만, 책임지는 범위가 달라요.

그럼 지금 뭐부터 써야 할까요?

짧게 가르면 이래요. 내 코드 안에서 루프를 붙이고 싶으면 Agent SDK, 실행 인프라와 세션 유지까지 맡기고 싶으면 Managed Agents예요. Managed Agents는 Console에서 시각적으로 먼저 실험하고 같은 구성을 API로 옮길 수도 있어서, 백엔드 팀이 빠르게 프로토타입을 돌릴 때 꽤 편해요.

항목	Claude Agent SDK	Claude Managed Agents
런타임 위치	내 로컬, 내 서버, 내 CI 파이프라인	Anthropic 관리 인프라
세션 상태	내가 재개와 저장을 챙김	세션과 이벤트가 서버 쪽에 유지됨
잘 맞는 일	로컬 repo 작업, CI 훅, 커스텀 앱	장기 실행, 비동기 작업, 클라우드 워크로드
도구 구성	Claude Code 도구 + MCP + 내 앱 로직	관리형 도구 세트 + MCP + 환경 정의
요금	기본 토큰 과금만 봄	기본 토큰 과금 + 활성 런타임 $0.08/세션-시간 + 웹 검색 $10/1K 쿼리
시작 표면	코드부터 시작	Console에서 먼저 실험 가능

솔로 운영자라면 보통 Agent SDK부터 잡는 게 나아요. 왜냐면 제어가 내 손에 있고, 기존 파이프라인에 얹기 쉽거든요. 반대로 몇 시간짜리 리서치 세션, 상태 유지가 필요한 비동기 작업, 클라우드 컨테이너와 네트워크 규칙까지 한 덩어리로 보고 싶다면 Managed Agents가 더 자연스러워요.

큰 설계 관점이 더 필요하면 AI 에이전트 만들기: 도구 호출부터 워크플로우까지 실전 가이드를 이어서 보세요. Agent SDK와 Managed Agents를 “루프를 내가 쥐느냐, 런타임까지 위임하느냐”로 보면 훨씬 덜 헷갈려요.

자주 묻는 질문

Q1. Claude Code SDK랑 Claude Agent SDK, 뭐가 달라요?

A: 같은 제품 계열이에요. 2025년 9월부터 Claude Code SDK가 Claude Agent SDK로 이름이 바뀌었고, 지금은 Python 패키지 claude-agent-sdk와 TypeScript 패키지 @anthropic-ai/claude-agent-sdk를 기준으로 문서가 정리돼 있어요.

Q2. Claude Max 구독 토큰으로 Agent SDK를 내 제품에 붙여도 되나요?

A: 공식 문서 기준으로는 안 돼요. 서드파티 제품이나 서비스에선 claude.ai 로그인이나 구독 한도를 가져다 쓰지 말고 API 키 인증을 쓰라고 안내해요. 로컬 실험과 제품 배포는 같은 얘기가 아니거든요.

Q3. `maxThinkingTokens`나 thinking 설정을 넣었는데 reasoning이 왜 안 보여요?

A: 2026-04-18 기준 TypeScript SDK 이슈 #25가 Open 상태예요. 지금은 tool 실행 결과는 보이지만 thinking 블록은 SDK 레벨에서 그대로 노출되지 않는 흐름이라, reasoning 디버깅이 핵심이면 Messages API도 같이 봐야 해요.

Q4. Agent SDK와 Managed Agents 중 뭘 먼저 써야 하나요?

A: 내 서버나 CI 파이프라인에 붙일 거면 Agent SDK부터 가세요. 세션 유지, 클라우드 런타임, 장기 비동기 실행까지 묶어서 맡기고 싶으면 Managed Agents가 더 맞아요.

Q5. 서브에이전트 여러 개 돌리면 메모리가 터진다던데 어떻게 줄이나요?

A: 에이전트 수부터 줄이고, 각 역할을 read-only 조사나 테스트처럼 좁게 나누세요. 공유 writable 작업을 여러 개 겹치면 금방 무거워져요. 처음엔 에이전트를 팀보다 함수처럼 취급하는 쪽이 덜 꼬여요.

다음 단계

지금 바로 해볼 거면 Python 예제를 그대로 복붙해서 읽기 전용 도구만 열고 한 번 돌려보세요. 서브에이전트 설계까지 이어갈 생각이면 Claude Code 서브에이전트 만들기 실전 가이드: 자동 위임·비용 절감 세팅까지로 바로 넘어가면 돼요.

Claude Agent SDK 사용법: 커스텀 에이전트 빌드 실전 가이드

claude agent sdk 한 줄 요약

Claude Agent SDK가 Claude Code SDK였다는 점부터 짚고 갈게요

왜 claude agent sdk 이름만 바꿨는데 이렇게 헷갈리나요

네 가지 진입점 중 내 상황에 맞는 건 뭘까

claude agent sdk 설치와 첫 쿼리, 여기서 막히면 계속 꼬여요

claude agent sdk 권한 세팅, tools와 allowed_tools를 헷갈리면 손해예요

세션 재개와 비용 상한, 프로덕션에 넣으려면 여기까지

설치하고 나서 다들 한 번씩 밟는 함정 5가지

Claude Agent SDK에서 왜 node를 spawn하는 거죠

thinking 미노출은 claude agent sdk 버그인가요

claude managed agents랑 언제 갈라야 할까

자주 묻는 질문

Q1. Claude Code SDK랑 Claude Agent SDK, 뭐가 달라요?

Q2. Claude Max 구독 토큰으로 Agent SDK를 내 제품에 붙여도 되나요?

Q3. `maxThinkingTokens`나 thinking 설정을 넣었는데 reasoning이 왜 안 보여요?

Q4. Agent SDK와 Managed Agents 중 뭘 먼저 써야 하나요?

Q5. 서브에이전트 여러 개 돌리면 메모리가 터진다던데 어떻게 줄이나요?

다음 단계

NotebookLM 블로그 활용: 인터뷰 녹취를 초안으로 바꾸는 3단계

Claude Code Agent Teams: 1M 컨텍스트로 병렬 리팩터링 돌리기

자체 호스팅 n8n + AI 스택 월 10만원 미만으로 돌리기

Perplexity Spaces 리서치: 전용 브레인 15분 세팅법

AI 이메일 자동화: Gmail + GPT 답장 템플릿 5종

AI 컨텍스트 엔지니어링: Notion·Claude·Cursor 분담법

답글 남기기 응답 취소

claude agent sdk 한 줄 요약

Claude Agent SDK가 Claude Code SDK였다는 점부터 짚고 갈게요

왜 claude agent sdk 이름만 바꿨는데 이렇게 헷갈리나요

네 가지 진입점 중 내 상황에 맞는 건 뭘까

claude agent sdk 설치와 첫 쿼리, 여기서 막히면 계속 꼬여요

claude agent sdk 권한 세팅, tools와 allowed_tools를 헷갈리면 손해예요

세션 재개와 비용 상한, 프로덕션에 넣으려면 여기까지

설치하고 나서 다들 한 번씩 밟는 함정 5가지

Claude Agent SDK에서 왜 node를 spawn하는 거죠

thinking 미노출은 claude agent sdk 버그인가요

claude managed agents랑 언제 갈라야 할까

자주 묻는 질문

Q1. Claude Code SDK랑 Claude Agent SDK, 뭐가 달라요?

Q2. Claude Max 구독 토큰으로 Agent SDK를 내 제품에 붙여도 되나요?

Q3. maxThinkingTokens나 thinking 설정을 넣었는데 reasoning이 왜 안 보여요?

Q4. Agent SDK와 Managed Agents 중 뭘 먼저 써야 하나요?

Q5. 서브에이전트 여러 개 돌리면 메모리가 터진다던데 어떻게 줄이나요?

다음 단계

Similar Posts

답글 남기기 응답 취소

Q3. `maxThinkingTokens`나 thinking 설정을 넣었는데 reasoning이 왜 안 보여요?