Claude Managed Agents API Python SDK — Claude Managed Agents API Python SDK 완전 가이드 — 에이전트 생성부터 스트리밍까지 7단계

Claude Managed Agents API Python SDK 완전 가이드 — 에이전트 생성부터 스트리밍까지 7단계

2026.04.29 · 26분 읽기

목차

API 하나로 자율 에이전트를 만들고, 컨테이너 환경에서 코드까지 실행시킬 수 있다면? Anthropic의 Managed Agents는 에이전트 생성부터 세션 실행, 결과 스트리밍까지 하나의 API 체계로 구성된다. 공식 문서는 영어로만 제공되며, 여기서는 Python SDK 코드를 중심으로 각 단계의 동작 방식을 다룬다.

Claude Managed Agents API의 4가지 핵심 개념

Claude Managed Agents는 Agent, Environment, Session, Events라는 4가지 개념으로 구성된다. 각 개념이 REST 엔드포인트와 1:1로 대응되기 때문에, 이 구조를 먼저 파악해야 SDK 코드가 읽힌다.

개념역할대응 엔드포인트
Agent모델·시스템 프롬프트·도구 정의POST /v1/agents
Environment컨테이너 템플릿 (네트워크·파일시스템)POST /v1/environments
SessionAgent + Environment의 실행 인스턴스POST /v1/sessions
Events사용자↔에이전트 메시지 교환POST /v1/sessions/{id}/events

Agent는 “무엇을 할 수 있는가”를, Environment는 “어디서 실행되는가”를 정의하는 셈이다. Session은 이 둘을 결합한 실행 단위이고, Events는 세션 안에서 오가는 메시지 스트림에 해당한다.

모든 엔드포인트는 managed-agents-2026-04-01 베타 헤더가 필요하다. 다만 Python SDK를 쓰면 client.beta.agents 네임스페이스가 이 헤더를 자동으로 설정하므로 직접 넣을 일은 없다. Managed Agents 아키텍처 개요에서 각 개념의 상세 스펙을 확인할 수 있다.

내장 도구 목록
Managed Agents가 지원하는 내장 도구는 Bash 실행, 파일 읽기/쓰기, 웹 검색/패치, MCP 서버 연결이다. 별도 구현 없이 tools 배열에 타입만 지정하면 활성화되는 방식이다.
## Python SDK 설치와 에이전트 생성

SDK 설정

Anthropic Python SDK는 pip install anthropic으로 설치한다. ANTHROPIC_API_KEY 환경변수가 설정되어 있으면 Anthropic() 클라이언트가 자동으로 키를 읽는다. 별도 버전 지정 없이 최신 SDK를 쓰면 Managed Agents 베타 엔드포인트에 접근 가능하다.

에이전트 생성 코드

에이전트 생성은 POST /v1/agents에 name, model, system, tools 필드를 전달하는 구조다. SDK에서는 client.beta.agents.create()로 호출한다.

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding assistant. Write clean, well-documented code.",
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
)

print(f"Agent ID: {agent.id}, version: {agent.version}")

tools 배열에 {"type": "agent_toolset_20260401"}을 지정하면 bash 실행, 파일 연산, 웹 검색 등 전체 내장 도구가 한꺼번에 활성화된다. 개별 도구를 하나씩 등록할 필요가 없다는 점이 핵심이다.

반환값에서 agent.id는 이후 세션 생성 시 참조하는 식별자이고, agent.version은 에이전트 설정이 변경될 때마다 증가하는 값이다.

모델 선택 기준
`model` 필드에는 Claude 모델명을 지정한다. 코드 생성 중심이면 `claude-opus-4-7`이, 빠른 응답이 필요하면 경량 모델이 적합하다. 모델별 토큰 요금이 다르므로 용도에 맞게 선택하는 것이 비용 관리의 출발점이 된다.
### system 프롬프트 설계 포인트

system 필드는 에이전트의 행동 범위를 결정하는 핵심 파라미터다. “You are a helpful assistant” 수준의 범용 지시보다는, 구체적인 역할과 제약을 명시하는 편이 결과 품질이 높다. 예를 들어 코드 리뷰 에이전트라면 “Review Python code for type safety and PEP 8 compliance. Do not modify business logic.” 같은 형태가 효과적이다.

에이전트는 한 번 생성하면 재사용이 가능하다. 매번 새로 만들 필요 없이, 동일한 agent ID로 여러 세션을 열 수 있는 구조인 것이다.

Environment 생성과 네트워크 설정

Environment는 에이전트가 코드를 실행하는 컨테이너 환경의 템플릿이다. POST /v1/environments로 생성하며, 네트워킹 정책을 unrestricted 또는 제한된 설정으로 지정할 수 있다.

environment = client.beta.environments.create(
    name="dev-sandbox",
    networking="unrestricted",
)

print(f"Environment ID: {environment.id}")

networking 값에 따라 에이전트의 외부 접근 범위가 달라진다.

networking 설정외부 API 호출pip install보안 수준
unrestricted가능가능낮음 — 개발/테스트용
제한 설정허용 목록만제한적높음 — 프로덕션 권장

개발 단계에서는 unrestricted로 빠르게 테스트하고, 프로덕션에서는 네트워크 범위를 좁히는 것이 일반적인 패턴이다. 에이전트가 외부 API를 호출하거나 패키지를 설치해야 하는 경우 unrestricted가 필수적이지만, 민감 데이터를 다루는 환경이라면 제한 설정을 사용하는 것이 안전하다.

네트워크 설정 주의
unrestricted 환경에서 에이전트가 외부 서비스에 데이터를 전송할 수 있다. API 키나 인증 정보가 시스템 프롬프트에 포함된 경우 유출 위험이 존재하므로, 민감 정보는 환경변수로 분리하고 제한된 네트워크 설정을 적용하는 것이 권장된다.
Environment도 Agent와 마찬가지로 재사용 가능하다. 하나의 Environment에 여러 세션을 연결해서 동일한 컨테이너 스펙으로 반복 실행하는 구조가 된다.

사전 설치 패키지와 파일 유지

컨테이너 환경은 세션이 시작될 때 초기화된다. 세션이 종료되면 파일시스템 변경 사항은 사라지기 때문에, 매 세션마다 pip install이나 파일 생성이 필요한 경우 에이전트의 system 프롬프트에 초기화 단계를 명시하는 것이 일반적이다.

예를 들어 데이터 분석 에이전트라면 system 프롬프트에 “Start every session by running pip install pandas matplotlib seaborn“을 추가해두면, 에이전트가 작업 시작 전 필요한 패키지를 자동으로 설치하는 흐름이 만들어진다. 컨테이너 간 파일 공유가 필요한 경우, 현재 Managed Agents는 볼륨 마운트 설정을 직접 지원하지 않으며 외부 스토리지(S3, GCS 등)를 통한 우회가 필요하다.

세션 생성과 Claude Managed Agents API 이벤트 스트리밍

세션 생성

세션은 Agent와 Environment를 묶어 실행하는 인스턴스다. POST /v1/sessions에 agent ID와 environment_id를 전달하면 된다.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart session",
)

세션이 생성되면 session.id를 받는다. 이 ID로 메시지를 보내고, 응답 스트림을 열고, 세션 상태를 조회하는 것이 가능하다.

SSE 이벤트 스트리밍

메시지 전송과 응답 수신은 이벤트 기반으로 동작한다. POST /v1/sessions/{id}/events에 user.message 타입 이벤트를 보내고, GET /v1/sessions/{id}/stream으로 SSE(Server-Sent Events) 스트림을 열어 에이전트 응답을 수신하는 방식이다.

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "Create a Python script..."}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "session.status_idle":
                break

스트림에서 수신하는 주요 이벤트 타입은 세 가지다.

  • agent.message — 에이전트의 텍스트 응답. event.content 안에 텍스트 블록이 담겨 온다.
  • agent.tool_use — 에이전트가 도구(bash, 파일, 웹 검색 등)를 호출한 기록. 어떤 도구를 어떤 인자로 실행했는지 확인 가능하다.
  • session.status_idle — 에이전트가 모든 작업을 마치고 대기 상태로 전환됨을 의미한다. 이 이벤트를 받으면 스트림을 닫아도 되는 것이다.

Python의 match 구문(3.10+)으로 이벤트 타입을 분기하는 패턴이 Managed Agents 퀵스타트 가이드에서도 동일하게 사용된다. with 블록 안에서 stream과 send를 함께 처리하는 구조가 핵심인데, 스트림을 먼저 열고 메시지를 보내야 응답 이벤트를 놓치지 않는다.

멀티턴 대화 처리

하나의 세션에서 여러 번 메시지를 주고받는 것도 가능하다. session.status_idle을 수신한 뒤 다시 events.send()를 호출하면 같은 세션 컨텍스트 안에서 대화가 이어지는 셈이다. 세션이 유지되는 동안 에이전트는 이전 대화 내용과 파일시스템 상태를 기억한다.

멀티턴 구조는 단계별 작업 분해에 특히 효과적이다. 첫 메시지로 코드 파일을 생성하게 하고, 두 번째 메시지로 테스트를 작성하게 하고, 세 번째 메시지로 리팩토링을 요청하는 식이다. 각 단계가 이전 단계의 파일시스템 상태를 공유하기 때문에, 에이전트가 자신이 만든 파일을 다음 단계에서 바로 참조하는 것이 가능하다.

Claude Managed Agents API 사용법 — 과금 구조 정리

비용 구조를 모르고 에이전트를 돌리면 예상치 못한 청구가 발생할 수 있다. Managed Agents의 과금은 크게 세 가지 축으로 나뉜다.

세션 런타임 요금

세션 런타임은 $0.08/session-hour로 과금된다. running 상태인 시간만 밀리초 단위로 측정하며, idle·rescheduling·terminated 상태는 과금 대상이 아니다. 에이전트가 작업을 마치고 idle로 전환되면 런타임 과금이 멈추는 구조이므로, session.status_idle 이벤트를 감지해서 불필요한 세션을 정리하는 것이 비용 최적화의 기본이 된다.

토큰 요금

토큰은 표준 모델 요금이 그대로 적용된다. Claude Opus 4.7 기준으로 입력 $5/MTok, 출력 $25/MTok이다. 에이전트가 도구를 여러 번 호출하면 각 호출마다 토큰이 소모되므로, 복잡한 작업일수록 토큰 비용이 급증하기도 한다.

추가 과금 항목

웹 검색 도구는 1,000회당 $10가 별도로 부과된다. 에이전트가 자율적으로 웹 검색을 반복 실행할 수 있으므로, system 프롬프트에서 검색 횟수를 제한하거나 검색이 불필요한 작업에는 웹 검색 도구를 비활성화하는 것이 비용 관리에 유리하다.

과금 항목단가비고
세션 런타임$0.08/session-hourrunning 상태만 과금
토큰 (Opus 4.7)입력 $5/MTok, 출력 $25/MTok도구 호출마다 토큰 소모
웹 검색$10/1,000회에이전트 자율 검색 주의
Batch API 할인 미적용
Managed Agents에는 Batch API 할인, Fast mode, Data residency 배수가 적용되지 않는다. 대량 처리 시 Messages API의 Batch 모드와 비용을 비교해볼 필요가 있다.
### 비용 예측과 사전 모니터링

실제 운영 전에 예상 비용을 계산해두면 예산 초과를 방지할 수 있다. 코딩 작업 에이전트를 하루 4시간 실행하고, 세션당 입력 80K 토큰·출력 10K 토큰, 웹 검색 30회를 소비하는 시나리오를 예로 들면 일일 비용은 다음과 같다.

항목계산식일 비용
세션 런타임$0.08 × 4h$0.32
입력 토큰 (Opus 4.7)$5 × 0.08MTok$0.40
출력 토큰 (Opus 4.7)$25 × 0.01MTok$0.25
웹 검색$10 × 30/1,000$0.30
합계$1.27

Anthropic 콘솔의 Usage 탭에서 조직별 API 소비 현황을 확인할 수 있다. 현재는 자동 예산 알림 기능이 제공되지 않으므로, 별도 모니터링 스크립트로 일일 사용량을 집계하는 방식을 직접 구현해야 하는 상황이다.

레이트 리밋과 운영 시 고려사항

엔드포인트별 레이트 리밋

Managed Agents의 레이트 리밋은 조직(organization) 단위로 적용된다.

  • 생성 엔드포인트 (agents, sessions, environments 등) — 분당 60요청
  • 읽기 엔드포인트 (retrieve, list, stream 등) — 분당 600요청

생성 엔드포인트가 분당 60요청이라는 점은 대량 에이전트를 동시에 프로비저닝하는 시나리오에서 병목이 될 수 있다. 에이전트와 환경은 재사용 가능하므로, 매 요청마다 새로 생성하지 않고 기존 리소스를 캐싱하는 패턴이 필수적이다.

읽기 엔드포인트는 분당 600요청으로 여유가 있는 편이지만, SSE 스트림을 여러 세션에서 동시에 열면 빠르게 소진될 때가 있다. 동시 세션 수를 제한하거나, 스트림 연결을 풀링하는 구조가 운영 안정성을 높이는 방법이다.

Research Preview 기능

outcomes, multiagent, memory 기능은 현재 research preview 단계로, 별도 접근 신청이 필요하다. 공식 문서에도 상세 스펙이 공개되어 있지 않다. 멀티에이전트 오케스트레이션이나 세션 간 메모리 공유가 필요한 경우, 현재로서는 애플리케이션 레벨에서 직접 구현해야 하는 상황이다.

재시도 전략 구현

레이트 리밋(429) 또는 일시적 서버 오류(5xx)가 발생하면, 지수 백오프를 적용한 재시도 래퍼를 미리 만들어두는 것이 안정적이다. 세션 생성 API처럼 분당 60요청 제한이 있는 엔드포인트에서 특히 효과적인 패턴이다.

import time
import anthropic

def create_session_with_retry(client, agent_id, env_id, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.beta.sessions.create(
                agent=agent_id,
                environment_id=env_id,
            )
        except anthropic.RateLimitError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # 1s → 2s → 4s
        except anthropic.APIStatusError as e:
            if e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

anthropic.RateLimitError는 429 응답 시 SDK가 자동으로 발생시키는 예외다. APIStatusError.status_code로 5xx와 4xx를 구분하면, 5xx는 재시도하고 4xx는 즉시 실패 처리하는 분기가 명확해진다. 동일한 패턴을 events.send() 호출에도 적용해두면 스트리밍 단계의 간헐적 오류에도 대응할 수 있다.

전체 흐름 통합 — 에이전트 생성에서 결과 수집까지

각 단계를 순서대로 연결하면 Claude Managed Agents API의 전체 흐름이 된다.

Agent 생성 ──→ Environment 생성 ──→ Session 생성
                                        │
                                        ▼
                              Events.send (user.message)
                                        │
                                        ▼
                              Events.stream (SSE)
                                        │
                           ┌────────────┼────────────┐
                           ▼            ▼            ▼
                    agent.message  agent.tool_use  session.status_idle
                    (텍스트 응답)   (도구 실행 로그)  (작업 완료 → 종료)

결과 수집 패턴

스트림에서 받은 이벤트를 저장하는 기본 패턴은 리스트에 누적하는 방식이다.

results = []

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "List all Python files"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    results.append(block.text)
            case "agent.tool_use":
                results.append(f"[tool] {event}")
            case "session.status_idle":
                break

full_response = "".join(results)

agent.tool_use 이벤트도 함께 수집하면 에이전트가 어떤 도구를 어떤 순서로 실행했는지 추적할 수 있다. 디버깅이나 감사(audit) 로그용으로 유용한 패턴이다.

에러 상황 대응

프로덕션 환경에서의 에러 핸들링·재시도 패턴은 공식 문서에 명시되어 있지 않다. 현재로서는 SDK가 던지는 예외를 try/except로 잡고, HTTP 상태 코드에 따라 재시도 여부를 판단하는 방식을 직접 구현해야 한다. 429(Rate Limit) 응답 시 지수 백오프를 적용하고, 5xx 응답 시 세션 상태를 조회한 뒤 재개하는 것이 일반적인 접근이 될 것이다.

세션 상태 확인은 client.beta.sessions.retrieve(session_id)로 가능하다. 반환되는 session.status 값이 running이면 스트림을 다시 열어 이어서 처리할 수 있고, terminated이면 새 세션을 생성해야 한다. 스트림 재연결 시 이미 수신한 이벤트가 중복으로 들어오지 않으므로, 클라이언트 측 중복 필터링은 별도로 필요하지 않다.

세션 재사용으로 비용 절감
단발성 질문마다 새 세션을 여는 대신, 하나의 세션에서 멀티턴으로 처리하면 세션 생성 오버헤드와 컨텍스트 재구축 토큰을 줄일 수 있다. 세션이 idle 상태일 때는 런타임 과금이 멈추므로, 세션을 열어두고 필요할 때 메시지를 보내는 패턴도 비용 면에서 효율적인 편이다.
## Claude Managed Agents API 사용법 — 실전 체크리스트와 다음 단계

코드 작성 시 빠뜨리기 쉬운 점검 항목은 다섯 가지다.

배포 전 점검 항목

  • API 키 관리 — ANTHROPIC_API_KEY를 코드에 하드코딩하지 않는다. 환경변수 또는 시크릿 매니저를 사용하는 것이 기본이다.
  • 모델 선택 — 작업 복잡도에 맞는 모델을 지정한다. 단순 텍스트 처리에 Opus를 쓰면 토큰 비용이 불필요하게 높아지는 경우가 있다.
  • 네트워크 정책 — 개발 환경은 unrestricted, 프로덕션은 제한 설정으로 분리한다.
  • 세션 정리 — session.status_idle 수신 후 스트림을 닫고, 불필요한 세션은 명시적으로 종료한다.
  • 레이트 리밋 대비 — 에이전트·환경은 재사용하고, 생성 API 호출을 최소화한다. 분당 60요청 제한에 걸리면 전체 파이프라인이 멈추기 때문이다.

한국어 문서 부재

현재 Claude Managed Agents의 공식 가이드는 전체가 영어로만 제공된다. 한국어 레퍼런스가 없으므로, SDK 코드의 타입 힌트와 docstring을 직접 확인하는 것이 가장 정확한 참조 경로가 된다.

MCP 서버 연동

Managed Agents의 tools 배열에는 MCP 서버도 연결할 수 있다. 다만 MCP 서버 연동의 상세 설정 예제는 공식 문서에 충분히 다뤄지지 않은 상태다. 에이전트에 외부 데이터베이스 조회나 사내 API 호출 기능을 붙이려면 MCP 서버 구현이 다음 단계가 된다. 그리고 멀티에이전트 오케스트레이션이 필요한 경우, 현재 research preview인 multiagent 기능의 정식 출시를 지켜보거나 애플리케이션 레벨에서 여러 세션을 조율하는 방식을 검토해볼 만하다. Anthropic SDK 에이전트 예제를 기반으로 Claude Managed Agents API 사용법을 확장해 나가면, 자율 에이전트 파이프라인의 기초가 갖춰지는 셈이다.

관련 글

이 글 공유하기