Claude Managed Agents — 핵심 개념과 빠른 시작
Managed Agents 심층 학습 노트의 기초 편. Messages API와의 차이, 4대 핵심 개념, 작동 흐름, 사용 적합 상황, 설치 및 빠른 시작을 다룬다.
1. 핵심 개념 — Messages API vs Managed Agents
| 구분 | Messages API | Claude Managed Agents |
|---|---|---|
| 정의 | 모델 직접 프롬프트 접근 | 사전 구축된 에이전트 하네스 + 관리 인프라 |
| 적합한 용도 | 커스텀 에이전트 루프, 세밀한 제어 | 장시간 작업, 비동기 작업 |
| 인프라 | 직접 구축 | 완전 관리형 |
| 상태 관리 | 직접 구현 | 내장 (파일시스템 + 대화 이력) |
요약: 에이전트 루프, 도구 실행, 런타임을 직접 만들고 싶지 않다면 Managed Agents를 사용.
2. 4대 핵심 개념 (Core Concepts)
┌─────────────────────────────────────────────────────┐
│ Agent (에이전트) │
│ 모델 + 시스템 프롬프트 + 도구 + MCP 서버 + 스킬 │
│ │
│ Environment (환경) │
│ 컨테이너 템플릿 (패키지, 네트워크 접근) │
│ │
│ Session (세션) │
│ 환경 위에서 실행되는 에이전트 인스턴스 │
│ 특정 작업 수행, 출력 생성 │
│ │
│ Events (이벤트) │
│ 앱 ↔ 에이전트 간 메시지 │
│ (user turn, tool result, status update) │
└─────────────────────────────────────────────────────┘
| 개념 | 설명 |
|---|---|
| Agent | 모델, 시스템 프롬프트, 도구, MCP 서버, 스킬을 정의. 한 번 생성 후 ID로 여러 세션에서 재사용 |
| Environment | Python/Node.js/Go 등 패키지가 설치된 클라우드 컨테이너. 네트워크 규칙, 마운트된 파일 포함 |
| Session | 에이전트 + 환경 조합으로 실행되는 인스턴스. 특정 작업 수행 |
| Events | SSE(Server-Sent Events)로 스트리밍. 서버에 영구 저장되어 나중에도 조회 가능 |
3. 작동 흐름 (How It Works)
1. Create Agent → 모델·프롬프트·도구 정의, ID 저장
↓
2. Create Environment → 클라우드 컨테이너 구성
↓
3. Start Session → agent_id + environment_id로 세션 생성
↓
4. Send Events & Stream → user 메시지 전송, SSE로 실시간 수신
↓
5. Steer or Interrupt → 실행 중 추가 메시지로 방향 조정 또는 중단
컨테이너 내부에서 벌어지는 일:
- 컨테이너 프로비저닝
- Claude가 도구 사용 여부 결정 (에이전트 루프)
- 도구 실행 (파일 쓰기, bash 명령, 웹 검색 등)
- 이벤트 스트리밍 (실시간)
session.status_idle이벤트로 완료 알림
4. 사용 적합 상황 (When to Use)
- 장시간 실행 — 수 분~수 시간, 다수의 도구 호출
- 클라우드 인프라 — 패키지 사전 설치, 네트워크 접근이 필요한 안전한 컨테이너
- 최소 인프라 — 에이전트 루프, 샌드박스, 도구 실행 레이어를 직접 만들기 싫을 때
- 상태 유지 세션 — 여러 상호작용에 걸친 영구 파일시스템 + 대화 이력
5. 설치 및 빠른 시작 (Quickstart)
5.1 CLI 설치
# macOS
brew install anthropics/tap/ant
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"
# Linux/WSL
VERSION=1.0.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
| sudo tar -xz -C /usr/local/bin ant5.2 SDK 설치
pip install anthropic # Python
npm install @anthropic-ai/sdk # TypeScriptexport ANTHROPIC_API_KEY="your-api-key-here"중요: 모든 Managed Agents API 요청에는
managed-agents-2026-04-01베타 헤더가 필요. SDK는 자동으로 설정.
5.3 전체 흐름 코드 예시 (Python)
from anthropic import Anthropic
client = Anthropic()
# 1. 에이전트 생성
agent = client.beta.agents.create(
name="Coding Assistant",
model="claude-sonnet-4-6",
system="You are a helpful coding assistant. Write clean, well-documented code.",
tools=[{"type": "agent_toolset_20260401"}],
)
print(f"Agent ID: {agent.id}")
# 2. 환경 생성
environment = client.beta.environments.create(
name="quickstart-env",
config={
"type": "cloud",
"networking": {"type": "unrestricted"},
},
)
# 3. 세션 시작
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Quickstart session",
)
# 4. 스트림 열기 + 메시지 전송 + 이벤트 처리
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에 저장하는 Python 스크립트를 만들어줘",
}],
}],
)
for event in stream:
match event.type:
case "agent.message":
for block in event.content:
print(block.text, end="")
case "agent.tool_use":
print(f"\n[도구 사용: {event.name}]")
case "session.status_idle":
print("\n\n에이전트 완료.")
breakRelated
- 2026-04-11-claude-managed-agents-deep-dive — 허브/개요
- 2026-04-11-claude-managed-agents-tools — 내장 도구와 커스텀 도구
- 2026-04-11-claude-managed-agents-reference — 이벤트·Rate Limit·베타 상태 참고