Claude Managed Agents 사용법 완전 가이드 — Agent·Session·Event 4단계 구축

목차

• Claude Managed Agents의 4가지 핵심 개념
  • Agent — 에이전트 정의
  • Environment — 실행 환경
  • Session — 실행 인스턴스
  • Events — 메시지 교환
• Claude Managed Agents 사용법 — 퀵스타트 4단계
  • 1단계: Agent 생성
  • 2단계: Environment 생성
  • 3단계: Session 시작
• Agent 생성 시 API 구조와 설정 옵션
  • 속도 제한
• SSE 스트리밍으로 Claude Managed Agents 이벤트 처리
  • 수신 이벤트 타입 전체 정리
  • 커스텀 도구 결과 반환
• 빌트인 도구와 MCP 서버 연동
  • MCP 서버 연동 구조
• 베타 제약 사항과 현재 한계
  • research preview 기능
  • 현재 문서화되지 않은 영역
  • 세션 수명주기와 비용 관리 전략
• Claude Managed Agents 사용법 정리와 실전 적용 전략

AI 에이전트를 만들려면 오케스트레이션 프레임워크를 직접 짜야 한다는 통념이 있다. LangChain이든 CrewAI든, 에이전트 루프를 코드로 구성하고 도구 호출 로직을 구현하며 컨테이너 런타임을 관리하는 것이 당연한 수순이라는 인식이다. 하지만 Claude Managed Agents 사용법을 살펴보면 이 전제가 달라진다. Anthropic이 제공하는 이 관리형 에이전트 인프라는 루프·도구 실행·런타임 전체를 API 뒤에 숨기고, 개발자는 Agent 정의와 세션 관리만 신경 쓰면 되는 구조를 취한다.

이 글에서는 Managed Agents의 4가지 핵심 개념부터 Python SDK를 이용한 에이전트 생성, SSE 스트리밍 이벤트 처리, MCP 서버 연동까지 단계별로 다룬다. 2026-04 기준 베타 상태이며, 모든 API 계정에서 기본적으로 접근이 가능하다.

Claude Managed Agents의 4가지 핵심 개념

Claude Managed Agents 사용법을 이해하려면 먼저 4개의 핵심 리소스를 구분해야 한다. 이 구조를 파악하지 못하면 API 호출 순서와 리소스 간 관계에서 혼란이 생기기 쉽다.

Agent — 에이전트 정의

Agent는 모델, 시스템 프롬프트, 도구, MCP 서버, 스킬을 하나로 묶은 설정 단위다. 어떤 모델을 쓸지, 어떤 도구를 활성화할지, 시스템 프롬프트를 뭘로 잡을지를 정의하는 것이 Agent 리소스의 역할이다. 실행 환경이나 대화 상태는 여기에 포함되지 않는다.

Environment — 실행 환경

Environment는 에이전트가 실행될 컨테이너 템플릿을 정의한다. 네트워킹 정책, 클라우드 설정 등 인프라 수준의 구성이 여기에 해당하는 셈이다. Agent와 분리되어 있으므로 동일한 Agent를 서로 다른 Environment에서 실행하는 것이 가능하다.

Session — 실행 인스턴스

Session은 실행 중인 에이전트 인스턴스에 해당한다. Agent와 Environment를 조합해서 Session을 시작하면, 그 시점부터 에이전트가 메시지를 주고받을 수 있는 상태가 되는 것이다. 하나의 Agent로 여러 Session을 동시에 띄울 수도 있다.

Events — 메시지 교환

Events는 애플리케이션과 에이전트 간 메시지를 주고받는 통로다. 사용자 메시지 전송, 에이전트 응답 수신, 커스텀 도구 호출 결과 반환 등이 모두 Events를 통해 이루어진다.

리소스	역할	비유
Agent	모델·도구·프롬프트 설정	Docker 이미지 정의
Environment	컨테이너 템플릿	Docker Compose 설정
Session	실행 중인 인스턴스	실행 중인 컨테이너
Events	메시지 교환 채널	stdin/stdout 스트림

이 4가지가 Managed Agents의 전체 아키텍처를 구성한다. Managed Agents 아키텍처 개요에서 각 리소스 간 관계를 시각적으로 확인할 수 있다.

## Claude Managed Agents 사용법 — 퀵스타트 4단계

실제 에이전트를 띄우는 과정은 4단계로 구성된다. Agent 생성 → Environment 생성 → Session 시작 → 이벤트 전송·스트리밍 순서를 따르면 된다. 모든 엔드포인트에 anthropic-beta: managed-agents-2026-04-01 베타 헤더가 필요하지만, Python SDK를 사용하면 이 헤더가 자동으로 설정된다.

1단계: Agent 생성

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"},
    ],
)

agent_toolset_20260401 도구 타입을 지정하면 bash, 파일 조작, 웹 검색 등 전체 빌트인 도구가 한꺼번에 활성화된다. 도구를 개별적으로 등록할 필요가 없는 것이 이 타입의 특징이다.

2단계: Environment 생성

environment = client.beta.environments.create(
    name="quickstart-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

networking 설정에서 unrestricted는 외부 네트워크 접근을 허용한다는 의미다. 프로덕션 환경에서는 이 값을 제한하는 것이 일반적이겠지만, 공식 문서에 네트워킹 정책 상세 옵션은 아직 명시되어 있지 않다.

3단계: Session 시작

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

Agent ID와 Environment ID를 조합해서 Session을 만든다. 이 시점부터 에이전트가 메시지를 수신할 준비가 된 상태다.

## Agent 생성 시 API 구조와 설정 옵션

Managed Agents API는 Agents, Sessions, Events, Resources, Environments, Vaults, Credentials, Files, Skills 총 9개 리소스 그룹으로 구성된다. 이 중 Agent 생성 시 가장 자주 다루는 설정 옵션을 정리한다.

Agent 생성의 요청 본문 구조는 다음과 같다.

{
  "name": "string (required, 1-256 chars)",
  "model": "claude-opus-4-7",
  "system": "string (optional, up to 100,000 chars)",
  "tools": [
    { "type": "agent_toolset_20260401" }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ]
}

model은 필수 필드이며, system은 최대 100,000자까지 설정 가능하다. tools는 최대 50개, skills는 최대 64개, mcp_servers는 최대 20개까지 지정할 수 있다. 숫자 제한을 초과하면 API가 에러를 반환하므로 복잡한 에이전트를 구성할 때 이 상한선을 인지해둘 필요가 있다.

필드	필수 여부	상한	용도
name	필수	256자	에이전트 식별 이름
model	필수	—	사용할 Claude 모델
system	선택	100,000자	시스템 프롬프트
tools	선택	50개	빌트인/커스텀 도구
skills	선택	64개	재사용 가능한 스킬
mcp_servers	선택	20개	외부 MCP 서버 연결

속도 제한

Create 엔드포인트는 분당 60회, 읽기 엔드포인트는 분당 600회로 속도 제한이 걸려 있다. 에이전트를 동적으로 생성하는 패턴 — 예를 들어 사용자 요청마다 새 Agent를 만드는 방식 — 은 이 제한에 금방 도달할 수 있다. Agent를 미리 생성해두고 Session만 새로 띄우는 편이 속도 제한 관점에서 유리하다.

## SSE 스트리밍으로 Claude Managed Agents 이벤트 처리

Session을 생성한 뒤 실제로 에이전트와 대화하려면 이벤트 스트리밍을 설정해야 한다. Python SDK에서 SSE 스트리밍은 stream-first 패턴을 따른다. 스트림을 먼저 열고, 그 안에서 메시지를 전송하는 순서인 것이다.

with client.beta.sessions.stream(
    session_id=session.id,
) as stream:
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}],
    )
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "agent.custom_tool_use":
            print(f"\nCustom tool call: {event.tool_name}")

이 코드에서 주목할 부분이 몇 가지 있다.

첫째, client.beta.sessions.stream()으로 스트림을 먼저 연다. HTTP 연결이 열린 상태에서 메시지를 전송하고 응답을 실시간으로 수신하는 구조다.

둘째, events.send()로 사용자 메시지를 보낸다. 이벤트 타입은 user.message이고, content 배열에 텍스트 블록을 담아 전송하면 된다.

셋째, 수신 이벤트 타입에 따라 분기 처리가 필요하다. agent.message는 에이전트의 텍스트 응답, agent.custom_tool_use는 커스텀 도구 호출 요청에 해당한다. 그 외에 session.status_idle과 session.status_terminated 이벤트도 존재하며, 세션 상태 변화를 추적하는 데 활용하게 된다.

수신 이벤트 타입 전체 정리

스트림에서 수신되는 이벤트 타입은 역할별로 구분된다. 처리 로직을 짤 때 각 타입이 어느 시점에 발생하는지 파악해두면 분기 처리 누락을 방지할 수 있다.

이벤트 타입	발생 시점	처리 주체
agent.message	에이전트 텍스트 응답 완료	애플리케이션
agent.custom_tool_use	커스텀 도구 호출 요청	애플리케이션 (실행 후 결과 반환)
session.status_idle	에이전트가 입력 대기 상태 진입	상태 감시 / 세션 종료 트리거
session.status_terminated	세션 종료 완료	리소스 정리

session.status_idle은 에이전트가 도구 실행을 마치고 다음 사용자 입력을 기다리는 상태다. 이 이벤트를 기준으로 후속 메시지를 보내거나 세션을 닫는 타이밍을 결정할 수 있다.

커스텀 도구 결과 반환

에이전트가 커스텀 도구를 호출하면, 애플리케이션 측에서 해당 도구를 실행한 뒤 결과를 돌려줘야 한다. 이때 user.custom_tool_result 이벤트 타입으로 custom_tool_use_id를 포함하여 반환하는 방식이다. 빌트인 도구(bash, 파일 조작 등)는 Managed Agents 인프라가 직접 실행하므로 이 과정이 필요 없지만, 외부 API 호출 같은 커스텀 도구는 애플리케이션이 처리하고 결과를 다시 스트림에 주입해야 한다.

이 패턴은 일종의 협력적 실행 모델이다. 에이전트가 “이 도구를 실행해달라”고 요청하면 애플리케이션이 실행하고 결과를 돌려주는 핑퐁 구조가 되는 셈이다. Python SDK의 Managed Agents 스트리밍 가이드에서 커스텀 도구 처리 전체 흐름을 확인할 수 있다.

빌트인 도구와 MCP 서버 연동

Managed Agents가 기본 제공하는 빌트인 도구는 크게 4가지 카테고리로 나뉜다.

• Bash: 셸 명령 실행. 패키지 설치, 스크립트 실행, 시스템 명령 등
• File operations: 파일 읽기, 쓰기, 편집, glob 패턴 검색, grep 검색
• Web search and fetch: 웹 검색 및 페이지 내용 가져오기
• MCP servers: 외부 MCP 서버와의 연결

agent_toolset_20260401 타입 하나를 지정하면 위 도구가 전부 활성화된다. 개별 도구를 선택적으로 비활성화하는 방법은 공식 문서에 명시되어 있지 않다.

MCP 서버 연동 구조

MCP(Model Context Protocol) 서버는 Agent 생성 시 mcp_servers 배열에 추가한다. 앞서 API 구조 섹션에서 본 것처럼 type, name, url 3개 필드로 구성되며, 최대 20개까지 연결할 수 있다. 에이전트가 실행 중에 MCP 서버의 도구를 자동으로 탐색하고 호출하는 방식이기 때문에, 연결만 설정해두면 별도의 도구 등록 없이 MCP 서버가 제공하는 기능을 사용할 수 있게 된다.

[Application]
    ↓ events.send(user.message)
[Session / Managed Agents Runtime]
    ↓ 도구 호출 판단
    ├─ 빌트인 도구 → 런타임이 직접 실행
    ├─ MCP 서버 도구 → MCP 프로토콜로 호출
    └─ 커스텀 도구 → agent.custom_tool_use 이벤트로 앱에 위임

빌트인 도구와 MCP 도구는 런타임이 자체 처리하므로 애플리케이션 코드에 추가 구현이 필요 없다. 커스텀 도구만 앞 섹션에서 설명한 이벤트 기반 핑퐁 패턴으로 처리하면 되는 것이다.

## 베타 제약 사항과 현재 한계

Claude Managed Agents는 2026-04 기준 베타 단계다. 기본 기능인 Agent·Environment·Session·Events는 모든 API 계정에서 사용 가능하지만, 확장 기능 일부는 접근이 제한되어 있다.

research preview 기능

outcomes(결과 정의), multiagent(멀티에이전트), memory(메모리) 기능은 research preview 상태로, 별도 액세스 요청이 필요하다. 공식 문서에도 이들 기능에 대한 상세 설명은 아직 제공되지 않은 상태다.

현재 문서화되지 않은 영역

프로덕션 배포 시 비용 최적화 — 세션 시간 관리, 토큰 절약 전략 — 에 대한 가이드가 공식 문서에 명시되어 있지 않다. 에러 핸들링과 재시도 패턴에 대한 실전 예제 역시 부족한 상태다. 또한 한국어 공식 문서는 존재하지 않으며, 모든 공식 가이드가 영문으로만 제공된다.

기능	상태	접근 방법
Agent/Environment/Session/Events	베타 (기본 제공)	모든 API 계정
outcomes (결과 정의)	research preview	별도 액세스 요청
multiagent (멀티에이전트)	research preview	별도 액세스 요청
memory (메모리)	research preview	별도 액세스 요청

세션 수명주기와 비용 관리 전략

현재 공식 문서에 명시된 세션 과금 구조는 없지만, 실무적으로 고려할 패턴은 정리할 수 있다. Session은 생성 이후 session.status_terminated 이벤트를 수신할 때까지 살아있는 상태로 유지된다. 대화가 끝났음에도 세션을 명시적으로 종료하지 않으면 유휴 세션이 누적될 수 있다.

권장 패턴은 세 가지다. 첫째, 대화 종료 시점에 세션 종료 API를 명시적으로 호출한다. 둘째, session.status_idle 이벤트 수신 후 일정 시간 내 후속 메시지가 없으면 세션을 닫는 타임아웃 로직을 추가한다. 셋째, 동일 사용자의 연속 대화라면 새 Session을 생성하는 대신 기존 Session을 재활용해 컨텍스트를 유지한다. 단, 세션 재활용 시 이전 대화 컨텍스트가 토큰을 소비한다는 점을 감안해야 한다.

## Claude Managed Agents 사용법 정리와 실전 적용 전략

Managed Agents 도입 시 고려할 실전 포인트는 세 가지다.

첫째, Agent는 재사용하고 Session만 새로 생성하는 패턴이 기본이다. Agent 생성 API의 분당 60회 제한을 고려하면, 에이전트 설정을 미리 정의해두고 대화마다 Session을 새로 여는 것이 합리적인 접근이다.

둘째, 빌트인 도구만으로도 상당한 범위의 자동화가 가능하다. Bash, 파일 조작, 웹 검색이 기본 제공되므로, 코드 생성·실행·검증 루프를 에이전트 런타임 안에서 완결할 수 있기도 하다. 외부 시스템과의 연동이 필요할 때만 MCP 서버나 커스텀 도구를 추가하면 된다.

셋째, SSE 스트리밍의 stream-first 패턴을 이해하는 것이 핵심이다. 스트림을 먼저 열고 메시지를 보내는 순서가 직관적이지 않을 수 있지만, 이 패턴 덕분에 연결 수립과 동시에 응답을 실시간으로 수신할 수 있는 것이다.

실전 도입 체크리스트:

1. Agent 설계    → model, system, tools 정의
2. Environment   → 네트워킹 정책 결정
3. Session 관리  → 생성·종료 주기 설계
4. 이벤트 처리   → stream-first + 커스텀 도구 핸들러
5. 모니터링      → session.status_idle / terminated 감시

Claude Managed Agents API가 안정화되면 다음 단계로 살펴볼 만한 영역이 있다. research preview 상태인 multiagent 기능은 여러 에이전트가 협력하는 워크플로를 가능하게 할 전망이며, memory 기능은 세션 간 컨텍스트 유지를 지원할 것으로 보인다. 그리고 MCP 서버 생태계가 확장되면서 Claude MCP 서버 연동을 통한 외부 시스템 통합 범위도 넓어질 것이다. Managed Agents 퀵스타트 가이드를 기준점으로 삼고, API 버전 변경을 추적하면서 프로덕션 적용 시점을 판단하는 것이 현실적인 Claude Managed Agents 사용법 도입 전략이다.

관련 글

• Claude Code 웹 버전 사용법 — 브라우저 AI 코딩 시작하는 7단계 – Claude Code 웹 버전은 로컬 설정 없이 브라우저에서 AI 코딩 에이전트를 실행한다. GitHub 연동, 클라우드 환경 설정, 병렬…
• Claude Code 자동화 시스템 구축 7단계: 스킬·훅·배치 실전 아키텍처 – Claude Code로 반복 업무를 자동화하는 시스템을 만든다. 커스텀 스킬, 훅, 배치 처리, MCP 서버 연동까지 실전에서 쓰는 구조를…
• GPT-5 Codex CLI 사용법 7단계 — Rust 설치·config.toml·모델 선택 완전 정복 – GPT-5 Codex는 기존 TypeScript CLI에서 Rust 구현으로 전환되었다. 설치, config.toml 설정, 샌드박스 정책…