Claude Managed Agents로 에이전트 세션 상태와 오류 복구를 Anthropic에 위임하는 법 — /v1/agents·/v1/sessions 직접 구현과 호스팅 인프라의 경계

마이크로서비스 중간에 AI를 붙이려 하면 금방 실감하게 되는 게 있습니다. 모델 API 호출 자체보다 그 주변 코드—세션이 중간에 끊기면 어떻게 복구할지, 도구 실행이 실패하면 retry를 어떻게 구현할지, 샌드박스 환경은 어디서 돌릴지—가 훨씬 더 복잡하다는 사실이요. 저도 처음 에이전트 루프를 직접 짜면서 체크포인트 로직 버그 때문에 사흘을 통째로 날린 적이 있어요. 비즈니스 로직은 다 짰는데 에이전트 인프라 때문에 릴리즈가 밀리는 상황, 한 번쯤 겪어보셨을 겁니다.

Anthropic이 2026년 4월 공개 베타로 출시한 Claude Managed Agents는 이 인프라 부담을 통째로 위임할 수 있는 구조를 제안합니다. POST /v1/agents로 에이전트를 정의하고, POST /v1/sessions로 장기 실행 세션을 시작하면—세션 상태 관리, 오류 복구 자동화, 샌드박스 운영을 Anthropic 인프라가 가져갑니다. 이 글에서는 그 위임 원리가 실제로 어떻게 동작하는지, 그리고 어디까지 넘기고 어디서부터는 직접 들고 가야 하는지를 코드와 함께 살펴봅니다.

단순히 "편리한 래퍼 API"가 아니라 아키텍처 결정에 가까운 이야기입니다. 잘못 선택하면 나중에 벤더 종속이나 데이터 주권 문제로 돌아올 수 있거든요. 장단점을 솔직하게 짚어볼게요.

핵심 개념

에이전트 루프를 직접 구현할 때 실제로 어떤 일이 생기나

에이전트를 자체 구현한다면 이런 흐름이 됩니다.

개발자 코드
  → 모델 API 호출
  → 응답에서 tool_use 파싱
  → 도구 실행
  → 실패 시 retry 로직 (backoff, 재시도 횟수, 예외 분기)
  → 상태를 DB나 Redis에 저장
  → 다음 루프 반복

이걸 견고하게 만들려면 체크포인트, 분산 락, 컨테이너 크래시 대응, 타임아웃 처리까지 구현해야 해요. 솔직히 비즈니스 로직보다 이 인프라 부분이 더 복잡해지는 경우가 많습니다. Managed Agents는 이 루프 전체를 Anthropic 쪽으로 옮깁니다.

개발자 코드
  → POST /v1/sessions (task 이벤트 전송)
  → 결과 스트림 수신
         ↕
  Anthropic 인프라 (에이전트 루프 + 오류 복구 + 상태 관리)

뇌-손 분리(Brain-Hands Split): 무엇을 넘기고 무엇을 가져올 수 있나

Anthropic 엔지니어링 블로그에서 공개한 이 시스템의 핵심 설계 원칙입니다. 위임 범위를 이해하는 데 가장 중요한 개념이에요.

"손"만 자체 인프라로 이전할 수 있는 것이 Self-Hosted Sandboxes 기능입니다. 모델 추론 로직(뇌)은 Anthropic에 두되, 실제 코드가 실행되는 환경(손)만 사내 서버로 가져올 수 있어요. 금융이나 의료처럼 데이터가 외부로 나가면 안 되는 환경에서 특히 유용한 옵션입니다.

세션 상태 위임이 실제로 동작하는 방식

핵심 원리: 세션 이벤트 로그를 외부 지속 저장소에 분리해, 실행 컨테이너(손)가 무상태(Stateless)로 취급됩니다. 컨테이너가 충돌해도 harness가 다른 컨테이너로 세션 로그를 기반으로 이어받으므로 작업 손실이 없습니다.

개발자 입장에서는 재연결 시 client.beta.sessions.stream()을 다시 호출하면 그 시점까지의 전체 이벤트 로그를 받아볼 수 있습니다. 내부적으로 체크포인트가 어디까지 됐는지 직접 추적할 필요가 없어요.

harness: Anthropic 인프라에서 에이전트 루프를 실제로 실행하고 관리하는 실행 환경 구성 요소. 도구 호출 조율, 오류 전달, 세션 로그 유지를 담당합니다. 네트워크 오류나 컨테이너 크래시가 발생하면 harness가 자동으로 다른 컨테이너로 이어받아 세션을 재개합니다.

오류 복구가 위임되는 방식

도구 실행이 실패하면 harness가 그 실패를 캐치해서 Claude에게 tool call 응답으로 전달합니다. Claude는 오류 문맥을 바탕으로 재시도 여부와 대안을 스스로 판단합니다. 개발자가 별도로 retry 로직, backoff 전략, 상태 체크포인트를 구현하지 않아도 됩니다.

실전 적용

예시 1: 장기 실행 백그라운드 작업

수십 분~수 시간이 걸리는 데이터 분석 작업을 사용자 연결 없이 백그라운드로 돌리는 패턴입니다. Anthropic 공식 사례로 언급된 방식이에요.

import anthropic
 
client = anthropic.Anthropic()
 
# 1단계: 에이전트 정의 (한 번만. 재사용 가능, 버전 관리됨)
agent = client.beta.agents.create(
    model="claude-opus-4-5",
    name="data-analyst",
    system="You are a data analysis agent. When given sales data, produce a structured report.",
    tools=[
        {"type": "computer_use_20250124"},
        {"type": "bash_20250124"},
    ],
    betas=["managed-agents-2026-04-01"],
)
 
# 2단계: 세션 시작 — 이후 상태 관리는 Anthropic이 담당
session = client.beta.sessions.create(
    agent_id=agent.id,
    betas=["managed-agents-2026-04-01"],
)
 
# 3단계: 작업 전송
client.beta.sessions.send_event(
    session_id=session.id,
    event={"type": "user", "content": "Analyze Q1 sales data and produce a summary report."},
)
 
# 4단계: 스트리밍 결과 수신
# 네트워크 오류로 연결이 끊겨도 harness가 세션을 유지합니다
# 재연결 시 이 호출만 다시 하면 전체 이벤트 로그가 복원됩니다
for chunk in client.beta.sessions.stream(session_id=session.id):
    print(chunk)

모든 요청에 betas=["managed-agents-2026-04-01"]가 필요합니다. 이걸 빠뜨리면 일반 Messages API로 라우팅되어서 진짜 황당한 에러가 납니다—에러 메시지도 안 맞아서 원인 찾는 데 한참 걸려요.

예시 2: 엔터프라이즈 내부망 연동 (Self-Hosted Sandboxes)

이 패턴은 데이터 외부 반출 규제가 있는 금융·의료 환경을 전제합니다. 일반적인 웹 서비스 개발이라면 예시 1 패턴만으로도 충분합니다.

실행 환경(손)만 사내로 가져오고, 추론 로직(뇌)은 Anthropic에 유지하는 구조입니다.

[Anthropic 인프라]
  Claude 추론 + 에이전트 루프 + 세션 상태 관리
          ↕
    MCP 프록시 (암호화 터널)
          ↕
[고객 인프라]
  샌드박스 컨테이너 / 내부 DB / 파일 시스템
  자격 증명은 Vault에 저장 — Claude 생성 코드에는 절대 노출 안 됨

MCP Tunnels: 고객 인프라 쪽에서 아웃바운드 연결만 열면 됩니다. 즉, 방화벽 인바운드 규칙을 변경하지 않아도 에이전트가 내부망 MCP 서버와 통신할 수 있습니다. end-to-end 암호화를 지원하며 현재 리서치 프리뷰 상태입니다.

Self-Hosted Sandboxes를 활성화하려면 에이전트 생성 시 실행 환경을 자체 인프라로 지정합니다.

# Self-Hosted Sandbox 연결 설정 예시
agent = client.beta.agents.create(
    model="claude-opus-4-5",
    name="internal-analyst",
    system="You are a data analysis agent with access to internal systems.",
    tools=[{"type": "bash_20250124"}],
    sandbox={
        "type": "self_hosted",
        "endpoint": "https://your-mcp-proxy.internal/v1",  # 사내 MCP 프록시 엔드포인트
        "auth": {"type": "bearer", "token_env": "MCP_TOKEN"},
    },
    betas=["managed-agents-2026-04-01"],
)

이 구조에서 자격 증명은 MCP 프록시를 통해서만 접근되고, Claude가 생성하는 코드에는 절대 노출되지 않는다는 점이 보안 측면에서 핵심입니다.

예시 3: 사용자 대면 실시간 응답과 백그라운드 작업 분리

실무에서 가장 흔히 쓰이는 하이브리드 패턴입니다. 레이턴시에 민감한 사용자 대면 인터랙션과 무거운 비동기 작업을 다른 경로로 처리하는 방식이에요.

# 사용자 대면 실시간 응답 — raw Messages API 사용
# 빠른 응답 속도가 중요한 채팅 인터페이스: 세션 초기화 오버헤드가 없습니다
def handle_user_chat(user_message: str):
    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": user_message}],
    )
    return response.content
 
# 장기 비동기 작업 — Managed Agents로 오프로드
# 보고서 생성, 데이터 파이프라인, 코드 생성 등
def dispatch_background_task(task_description: str, agent_id: str) -> str:
    session = client.beta.sessions.create(
        agent_id=agent_id,
        betas=["managed-agents-2026-04-01"],
    )
    client.beta.sessions.send_event(
        session_id=session.id,
        event={"type": "user", "content": task_description},
    )
    # session.id를 저장해두고 나중에 아래처럼 결과를 조회합니다
    # client.beta.sessions.stream(session_id=session_id)
    return session.id
 
# 실제 사용 흐름:
#   1. 사용자 채팅 → handle_user_chat() → 즉시 응답
#   2. "보고서 생성해줘" → dispatch_background_task() → session_id 반환
#   3. 완료 시 웹훅 또는 폴링으로 결과 수신 → 사용자에게 알림

두 함수가 한 프로덕트 안에서 공존할 때 핵심은 어느 경로가 사용자를 기다리게 하느냐입니다. 즉각 응답이 필요한 건 Messages API, 기다려도 되는 무거운 작업은 Managed Agents—이 기준만 기억하면 됩니다.

장단점 분석

장점

단점 및 주의사항

옵저버빌리티(Observability): 시스템 내부 상태를 외부에서 측정·추적할 수 있는 정도. 에이전트 맥락에서는 세션별 토큰 사용량, 도구 호출 횟수, 오류율 등을 모니터링하는 것을 말합니다.

실무에서 가장 흔한 실수

저도 팀에서 실제로 목격한 것들이에요.

1. 레이턴시가 중요한 사용자 대면 응답에 Managed Agents를 적용하는 경우. 세션 초기화 오버헤드가 있어 실시간 채팅에는 적합하지 않습니다. 사용자 대면은 raw Messages API나 Agent SDK, 백그라운드 작업만 Managed Agents로 분리하는 하이브리드 구조를 고려해보시면 좋습니다.

2. betas 헤더를 빠뜨리는 경우. betas=["managed-agents-2026-04-01"] 없이 요청하면 일반 Messages API로 라우팅되어서 이상한 에러가 납니다. 에러 메시지도 안 맞아서 원인 찾는 데 시간을 낭비하게 되거든요.

3. 세션 비용 상한 없이 장기 작업을 그냥 돌리는 경우. 세션 실행 시간 요금이 있는 구조에서 세션이 예상보다 길어지면 비용이 빠르게 쌓입니다. 작업 단위로 세션을 명시적으로 종료하거나 타임아웃을 설정해두는 게 좋습니다.

마치며

Managed Agents는 "에이전트 인프라를 직접 유지할 역량과 시간이 없는 팀"에게 실질적인 대안이 될 수 있지만, Claude 종속과 데이터 주권 제한이라는 트레이드오프를 명확히 이해하고 선택하는 것이 중요합니다.

선택 기준은 비교적 명확합니다. 수분~수 시간짜리 백그라운드 작업이고, 인프라 유지보수보다 기능 개발에 시간을 쓰고 싶고, 도구가 이미 공개 인터넷이나 MCP 서버에 올라가 있다면 Managed Agents가 좋은 선택입니다. 반대로 여러 LLM을 조합해야 하거나, 완전 온프레미스가 필요하거나, 레이턴시에 민감한 실시간 응답이라면 자체 에이전트 루프가 맞습니다.

조금 더 큰 그림에서 보면, Managed Agents 같은 서비스는 "에이전트 인프라를 점점 클라우드에 위임하는" 업계 흐름의 일부입니다. 마치 서버 운영에서 서버리스로 넘어갔듯이요. 지금 선택이 2년 뒤 기술 부채에 어떻게 영향을 미칠지—특히 벤더 종속 측면에서—미리 고민해두면 나중에 전환 비용이 훨씬 줄어듭니다.

지금 바로 시작해볼 수 있는 3단계:

1. Anthropic API 키를 발급받고 pip install anthropic 또는 npm install @anthropic-ai/sdk로 SDK를 설치한 뒤, Managed Agents 공식 문서에서 베타 접근을 신청해볼 수 있습니다. 베타 기간에는 문서 URL이나 기능 구성이 변경될 수 있으므로, 공식 채널에서 최신 안내를 확인하는 것이 좋습니다.

2. 위 예시 1의 코드를 그대로 복사해서 간단한 분석 작업을 하나 돌려보시면 세션이 어떻게 생성되고 이벤트 로그가 어떤 구조로 오는지 직접 확인할 수 있습니다. 아직 에이전트를 만들어본 적이 없다면 이 단계가 가장 빠른 입문 경로입니다.

3. 현재 팀에서 직접 구현 중인 에이전트 루프가 있다면, 세션 상태 저장·오류 복구에 소비되는 코드 규모를 측정해보시면 좋습니다. 그 규모가 비즈니스 로직보다 크다면 Managed Agents 전환을 검토해볼 좋은 시점입니다. 아직 시작하지 않은 프로젝트라면, 처음부터 Managed Agents로 프로토타입을 만들어보고 제약이 느껴지는 시점에 자체 구현으로 전환하는 방식도 좋습니다.

참고 자료

• Claude Managed Agents overview | Claude API Docs
• Start a session | Claude API Docs
• Self-hosted sandboxes | Claude API Docs
• Scaling Managed Agents: Decoupling the brain from the hands | Anthropic Engineering
• New in Claude Managed Agents: self-hosted sandboxes and MCP tunnels | Claude Blog
• Claude Managed Agents: get to production 10x faster | Claude Blog
• Anthropic Introduces Managed Agents to Simplify AI Agent Deployment | InfoQ
• Anthropic's Claude Managed Agents gives enterprises a new one-stop shop but raises vendor 'lock-in' risk | VentureBeat
• Claude Managed Agents vs Claude Agent SDK | WaveSpeed Blog
• Deep Dive: How Anthropic's Claude Managed Agents Solve the AI Scaffolding Nightmare | Medium
• Anthropic Agent Lock-In: 9 Critical Enterprise Risks | Progressive Robot
• GitHub - anthropics/claude-agent-sdk-python