Anthropic Claude 관리형 에이전트 공개 베타 출시: 5분 만에 완전 관리형 AI 에이전트 실행하기

2026년 4월 8일, Anthropic은 Claude Platform을 통해 Claude Managed Agents의 퍼블릭 베타를 공식 발표했습니다. 이 새로운 완전 관리형 에이전트 프레임워크(Managed Agent Harness)는 "에이전트 루프 + 도구 실행 + 샌드박스 컨테이너 + 상태 지속성"을 하나의 REST API 세트로 묶어 제공합니다. 이제 개발자는 직접 에이전트 루프나 도구 호출 계층, 런타임을 구축할 필요가 없습니다. /v1/agents, /v1/environments, /v1/sessions라는 세 가지 엔드포인트만 호출하면 Claude가 안전한 샌드박스 환경에서 독립적인 에이전트로서 긴 작업 시간을 필요로 하는 업무를 스스로 수행할 수 있게 됩니다.

이번 공개 테스트에서는 managed-agents-2026-04-01 베타 요청 헤더, 새로운 agent_toolset_20260401 도구 세트, 그리고 Server-Sent Events(SSE) 기반의 이벤트 스트림 프로토콜이 함께 공개되었습니다. 본 글에서는 공식 문서와 최신 릴리스 노트를 바탕으로 Claude Managed Agents의 핵심 개념, API 연동 방식, 이벤트 모델 및 과금 규칙을 체계적으로 정리합니다. 또한 5분 안에 실제 Managed Agent 세션을 실행해 볼 수 있는 Python/curl 예제 코드를 제공해 드립니다.

Claude Managed Agents란 무엇인가: 관리형 에이전트의 핵심 포지셔닝

Managed Agents를 이해하기 전에 기존 Messages API와의 관계를 먼저 정리할 필요가 있습니다. Anthropic은 현재 두 가지 구축 경로를 제공합니다. Messages API는 모델을 직접 호출하는 방식으로, 에이전트 루프를 완전히 제어해야 하는 시나리오에 적합합니다. 반면 Managed Agents는 미리 구축되어 설정 가능한 에이전트 실행 환경을 제공하며, 장시간 작업, 비동기화, 샌드박스 격리가 필요한 워크로드에 최적화되어 있습니다.

Messages API와의 차이점

🎯 도입 권장 사항: AI가 스스로 코드를 작성하고 스크립트를 실행하며 웹 브라우징 후 결과를 요약하는 등의 백그라운드 작업을 구축 중이라면, Messages API와 직접 샌드박스를 연동하는 것보다 Managed Agents를 사용하는 것이 훨씬 효율적입니다. APIYI(apiyi.com) 플랫폼에서 두 방식을 비교 테스트하여 어떤 형태가 귀사의 비즈니스에 더 적합한지 빠르게 판단해 보시기 바랍니다.

4가지 핵심 개념

Claude Managed Agents는 다음과 같은 네 가지 기본 개념을 중심으로 설계되었습니다.

• Agent (에이전트): 모델, 시스템 프롬프트, 도구, MCP 서버 및 스킬의 정적 정의로, 한 번 생성하면 여러 세션에서 재사용할 수 있으며 버전 관리를 지원합니다.
• Environment (환경): 클라우드 컨테이너 템플릿으로, 사전 설치된 패키지, 네트워크 액세스 정책, 마운트된 파일 등을 설명합니다.
• Session (세션): 특정 Agent + Environment의 실제 실행 인스턴스로, 일회성 또는 장시간 작업의 실행을 담당합니다.
• Events (이벤트): 세션과 클라이언트 간에 교환되는 메시지로, 사용자 메시지, 도구 호출, 도구 결과, 상태 변경 등이 포함됩니다.

Managed Agents 핵심 역량 살펴보기: 샌드박스, 도구 세트 및 SSE 스트리밍

앞서 다룬 네 가지 개념을 바탕으로, 베타 버전에서 실제로 어떤 기능을 제공하는지 하나씩 살펴보겠습니다.

보안 샌드박스 및 컨테이너 구성

각 세션은 격리된 클라우드 컨테이너에서 실행되며, 다음과 같은 특징을 가집니다.

• 런타임 사전 설치: Python, Node.js, Go 등 주요 언어 환경을 즉시 사용할 수 있습니다.
• 네트워크 정책: unrestricted(제한 없음) 및 더 엄격한 제한적 네트워크 모드를 지원하여 샌드박스가 데이터 유출 경로로 악용되는 것을 방지합니다.
• 파일 시스템: 컨테이너 내 파일은 세션 수명 주기 동안 유지되며, Agent가 라운드 간에 파일을 읽고 쓸 수 있습니다.
• 리소스 마운트: 환경 설정(Environment)에서 데이터 파일이나 스크립트를 미리 마운트할 수 있습니다.

내장 도구 세트 agent_toolset_20260401

공개 테스트 버전에서는 통합 도구 세트 식별자인 agent_toolset_20260401을 제공하며, 이를 통해 사전 구축된 모든 도구를 한 번에 활성화할 수 있습니다.

🎯 개발자 팁: agent_toolset_20260401은 "통합 스위치"와 같아서 프로토타입을 빠르게 검증할 때 편리합니다. 프로덕션 환경에서는 최소 권한 원칙에 따라 필요한 하위 세트만 활성화하는 것을 권장합니다. APIYI(apiyi.com)에서 서로 다른 도구 하위 세트의 토큰 비용을 비교하고 싶다면, base_url만 변경하여 동일한 코드를 바로 재사용할 수 있습니다.

Server-Sent Events(SSE) 스트리밍 이벤트 모델

기존 메시지 API의 "요청 1회 → 응답 1회" 방식과 달리, Managed Agents는 이벤트 기반 + SSE 푸시 모델을 채택했습니다. 주요 이벤트 유형은 다음과 같습니다.

Claude Managed Agents 빠르게 시작하기: API 연결 전체 과정

Managed Agent 세션을 완벽하게 실행하는 과정을 가장 짧은 코드로 보여드리겠습니다. 핵심 단계는 다음과 같습니다: Agent 생성 → 환경 생성 → 세션 생성 → 메시지 전송 및 SSE 스트림 구독.

사전 준비 사항

1. Claude API 키(또는 APIYI apiyi.com의 호환 키).
2. 요청 시마다 anthropic-beta: managed-agents-2026-04-01 헤더 포함; 공식 SDK는 자동으로 추가해주지만, 수동 curl 사용 시에는 명시적으로 선언해야 합니다.
3. Python SDK 최신 버전 업데이트: pip install -U anthropic.

파이썬(Python) 간편 예시

from anthropic import Anthropic

client = Anthropic(
    # APIYI 중계 서비스를 사용하면 기존 코드를 재사용할 수 있으며, SDK 사용법을 변경할 필요가 없습니다.
    base_url="https://api.apiyi.com",
    api_key="YOUR_API_KEY",
)

# 1. Agent 생성
agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",
    system="당신은 유용한 코딩 보조 도구입니다.",
    tools=[{"type": "agent_toolset_20260401"}],
)

# 2. 환경 생성 (제한 없는 네트워크)
env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

# 3. 세션 생성
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

# 4. SSE 스트림 열기 및 사용자 메시지 전송
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": "피보나치 수열의 처음 20개 숫자를 생성하여 fibonacci.txt 파일에 저장해줘.",
            }],
        }],
    )
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                print(block.text, end="")
        elif event.type == "agent.tool_use":
            print(f"\n[도구 사용: {event.name}]")
        elif event.type == "session.status_idle":
            print("\n\n대리인 작업 완료.")
            break

# Beta 헤더를 포함하여 Agent 생성
curl -sS https://api.apiyi.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "system": "당신은 유용한 코딩 보조 도구입니다.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }'

# 환경 및 세션 생성 요청 구조는 비슷하며, 공식 퀵스타트 문서를 참조하세요.
# SSE 스트림 구독 시 사용:
# curl -N -H "Accept: text/event-stream" \
#   https://api.apiyi.com/v1/sessions/$SESSION_ID/stream

🎯 코드 재사용 제안: 위 base_url을 APIYI apiyi.com으로 지정하면 중국 본토에서도 낮은 지연 시간으로 Managed Agents 공개 테스트 인터페이스에 접속할 수 있습니다. 공식 SDK의 모든 매개변수, Beta 헤더, 이벤트 유형이 완벽하게 호환되므로 별도의 래핑이 필요 없습니다.

5단계 프로세스 도표

[클라이언트] ──1. 에이전트 생성──────────▶ [API]
[클라이언트] ──2. 환경 생성────────────▶ [API]
[클라이언트] ──3. 세션 생성────────────▶ [API]
[클라이언트] ──4. SSE 스트림 열기───────▶ [API]
[클라이언트] ──5. 사용자 메시지 전송─────▶ [API]
          ◀─ 에이전트 메시지 / 도구 사용 / 도구 결과 / 유휴 상태 ──

전체 과정의 핵심은 이벤트 선행, 스트림 수신입니다. 중간 상태를 놓치지 않도록 사용자(user) 이벤트를 보내기 전에 SSE 스트림을 먼저 여는 것을 권장합니다.

Claude Managed Agents 핵심 규칙: 속도 제한, 과금 및 브랜드 규정 준수

공개 베타 버전에서 프로덕션 환경을 위한 명확한 매개변수가 제시되었습니다. 개발자분들이 가장 궁금해하실 세 가지 핵심 규칙을 정리해 드립니다.

속도 제한(Rate Limit) 규칙

속도 제한은 조직(Organization) 단위로 집계되며, 계정의 티어(Tier)와는 별개로 적용됩니다.

이와 별개로 조직 단위의 소비 한도와 티어별 속도 제한은 그대로 유지됩니다. 높은 동시성을 요구하는 대규모 에이전트 작업은 사전에 속도 제한 계획을 세우거나, APIYI(apiyi.com)를 통해 여러 계정의 리소스 풀로 분산하는 것이 좋습니다.

과금 모델

Managed Agents의 비용은 다음 두 가지 항목으로 구성됩니다.

1. 세션 실행 비용: 세션 시간당 $0.08.
2. 모델 토큰 비용: 선택한 Claude 모델(예: Sonnet 4.6 / Opus 4.6)의 표준 단가 적용.

별도의 구독료나 고정 인프라 비용은 없습니다. 단, 사용하지 않더라도 세션을 종료하지 않으면 시간당 요금이 계속 부과되므로, 작업이 끝나면 반드시 종료 인터페이스를 호출해야 합니다.

브랜드 규정 준수 가이드

Anthropic은 파트너사가 Claude 브랜드를 사용할 때 다음과 같은 명확한 제약을 두고 있습니다.

• ✅ 허용: Claude Agent, Claude(메뉴 문맥 내), {YourAgentName} Powered by Claude.
• ❌ 금지: Claude Code, Claude Code Agent, Claude Cowork 등의 명칭 사용 금지. 또한 Claude Code의 ASCII 아트나 시각적 요소를 모방하는 행위도 금지됩니다.

🎯 규정 준수 팁: 기업용으로 제공되는 관리형 에이전트 제품의 경우, 자체 브랜드의 주도권을 유지하고 기술 설명란에만 "Powered by Claude"라고 명시하는 것을 권장합니다. 공식적인 브랜드 라이선스나 템플릿 UI가 필요하다면 APIYI(apiyi.com)를 통해 협력 채널의 연결 가이드를 확인해 보세요.

Claude Managed Agents 주요 활용 사례: 어떤 업무를 먼저 전환해야 할까?

공개 베타 버전에서는 일부 기능(outcomes, multiagent, memory)이 여전히 Research Preview 단계에 있지만, 다음 네 가지 시나리오에는 즉시 도입이 가능합니다.

즉시 전환을 권장하는 4가지 워크로드

도입을 권장하지 않는 시나리오

• 초저지연 실시간 대화: 세션 시작 및 SSE 오버헤드가 발생하여 100ms 단위의 빠른 응답이 필요한 UI에는 적합하지 않습니다.
• 엄격한 규정 준수가 필요한 로컬 배포: Managed Agents는 클라우드 서비스이므로 온프레미스(on-prem)를 지원하지 않습니다.
• 완벽한 커스텀 에이전트 루프가 필요한 연구 프로젝트: 이 경우에는 여전히 Messages API를 사용하여 직접 루프를 구축하는 것을 권장합니다.

🎯 전환 경로 제안: 기존의 "Messages API + 직접 구축한 도구 스케줄링" 방식의 에이전트 업무를 Managed Agents로 구현해 보세요. 동일한 프롬프트를 사용하여 두 버전을 실행한 뒤, 토큰 비용과 작업 완료율을 비교해 보는 것이 좋습니다. APIYI(apiyi.com)를 이용하면 하나의 키로 두 인터페이스를 모두 호출할 수 있어, 병렬 테스트 시 키를 번거롭게 교체할 필요가 없습니다.

FAQ: Managed Agents 사용 시 주의사항 및 팁

Q1: managed-agents-2026-04-01를 수동으로 추가해야 하나요?

공식 SDK(Python / TypeScript / Go / Java / C# / Ruby / PHP)를 사용하는 경우 수동으로 추가할 필요가 없으며, SDK가 베타 경로에서 자동으로 삽입합니다. 네이티브 curl이나 직접 구현한 HTTP 클라이언트를 사용하는 경우에만 anthropic-beta: managed-agents-2026-04-01 헤더를 명시적으로 추가해야 합니다. APIYI(apiyi.com) 중계 서비스를 이용하는 경우에도 표준 경로로 요청하는 것이 호환성 면에서 가장 좋습니다.

Q2: SSE 스트림이 끊기면 세션 정보가 손실되나요?

아닙니다. 세션의 이벤트 기록은 서버 측에 영구 저장되므로, 연결이 끊기더라도 /v1/sessions/{id}/stream 엔드포인트로 재연결하면 후속 이벤트를 계속 수신할 수 있습니다. API가 중단된 지점의 버퍼부터 다시 전송해 줍니다. 이는 "한 번 요청에 한 번 응답"하는 일반적인 Messages API와는 완전히 다른 방식입니다.

Q3: 실행 중인 Agent를 어떻게 중단하나요?

Managed Agents는 중간 실행 제어(mid-execution steering)를 지원합니다. 같은 세션의 /events 엔드포인트로 새로운 user.message를 보내면 현재 실행 중인 도구 호출 루프를 끊고 방향을 바꿀 수 있습니다. 또한 별도의 중단 엔드포인트를 통해 세션을 강제로 종료할 수도 있습니다.

Q4: 세션 비용은 어떤 경우에 발생하나요?

세션이 "실행 가능(runnable)" 상태로 유지되는 동안에는 Agent가 status_idle 상태라도 시간당 $0.08의 비용이 발생합니다. 작업이 완료되면 세션을 명시적으로 종료하여 불필요한 비용 발생을 방지하는 것이 좋습니다. APIYI(apiyi.com)의 청구 내역 대시보드를 활용하면 비정상적으로 유휴 상태인 세션을 빠르게 파악할 수 있습니다.

Q5: Managed Agents는 어떤 Claude 모델을 지원하나요?

현재 공개 베타에서는 Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 세 가지 주력 모델을 지원합니다. 긴 컨텍스트 윈도우(1M 토큰)는 Opus 4.6 및 Sonnet 4.6에서 별도의 베타 헤더 없이 기본적으로 사용할 수 있습니다.

Q6: 기존의 Agent Skills / MCP Server를 그대로 가져올 수 있나요?

네, 가능합니다. Agent 정의 내에서 MCP 서버 목록과 Skills 참조를 직접 선언할 수 있습니다. Managed Agents는 2025년 10월에 발표된 Agent Skills 베타 프로토콜을 그대로 사용하므로, 기존에 구축한 스킬 패키지를 수정 없이 바로 적용할 수 있습니다.

요약: Managed Agents가 가져온 개발 패러다임의 전환

Claude Managed Agents 공개 베타 출시는 Anthropic이 공식적으로 "Agent 인프라"를 제품 라인업에 포함했음을 의미합니다. 개발자 입장에서 이번 업데이트의 진정한 가치는 단순히 기능 하나가 추가된 것이 아니라, 자체 구축 Agent 시스템의 5대 난제(루프 구현, 도구 실행, 샌드박스 격리, 상태 유지, 이벤트 스트림 프로토콜)를 한 번에 해결했다는 점에 있습니다. managed-agents-2026-04-01 베타 요청 헤더를 추가하고 세 개의 엔드포인트를 호출하는 것만으로 Claude를 진정한 "자율 실행 대리인"으로 변모시킬 수 있습니다.

최신 Claude Sonnet 4.6 / Opus 4.6 모델, 1M 토큰 컨텍스트, Agent Skills 및 자동 캐싱 기능을 결합한 Managed Agents는 장시간 실행되는 비동기식 멀티 도구 백엔드 에이전트 업무를 처음으로 기업급 환경에서 구현할 수 있게 해줍니다. 우선 자동화 보고서 작성이나 코드 스캐폴딩과 같은 저위험 시나리오에서 시범 도입해 보고, 점진적으로 핵심 업무로 확장하는 것을 추천합니다.

🎯 운영 제안: 마이그레이션을 준비하는 팀이라면 base_url을 APIYI(apiyi.com)로 설정하는 것을 추천합니다. 공식 SDK 코드를 그대로 재사용하면서도 안정적인 국내 접속 속도를 보장받을 수 있으며, Messages API와 Managed Agents를 병행 테스트하여 의사결정에 필요한 데이터를 충분히 확보할 수 있습니다.

— APIYI Team (APIYI 기술팀)