Claude Managed Agents 구축 — Claude Managed Agents 구축 7단계 — SDK 설치·MCP·비용 최적화 완전 가이드

Claude Managed Agents 구축 7단계 — SDK 설치·MCP·비용 최적화 완전 가이드

2026.05.02 · 19분 읽기

목차

API 호출 한 번으로 끝나는 작업이라면 에이전트가 필요 없다. 문제는 여러 단계를 거쳐야 하는 작업이다. 파일을 읽고, 외부 API를 호출하고, 결과를 종합해서 코드를 생성하는 워크플로우는 단순 프롬프트 체인으로 제어하기 어렵다. Claude Managed Agents 구축 가이드를 찾는 개발자 대부분이 이 지점에서 출발하는 셈이다. 이 글에서는 SDK 설치부터 멀티에이전트 패턴, 과금 구조, 프로덕션 배포 체크리스트까지 단계별로 정리한다.

Claude Managed Agents가 필요한 시점

대규모 조직에서는 내부 플랫폼 팀이 에이전트 인프라를 직접 구축하는 경우가 많다. 컨테이너 오케스트레이션, 세션 관리, 장애 복구까지 자체 구현하면 초기 비용이 크지만 통제력이 높은 구조다. 반면 소규모 팀에서는 이런 인프라를 처음부터 만들 여유가 없다. Claude Managed Agents는 세션 런타임, 도구 실행 환경, 샌드박싱을 Anthropic이 관리하므로 에이전트 로직 자체에 집중할 수 있게 해준다.

에이전트 도입이 실질적으로 의미 있는 상황은 다음과 같다.

  • 멀티스텝 워크플로우: 하나의 요청이 파일 읽기 → 분석 → 코드 생성 → 테스트 실행처럼 여러 도구를 순차 호출해야 할 때
  • 병렬 처리: 동일한 작업을 여러 하위 에이전트에 분산시켜 처리 시간을 줄여야 할 때
  • 상태 유지: 대화 맥락을 세션 단위로 유지하면서 중간 결과를 누적해야 할 때
Managed Agents vs 직접 구축
Managed Agents는 세션 런타임 과금 모델을 사용하므로 별도 컨테이너 시간 비용이 추가 청구되지 않는다. 자체 에이전트 인프라를 운영할 때 발생하는 컨테이너 관리 비용과 비교하면 소규모 팀에서 초기 비용 부담이 낮은 편이다.
단순 질의응답이나 한 번의 API 호출로 끝나는 작업에는 에이전트가 과하다. 에이전트 세션은 토큰 비용 외에 런타임 과금이 별도로 붙기 때문에, 단순 작업에 에이전트를 투입하면 비용만 늘어나는 결과를 낳게 된다.

Claude Agent SDK 설치와 기본 구조

Claude Agent SDK(Python)는 pip install claude-agent-sdk로 설치하며 Python 3.10 이상이 필요하다. Claude Agent SDK Python 저장소에서 최신 버전과 변경 이력을 확인할 수 있다.

SDK의 핵심 API는 두 가지로 구성된다.

구성 요소역할비고
ClaudeSDKClient에이전트 세션 생성·관리async context manager로 사용
query()비동기 쿼리 실행에이전트에 작업 전달
ClaudeAgentOptions에이전트 동작 설정system_prompt, max_turns 등

기본 사용 패턴은 아래와 같다.

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a helpful assistant",
    max_turns=5,
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode='acceptEdits'
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Tell me a joke")
    async for msg in client.receive_response():
        print(msg)

async with 블록 안에서 세션이 자동으로 생성되고, 블록을 벗어나면 세션이 종료된다. receive_response()는 async iterator로 스트리밍 응답을 반환하므로, 긴 작업에서도 중간 결과를 실시간으로 확인할 수 있는 구조다.

ClaudeCodeOptions 이름 변경
기존에 사용되던 `ClaudeCodeOptions`는 `ClaudeAgentOptions`로 이름이 변경되었다. 기존 코드에서 `ClaudeCodeOptions`를 import하고 있다면 `ClaudeAgentOptions`로 교체해야 한다.
## ClaudeAgentOptions 설정 항목 상세

ClaudeAgentOptions는 에이전트의 동작 범위와 권한을 제어하는 핵심 설정 객체다. Claude Managed Agents 구축 가이드에서 가장 많이 조정하게 되는 부분이기도 하다.

system_prompt와 max_turns

system_prompt는 에이전트의 역할과 행동 지침을 정의한다. 프로덕션 환경에서는 단순한 역할 설명보다 구체적인 제약 조건을 명시하는 것이 안정적이다. max_turns는 에이전트가 도구를 호출할 수 있는 최대 횟수를 제한하는데, 무한 루프 방지와 비용 통제 두 가지 목적을 동시에 달성하는 설정이다.

allowed_tools와 permission_mode

allowed_tools로 에이전트가 사용할 수 있는 도구 목록을 화이트리스트 방식으로 지정한다. 반대로 disallowed_tools를 사용하면 블랙리스트 방식으로 특정 도구만 차단할 수도 있다. permission_mode는 에이전트가 파일 수정 같은 민감한 작업을 수행할 때의 권한 수준을 결정한다.

mcp_servers와 hooks

mcp_servers는 에이전트에 연결할 MCP 서버 목록을 지정하며, hooks는 에이전트 실행 중 특정 시점(예: PreToolUse)에 개입할 수 있는 콜백 시스템이다. 이 두 설정은 다음 섹션에서 코드와 함께 상세히 다룬다.

대규모 조직에서는 allowed_tools를 팀별 정책으로 중앙 관리하는 경우가 흔하다. 소규모 팀에서는 에이전트 용도별로 옵션 프리셋을 만들어 두면 관리가 수월해진다. 예를 들어 코드 리뷰 에이전트는 Read 도구만, 코드 생성 에이전트는 Read와 Write를 허용하는 식이다.

인프로세스 MCP 서버로 커스텀 도구 구축

SDK는 @tool 데코레이터와 create_sdk_mcp_server를 사용하여 인프로세스 MCP 서버를 만들 수 있다. 외부 MCP 서버와 비교했을 때 몇 가지 구조적 이점이 있다.

비교 항목외부 MCP 서버인프로세스 MCP 서버
프로세스 관리서브프로세스 별도 관리 필요불필요
IPC 오버헤드있음 (stdout/stdin 또는 HTTP)없음
배포 단위서버 바이너리 + 에이전트 코드단일 프로세스
타입 안전성스키마 별도 정의Python 타입 힌트 활용

아래는 커스텀 도구를 정의하고 MCP 서버로 묶는 코드 예제다.

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

server = create_sdk_mcp_server(
    name="my-tools", version="1.0.0", tools=[greet_user]
)

@tool 데코레이터의 첫 번째 인자는 도구 이름, 두 번째는 설명, 세 번째는 파라미터 스키마다. 반환값은 MCP 프로토콜의 content 배열 형식을 따른다.

Hooks 시스템으로 에이전트 동작 가로채기

Hooks 시스템은 PreToolUse 등의 시점에서 에이전트 동작을 가로채고 제어할 수 있다. 예를 들어 특정 도구 호출 전에 입력값을 검증하거나, 호출 자체를 차단하는 로직을 삽입하는 것이 가능하다. 이 방식은 프로덕션 환경에서 에이전트의 예측 불가능한 행동을 방지하는 안전장치 역할을 하게 된다.

인프로세스 vs 외부 MCP 서버 선택 기준
도구 로직이 에이전트와 같은 언어(Python)로 작성되고, 외부 프로세스 의존성이 없다면 인프로세스 MCP 서버가 유리하다. 반면 도구가 다른 언어로 작성되었거나 독립적인 생명주기가 필요하면 외부 MCP 서버를 사용하는 것이 적절한 선택이다.
## 멀티에이전트 오케스트레이션 패턴

단일 에이전트로 처리하기 어려운 복잡한 작업은 여러 에이전트를 조합해서 해결한다. claude-agent-sdk-demos 저장소에는 8개 데모가 포함되어 있으며, 그중 Research Agent 데모가 멀티에이전트 패턴의 대표적 구현 사례다.

Research Agent 패턴

Research Agent 데모는 다음 워크플로우를 구현한다.

연구 요청
  ↓
하위 주제로 분해
  ↓
병렬 researcher 에이전트 스폰
  ↓
각 에이전트가 독립적으로 조사
  ↓
결과 종합

이 패턴의 핵심은 오케스트레이터 에이전트가 작업을 분해하고, 하위 에이전트들이 병렬로 실행된 뒤 결과를 모아서 최종 응답을 생성하는 구조다. 대규모 조직에서 흔히 쓰는 MapReduce 패턴과 개념적으로 유사한 접근이다.

Session API (V2)

Hello World V2 데모는 unstable_v2_* Session API를 사용하여 send()와 stream()을 분리하고, 멀티턴 대화와 세션 영속성을 지원한다. 아직 unstable 프리픽스가 붙어 있으므로 프로덕션 적용 시에는 API 변경 가능성을 감안해야 하는 상황이다.

멀티에이전트 구성에서 주의할 점은 각 하위 에이전트가 독립적인 세션을 소비한다는 것이다. 병렬 에이전트 수가 늘어나면 세션 런타임 비용도 비례해서 증가하므로, 병렬도와 비용 사이의 트레이드오프를 설계 단계에서 고려할 필요가 있다.

Claude Managed Agents 과금 구조와 비용 최적화

Claude Managed Agents 구축 가이드에서 빠뜨릴 수 없는 부분이 과금 구조다. Anthropic 가격 정책 페이지에 따르면, Managed Agents는 토큰과 세션 런타임 두 가지 차원으로 과금된다.

과금 모델 상세

세션 런타임은 $0.08/session-hour이며, running 상태 동안만 밀리초 단위로 과금된다. idle, rescheduling, terminated 상태에서는 과금되지 않는다. 이 구조 덕분에 에이전트가 외부 API 응답을 기다리는 동안 idle 상태로 전환되면 런타임 비용이 절감되는 셈이다.

아래는 Opus 4.7 모델 기준 1시간 세션의 비용 산출 예시다.

# Worked example: 1hr Opus 4.7 session
# Input: 50,000 tokens × $5/MTok = $0.25
# Output: 15,000 tokens × $25/MTok = $0.375
# Session runtime: 1.0hr × $0.08 = $0.08
# Total = $0.705

여기서 주의할 점이 몇 가지 있다. Batch API 할인, Fast mode 프리미엄, Data residency 멀티플라이어, 서드파티 플랫폼 가격은 Managed Agents 세션에 적용되지 않는다. 웹 검색 기능을 사용하면 1,000건당 $10 표준 요금이 별도로 부과되기도 한다.

프롬프트 캐싱으로 비용 절감

프롬프트 캐싱 멀티플라이어는 Managed Agents 세션에도 동일하게 적용된다. 캐싱을 활용하면 반복되는 시스템 프롬프트나 컨텍스트의 입력 토큰 비용을 크게 줄일 수 있다.

# Cache-optimized example: same 1hr session
# Uncached input: 10,000 × $5/MTok = $0.05
# Cache reads: 40,000 × $5 × 0.1/MTok = $0.02
# Output: 15,000 × $25/MTok = $0.375
# Runtime: 1.0hr × $0.08 = $0.08
# Total = $0.525

캐싱 적용 전 $0.705에서 캐싱 적용 후 $0.525로, 약 25% 비용이 절감된다. 시스템 프롬프트가 길고 반복 호출이 잦은 에이전트일수록 캐싱 효과가 커진다.

비용 최적화 체크리스트
시스템 프롬프트를 캐싱 가능한 구조로 설계하고, max_turns를 작업 복잡도에 맞게 제한하며, 병렬 에이전트 수를 필요 최소한으로 유지하는 것이 비용 통제의 기본 원칙이다.
## 프로덕션 배포 전 체크리스트

Claude Managed Agents를 프로덕션에 배포하기 전에 아래 항목을 점검해야 한다. 대규모 조직에서는 이런 체크리스트가 플랫폼 팀 차원에서 관리되지만, 소규모 팀에서는 에이전트를 만든 개발자가 직접 확인해야 하는 영역이다.

SDK 및 환경 설정

  • Python 3.10 이상 환경인지 확인
  • pip install claude-agent-sdk 최신 버전 설치 여부
  • ClaudeCodeOptions가 아닌 ClaudeAgentOptions를 사용하고 있는지 확인 (이름 변경 반영)
  • API 키가 환경 변수로 관리되는지 (하드코딩 금지)

에이전트 동작 제어

  • max_turns 설정으로 무한 루프 방지
  • allowed_tools 또는 disallowed_tools로 도구 접근 범위 제한
  • permission_mode 설정이 운영 환경에 맞는지 검토
  • system_prompt에 명확한 제약 조건 명시

비용 관리

  • 세션당 예상 토큰 사용량 산출
  • 세션 런타임($0.08/session-hour) 포함한 총 비용 추정
  • 프롬프트 캐싱 적용 가능 여부 확인
  • 웹 검색 사용 시 추가 비용(1,000건당 $10) 고려
  • 병렬 에이전트 수에 따른 비용 시뮬레이션

모니터링 및 에러 처리

  • 세션 상태(running, idle, rescheduling, terminated) 전환 로깅
  • 도구 호출 실패 시 재시도 정책 설정
  • 비정상 종료 시 세션 정리 로직 구현
  • async with 블록이 정상적으로 세션을 종료하는지 확인
공식 문서 확인 필수 항목
Managed Agents 세션 생성·컨테이너 구성 등 REST API 엔드포인트 상세와 보안 샌드박싱·권한 설정·오류 복구 등 운영 가이드는 공식 문서에 명시되어 있지 않다(2026-04 기준). 프로덕션 배포 전 최신 공식 문서를 반드시 재확인해야 한다. 한국어 공식 문서도 현재 존재하지 않으며 영문 문서만 제공된다.
## 운영 시 주의사항과 확장 방향

비용 폭주 방지

멀티에이전트 패턴에서 하위 에이전트가 예상보다 오래 실행되면 세션 런타임 비용이 급증할 수 있다. max_turns를 보수적으로 설정하고, 세션 단위 비용 상한선을 두는 것이 안전하다. Batch API 할인이 Managed Agents에는 적용되지 않으므로, 대량 처리가 필요한 경우 일반 API와 Managed Agents를 혼합 사용하는 방식도 고려할 만하다.

도구 권한 최소화

allowed_tools를 설정하지 않으면 에이전트가 사용 가능한 모든 도구에 접근할 수 있다. 프로덕션 환경에서는 반드시 화이트리스트 방식으로 필요한 도구만 명시적으로 허용해야 한다. 특히 Bash 도구는 시스템 명령어 실행이 가능하므로, 용도가 명확하지 않은 에이전트에는 포함하지 않는 쪽이 안전하다.

Session API 안정성

unstable_v2_* Session API는 멀티턴 대화와 세션 영속성을 지원하지만, unstable 프리픽스가 의미하듯 API 시그니처가 변경될 가능성이 있다. 프로덕션에서 사용한다면 SDK 버전을 고정(pin)하고, 업그레이드 시 API 변경 사항을 확인하는 프로세스가 필요하다.

확장 방향

에이전트 옵션 설정과 MCP 도구 구축이 안정화되었다면, 다음 단계로 Hooks 시스템을 활용한 에이전트 행동 감사(audit) 파이프라인을 구축하는 것이 자연스러운 확장이다. PreToolUse 훅에서 민감 데이터 접근을 로깅하거나, 특정 패턴의 도구 호출을 차단하는 정책 레이어를 추가할 수 있다. Claude 멀티에이전트 오케스트레이션을 본격적으로 확장한다면, 에이전트 간 통신 프로토콜과 결과 집계 전략도 설계 대상에 포함되는데, Research Agent 패턴이 그 출발점으로 적합한 구조다. ClaudeAgentOptions 설정을 팀 단위로 표준화하는 것도 Claude Managed Agents 구축 가이드의 다음 주제가 된다.

관련 글

이 글 공유하기