핵심 요약
Anthropic이 Claude Managed Agents를 베타로 출시했습니다. 기존 Messages API와는 별도로, 사전 구축된 에이전트 하니스(harness)와 관리형 인프라를 제공합니다.
직접 에이전트 루프, 도구 실행 환경, 샌드박스를 구축할 필요 없이, Claude가 파일 읽기/쓰기, 쉘 명령 실행, 웹 검색, 코드 실행을 자율적으로 수행하는 환경을 바로 사용할 수 있습니다.
Messages API와의 차이
| Messages API | Managed Agents | |
|---|---|---|
| 성격 | 직접 모델 프롬프팅 | 관리형 에이전트 하니스 |
| 적합한 용도 | 커스텀 에이전트 루프, 세밀한 제어 | 장시간 실행, 비동기 작업 |
| 인프라 | 직접 구축 | Anthropic이 관리 |
핵심 개념 (4가지)
- Agent — 모델, 시스템 프롬프트, 도구, MCP 서버, 스킬을 정의한 설정
- Environment — 패키지, 네트워크 접근, 마운트 파일이 설정된 클라우드 컨테이너 템플릿
- Session — 에이전트+환경 위에서 실행되는 인스턴스. 특정 작업을 수행하고 결과를 생성
- Events — 앱과 에이전트 간 주고받는 메시지 (사용자 입력, 도구 결과, 상태 업데이트)
작동 방식
- Agent 생성 — 모델, 시스템 프롬프트, 도구를 정의. 한 번 만들면 ID로 재사용
- Environment 생성 — Python, Node.js 등 패키지가 설치된 컨테이너 설정
- Session 시작 — Agent + Environment를 참조하여 세션 실행
- 이벤트 송수신 — 사용자 메시지를 보내면 Claude가 자율적으로 도구를 실행하고 SSE로 결과를 스트리밍
- 중간 개입 — 실행 중에도 추가 이벤트를 보내 에이전트 방향을 조정하거나 중단 가능
내장 도구
- Bash — 컨테이너 내 쉘 명령 실행
- 파일 작업 — 읽기, 쓰기, 편집, glob, grep
- 웹 검색/가져오기 — 웹 검색 및 URL 콘텐츠 가져오기
- MCP 서버 — 외부 도구 제공자 연결
어떤 경우에 적합한가?
- 장시간 실행 — 수분~수시간에 걸친 다단계 도구 호출 작업
- 클라우드 인프라 필요 — 패키지가 설치된 보안 컨테이너 환경
- 인프라 최소화 — 에이전트 루프, 샌드박스, 도구 실행 레이어를 직접 만들고 싶지 않을 때
- 상태 유지 세션 — 파일 시스템과 대화 이력이 여러 상호작용에 걸쳐 유지
시작하기
Managed Agents는 모든 Anthropic API 계정에서 기본 활성화되어 있어 별도 신청 없이 곧바로 사용할 수 있습니다(Dreaming 등 일부 리서치 프리뷰 기능만 별도 신청).
사전 요구 사항
- Anthropic Console 계정과 API 키
- SDK(Python·TypeScript·Java·Go·C#·Ruby·PHP) 또는 직접 호출용 HTTP 클라이언트
- 모든 엔드포인트에
anthropic-beta: managed-agents-2026-04-01헤더(SDK 사용 시 자동 설정)
SDK 설치와 API 키 설정
# Python
pip install anthropic
# TypeScript
npm install @anthropic-ai/sdk
# 공통: API 키 환경변수
export ANTHROPIC_API_KEY="..."4단계 호출 흐름
- Agent 생성 — 모델·시스템 프롬프트·도구셋(
agent_toolset_20260401)을 정의해 ID 발급. 한 번 만들면 여러 세션에서 재사용 - Environment 생성 — 컨테이너 설정(네트워킹, 사전 설치 패키지, 마운트 파일) 정의해 ID 발급
- Session 생성 — Agent ID + Environment ID로 세션 시작
- 이벤트 송수신 —
user.message이벤트로 메시지를 보내면 Claude가 자율적으로 도구를 실행하고 SSE 스트림으로 결과를 돌려줍니다. 실행 중간에 추가 이벤트를 보내 방향을 조정하거나 중단할 수도 있습니다
Python 최소 예시:
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.",
tools=[{"type": "agent_toolset_20260401"}],
)
environment = client.beta.environments.create(
name="quickstart-env",
config={"type": "cloud", "networking": {"type": "unrestricted"}},
)
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Quickstart",
)세션에 메시지를 보내고 SSE 스트림을 처리하는 전체 예시(7개 언어 SDK·CLI·curl)는 공식 Quickstart 문서에 정리되어 있습니다.
인터랙티브 온보딩
최신 Claude Code에서 /claude-api managed-agents-onboard 명령을 실행하면 단계별 안내와 질의응답으로 셋업을 진행할 수 있습니다(Anthropic 공식 문서에서 안내).
레이트 리밋
조직 단위로 적용되며, 그 위에 API 티어별 한도가 함께 적용됩니다.
| 엔드포인트 종류 | 제한 |
|---|---|
| 생성(agents·sessions·environments 등) | 분당 300회 |
| 조회·스트림(retrieve·list·stream 등) | 분당 600회 |
과금 구조
Managed Agents는 토큰 비용 + 세션 런타임 비용 두 가지로 청구됩니다. 단순히 API 토큰 비용만 나가는 것이 아닙니다.
토큰 비용
- 일반 Messages API와 동일한 모델별 토큰 단가 적용
- 프롬프트 캐싱 할인도 동일하게 적용
- 세션 내 웹 검색은 1,000회당 $10 추가 과금
세션 런타임 비용
| 항목 | 요금 | 측정 기준 |
|---|---|---|
| 세션 런타임 | 시간당 $0.08 | running 상태 지속 시간 |
- 밀리초 단위로 정밀 측정
running상태일 때만 과금 —idle(대기),rescheduling,terminated상태는 과금되지 않음- Code Execution의 컨테이너 시간 과금을 대체 (중복 과금 없음)
비용 예시
Claude Opus 4.6으로 1시간 코딩 세션 (입력 50K 토큰, 출력 15K 토큰):
| 항목 | 계산 | 비용 |
|---|---|---|
| 입력 토큰 | 50,000 × $5/MTok | $0.25 |
| 출력 토큰 | 15,000 × $25/MTok | $0.375 |
| 세션 런타임 | 1시간 × $0.08 | $0.08 |
| 합계 | $0.705 |
Messages API와 다른 점
다음 할인/옵션은 Managed Agents에 적용되지 않습니다:
- Batch API 할인 (세션은 상태를 유지하는 대화형이므로)
- Fast mode 프리미엄 (런타임이 추론 속도를 관리)
- Data residency 옵션
- 서드파티 플랫폼 (AWS Bedrock, Vertex AI 등) — Claude API 직접 연결만 지원
알아두면 좋은 점
- 현재 베타 단계 — 모든 엔드포인트에
managed-agents-2026-04-01베타 헤더 필요 - SDK 사용 시 베타 헤더가 자동 설정됨
- 모든 API 계정에서 기본 활성화
- outcomes, multiagent, memory 기능은 리서치 프리뷰로 별도 신청 필요