Claude Managed Agents Python SDK 배포 — Claude Managed Agents 배포 가이드 3단계 — Python SDK 핵심 개념 완전 정리

Claude Managed Agents 배포 가이드 3단계 — Python SDK 핵심 개념 완전 정리

2026.05.07 · 21분 읽기

목차

PR 리뷰 자동화, 스케줄 기반 리포트 생성, 이벤트 트리거 분석은 Claude Managed Agents가 처리하기 적합한 반복 작업 유형이다. Anthropic이 베타로 공개한 Managed Agents는 컨테이너 기반 에이전트를 API 한 줄로 띄우는 구조로, environments.create() → agents.create() → sessions.create() 3단계 API 호출로 배포가 완료된다.

Managed Agents 아키텍처 개요 기준으로 핵심 개념 4가지(Agent, Environment, Session, Events)를 정리하고, Python SDK 기반 3단계 배포 흐름을 코드 예제와 함께 다룬다.

Claude Managed Agents를 구성하는 4가지 핵심 개념

Claude Managed Agents는 Agent, Environment, Session, Events 네 가지 개념으로 구성된다. 각각의 역할이 명확히 분리되어 있어, 하나씩 이해하면 전체 배포 흐름이 자연스럽게 보이는 구조다.

Agent — 모델과 도구의 조합

Agent는 어떤 모델을 쓸지, 어떤 시스템 프롬프트를 줄지, 어떤 도구·MCP 서버·스킬을 연결할지 정의하는 단위다. 쉽게 말하면 “무엇을 할 수 있는 에이전트인가”를 선언하는 설정 객체인 셈이다. 한 번 생성하면 여러 세션에서 재사용할 수 있으므로, 에이전트 정의와 실행을 분리하는 것이 핵심 설계 원칙이 된다.

Environment — 컨테이너 템플릿

Environment는 에이전트가 실행될 컨테이너의 템플릿을 정의한다. 패키지 설치, 네트워크 접근 범위 같은 인프라 설정이 여기에 포함된다. 데이터 파이프라인 관점에서 보면, pandas나 dbt-core 같은 의존성을 Environment 레벨에서 지정해두면 세션마다 매번 설치할 필요가 없게 된다.

Session — 실행 인스턴스

Session은 Agent + Environment 조합의 실제 실행 인스턴스다. 세션을 생성하면 컨테이너가 뜨고, 그 안에서 에이전트가 동작하기 시작한다. 리소스(GitHub 리포지토리, 파일 등)와 Vault 자격증명은 세션 생성 시점에 주입하는 방식이다.

Events — 앱과 에이전트 간 메시지

Events는 애플리케이션과 에이전트 사이의 양방향 메시지 채널이다. SSE(Server-Sent Events) 스트림으로 연결하고, 메시지를 보내고 받는 구조다. session.status_idle, session.status_terminated 같은 상태 이벤트로 세션 생명주기를 제어하게 된다.

베타 헤더 필수
현재 Managed Agents는 베타 상태이며, 모든 엔드포인트에 `managed-agents-2026-04-01` 베타 헤더가 필요하다. Python SDK를 사용하면 이 헤더가 자동 설정되므로 직접 관리할 필요는 없다.
| 개념 | 역할 | 생명주기 | 비유 | |——|——|———-|——| | Agent | 모델·프롬프트·도구 정의 | 1회 생성, 재사용 | Docker 이미지 정의 | | Environment | 컨테이너 템플릿(패키지·네트워크) | 1회 생성, 재사용 | Dockerfile | | Session | 실행 인스턴스 | 호출마다 생성 | docker run | | Events | 앱↔에이전트 메시지 | 세션 내 스트림 | stdin/stdout |

Claude Managed Agents 배포 가이드: 3단계 흐름 정리

배포는 Phase 1(패턴 선택) → Phase 2(도구·스킬·리소스 구성) → Phase 3(Vault 설정 → 세션 생성 → Event Stream 연결) 순서로 진행된다. Managed Agents 온보딩 가이드에서 전체 흐름을 확인할 수 있다.

Phase 1 — 에이전트 패턴 선택

먼저 에이전트의 실행 패턴을 결정해야 한다. 공식 문서에서 제시하는 패턴은 네 가지다:

  • Event-triggered: 외부 이벤트(웹훅, 큐 메시지)가 들어오면 세션을 생성하는 방식
  • Scheduled: 크론 스케줄에 따라 주기적으로 실행
  • Fire-and-forget PR: PR 생성 후 결과만 확인하는 비동기 패턴
  • Research + dashboard: 데이터를 수집·분석해서 대시보드에 결과를 쌓는 패턴

데이터 파이프라인 자동화에는 Scheduled 패턴이 자연스러운 선택이다. dbt 모델 변경 감지 후 자동 리뷰가 필요하다면 Event-triggered가 적합하기도 하다.

Phase 2 — 도구와 리소스 구성

Agent에 연결할 도구는 세 가지 유형으로 나뉜다:

  • Prebuilt Agent Tools: Anthropic이 제공하는 내장 도구
  • MCP 서버: Model Context Protocol 기반의 외부 도구 서버
  • Custom Tools: 직접 정의한 함수를 도구로 등록

Skills(에이전트의 행동 지침)와 Resources(GitHub 리포지토리, 파일 등)도 이 단계에서 구성한다.

Phase 3 — 실행

Vault에 자격증명을 등록하고, 세션을 생성한 뒤 Event Stream을 연결하면 에이전트가 동작하기 시작한다.

agents.create()와 sessions.create() 분리 필수
에이전트 생성 코드와 세션 실행 코드를 같은 블록에 넣는 것은 안티패턴이다. Agent와 Environment는 1회 생성 후 재사용하고, Session은 호출마다 새로 만들어야 한다. 이 구분을 무시하면 매 실행마다 불필요한 Agent 재생성이 발생해 Rate Limit을 소모하게 된다.
## Environment와 Agent 생성 코드

1회 설정(one-time setup) 단계의 코드를 살펴보자. Environment를 먼저 만들고, 그 ID를 Agent 생성 시 참조하는 구조다.

# ONE-TIME SETUP
env_response = client.beta.managed_agents.environments.create(...)
env_id = env_response.id

agent_response = client.beta.managed_agents.agents.create(
    name="...",
    model="claude-opus-4-7",
    instruction="...",
    tools=[...],
    skills=[...],
    environment_id=env_id
)
agent_id = agent_response.id

environments.create()에서 컨테이너 템플릿을 정의하고, agents.create()에서 모델·프롬프트·도구·스킬을 지정한다. 반환된 env_id와 agent_id는 이후 세션 생성에서 계속 참조되므로 별도로 저장해 두는 것이 좋다.

데이터 파이프라인 용도라면 instruction 필드에 “SQL 쿼리 결과를 분석하고 이상치를 보고하라” 같은 구체적 지침을 넣게 될 것이다. model 파라미터에는 claude-opus-4-7처럼 정확한 모델 식별자를 지정해야 한다.

여기서 주의할 점은 tools 배열의 구성이다. Prebuilt Agent Tools, MCP 서버 참조, Custom Tool 정의가 모두 이 배열에 들어간다. MCP 서버를 연결할 경우 서버 엔드포인트 정보를, Custom Tool을 쓸 경우 함수 스키마를 포함해야 하는 방식이다.

Session 생성과 Event Stream 연결

Agent와 Environment가 준비되었으면, 이제 실행마다 Session을 생성하고 Event Stream으로 통신하는 런타임 코드를 작성할 차례다.

# RUNTIME (every invocation)
session = client.beta.managed_agents.sessions.create(
    agent=agent_id,
    environment_id=env_id,
    resources=[...],
    vault_ids=[...]
)

with client.beta.managed_agents.sessions.events.stream(
    session_id=session.id,
) as stream:
    client.beta.managed_agents.sessions.events.send(
        session_id=session.id,
        message="<first message>"
    )
    for event in stream:
        if event.type == "session.status_terminated":
            break
        if event.type == "session.status_idle":
            if event.stop_reason.type != "requires_action":
                break

sessions.create()에서 resources와 vault_ids를 주입하는 구조가 핵심이다. 같은 Agent 정의를 쓰더라도 세션마다 다른 리포지토리나 자격증명을 연결할 수 있다는 뜻이 된다.

Event Stream 처리 루프에서는 두 가지 종료 조건을 확인한다. session.status_terminated는 에이전트가 완전히 종료된 상태이고, session.status_idle은 에이전트가 대기 상태에 진입한 것이다. stop_reason.type이 requires_action이 아닌 idle이면 작업이 완료된 것으로 판단해 루프를 빠져나오게 된다.

데이터 파이프라인 연동 시 메시지 설계
`message` 파라미터에 JSON 형태로 파이프라인 컨텍스트를 전달하면 에이전트가 구조화된 입력을 받을 수 있다. 예를 들어 `{“task”: “analyze”, “table”: “orders”, “date_range”: “2026-05-01~2026-05-07”}` 같은 형태로 넘기면, 에이전트가 지침(instruction)에 따라 해당 테이블을 분석하는 방식이다.
## Python SDK로 커스텀 도구 등록하기

Claude Managed Agents의 강점 중 하나는 커스텀 도구를 인프로세스 MCP 서버로 등록할 수 있다는 점이다. claude-agent-sdk-python 리포지토리에서 제공하는 SDK를 사용하면 서브프로세스 관리나 IPC 오버헤드 없이 단일 Python 프로세스 안에서 도구를 실행할 수 있다.

SDK 설치와 기본 요구사항

설치는 pip install claude-agent-sdk로 진행하며, Python 3.10 이상이 필요하다. SDK는 두 가지 호출 방식을 제공한다:

  • query() 함수: 단순 비동기 호출. 메시지를 보내고 응답을 받는 일회성 패턴
  • ClaudeSDKClient: 양방향 대화형 세션 지원. 여러 턴에 걸친 상호작용이 필요할 때 사용

@tool 데코레이터와 MCP 서버 등록

@tool 데코레이터로 Python 함수를 도구로 선언하고, create_sdk_mcp_server()로 인프로세스 MCP 서버에 등록하는 흐름이다.

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

@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]
)

options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Greet Alice")
    async for msg in client.receive_response():
        print(msg)

@tool 데코레이터의 세 번째 인자는 파라미터 스키마다. {"name": str} 형태로 타입을 지정하면 SDK가 JSON Schema로 변환해 MCP 프로토콜에 맞춰 노출하는 구조가 된다.

allowed_tools 배열의 네이밍 컨벤션은 mcp__<서버이름>__<도구이름> 형식이다. 위 예제에서 서버 이름이 "tools"이고 도구 이름이 "greet"이므로 mcp__tools__greet이 되는 셈이다. 이 컨벤션을 틀리면 에이전트가 도구를 인식하지 못하므로 주의가 필요하다.

데이터 파이프라인 맥락에서는 @tool로 BigQuery 쿼리 실행기, S3 파일 리더, Slack 알림 발송기를 등록하면 에이전트가 파이프라인 전 구간을 단일 Python 프로세스에서 처리한다. 서브프로세스 없이 단일 프로세스에서 돌아간다는 점은 컨테이너 리소스 관리 측면에서도 유리하다.

GitHub 리포지토리 마운트와 리소스 관리

Claude Managed Agents 배포 가이드에서 빠질 수 없는 부분이 리소스 관리다. 에이전트가 코드를 읽고 수정하려면 GitHub 리포지토리를 세션에 마운트해야 한다.

리포지토리 마운트 설정

세션 생성 시 resources 배열에 다음 형태로 지정한다:

{
  "resources": [{
    "type": "github_repository",
    "url": "https://github.com/org/repo",
    "authorization_token": "<PAT or GitHub App token>",
    "mount_path": "/workspace/<repo-name>",
    "checkout": "<branch or SHA>"
  }]
}

mount_path의 기본 작업 디렉토리는 /workspace이며, 그 하위에 리포지토리 이름으로 마운트된다. checkout 필드에 브랜치명 또는 특정 커밋 SHA를 지정할 수 있어, 데이터 파이프라인의 특정 버전 코드를 에이전트에 제공한다.

파일 리소스 제한

세션당 파일 리소스는 최대 999개까지 지원된다. 대규모 모노레포를 통째로 마운트하면 이 제한에 걸릴 수 있으므로, 필요한 디렉토리만 선별적으로 마운트하는 것이 현실적인 방법이다.

PR 생성 시 추가 구성

중요한 점은 GitHub 리포지토리 마운트가 파일시스템 접근만 제공한다는 것이다. 에이전트가 PR을 생성하려면 GitHub MCP 서버를 별도로 연결하고, Vault에 GitHub 자격증명을 등록해야 한다. 리포지토리 마운트만으로는 읽기·수정은 되지만 GitHub API 호출(PR 생성, 이슈 코멘트 등)은 불가능한 구조인 셈이다.

Vault 자격증명 관리
`authorization_token` 필드에 PAT(Personal Access Token)이나 GitHub App 토큰을 직접 넣을 수 있지만, 프로덕션에서는 Vault에 등록한 뒤 `vault_ids`로 참조하는 방식이 권장된다. 토큰이 코드에 노출되는 위험을 원천적으로 차단하기 위함이다.
| 리소스 유형 | 용도 | 제한 사항 | |————-|——|———–| | github_repository | 코드 읽기·수정 | 파일시스템만, API 호출 불가 | | file | 개별 파일 주입 | 세션당 최대 999개 | | GitHub MCP 서버 | PR 생성·이슈 관리 | Vault 자격증명 별도 필요 |

Rate Limit과 운영 시 고려사항

프로덕션에 Claude Managed Agents를 배포하기 전에 Rate Limit 구조를 파악해 두어야 한다. 제한을 초과하면 429 에러가 반환되고, 파이프라인이 중단되는 상황이 발생할 수 있기 때문이다.

API Rate Limit 구조

Rate Limit은 조직(Organization) 단위로 적용된다. 엔드포인트 유형에 따라 두 가지 티어로 나뉜다:

  • Create 엔드포인트: agents.create, sessions.create, environments.create 등 — 분당 300회
  • Read 엔드포인트: retrieve, list, stream 등 — 분당 600회

모든 API 계정에 기본 활성화되어 있으므로 별도 승인 절차 없이 바로 사용 가능하다.

운영 관점에서의 설계 포인트

Create 300회/분 제한은 넉넉해 보이지만, agents.create()와 sessions.create()를 분리하지 않으면 얘기가 달라진다. 매 호출마다 Agent를 재생성하는 안티패턴을 쓰면, 실제로 세션 생성에 쓸 수 있는 Create 쿼터가 절반으로 줄어드는 것이다.

Event Stream 연결은 Read 엔드포인트에 해당하므로 분당 600회까지 가능하지만, 다수의 동시 세션을 운영할 때는 stream 연결 수를 모니터링해야 한다. 현재 공식 문서에 프로덕션 환경 모니터링·로깅 베스트 프랙티스는 명시되어 있지 않다.

pricing 관련 주의
세션 시간당 비용 외에 토큰 비용 구조의 상세 내역은 공식 문서 페이지에서 확인되지 않는다. 프로덕션 투입 전에 Anthropic 세일즈팀에 직접 확인하는 것이 안전하다.
### 한국어 문서 현황

현재 docs.anthropic.com/ko에 Managed Agents 전용 페이지가 존재하지 않는다. 모든 공식 문서는 영문으로만 제공되므로, 이 글에서 인용한 설정값과 API 시그니처는 영문 원본 기준임을 참고해야 한다.

Claude Managed Agents 배포 후 다음 단계

Environment로 컨테이너 템플릿을 정의하고, Agent로 모델·도구·프롬프트를 선언한 뒤, Session을 생성해서 Event Stream으로 통신하는 3단계 구조다. Agent/Environment 생성(one-time)과 Session 생성(per-invocation)을 코드 레벨에서 명확히 분리하는 것이 Rate Limit 소모를 막는 설계 원칙이며, @tool 데코레이터와 create_sdk_mcp_server()를 활용하면 커스텀 도구를 서브프로세스 없이 단일 프로세스로 운영할 수 있다.

다음으로 살펴볼 영역은 Claude MCP 서버 연동이다. GitHub MCP 서버 외에도 Slack, Jira, 데이터베이스 등 외부 서비스를 MCP 프로토콜로 연결하면 에이전트의 자율 범위가 크게 확장된다. Anthropic Agent API 전체 사용법을 한 번 훑어보면 Managed Agents 이외의 에이전트 패턴(로컬 실행, 하이브리드 등)과의 차이점도 명확해진다. Claude 에이전트 배포 자동화 측면에서는 CI/CD 파이프라인에 세션 생성 스크립트를 통합하는 것이 자연스러운 확장점이 될 수 있다. 현재 multi-agent 및 outcomes 기능은 research preview 단계로 일반 접근이 불가하지만, GA 전환 시 에이전트 간 협업 워크플로우 구성에서 핵심 역할을 하게 된다.

관련 글

이 글 공유하기