Claude Managed Agents — 공식 문서 기반 심층 학습 노트

Anthropic이 제공하는 관리형 에이전트 하네스(harness). 직접 에이전트 루프를 만들 필요 없이, 보안 컨테이너 위에서 Claude가 자율적으로 파일 읽기/쓰기, 명령 실행, 웹 검색, 코드 실행을 수행한다.

---

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  →  실행 중 추가 메시지로 방향 조정 또는 중단

컨테이너 내부에서 벌어지는 일:

1. 컨테이너 프로비저닝
2. Claude가 도구 사용 여부 결정 (에이전트 루프)
3. 도구 실행 (파일 쓰기, bash 명령, 웹 검색 등)
4. 이벤트 스트리밍 (실시간)
5. 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 ant

5.2 SDK 설치

pip install anthropic          # Python
npm install @anthropic-ai/sdk  # TypeScript

export 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에이전트 완료.")
                break

---

6. 내장 도구 (Built-in Tools)

agent_toolset_20260401 타입 지정 시 아래 도구가 기본 활성화.

도구	이름	설명
Bash	bash	쉘 명령 실행
Read	read	파일 읽기
Write	write	파일 쓰기
Edit	edit	파일 문자열 치환
Glob	glob	파일 패턴 매칭
Grep	grep	정규식 텍스트 검색
Web fetch	web_fetch	URL에서 콘텐츠 가져오기
Web search	web_search	웹 검색

6.1 특정 도구 비활성화

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",
    tools=[{
        "type": "agent_toolset_20260401",
        "configs": [
            {"name": "web_fetch", "enabled": False},
            {"name": "web_search", "enabled": False},
        ],
    }],
)

6.2 일부 도구만 활성화 (화이트리스트 방식)

tools=[{
    "type": "agent_toolset_20260401",
    "default_config": {"enabled": False},  # 모든 도구 기본 비활성화
    "configs": [
        {"name": "bash", "enabled": True},
        {"name": "read", "enabled": True},
        {"name": "write", "enabled": True},
    ],
}]

---

7. 커스텀 도구 (Custom Tools)

Messages API의 사용자 정의 도구와 유사. Claude가 요청을 emit → 클라이언트 코드가 실행 → 결과를 Claude에게 반환.

agent = client.beta.agents.create(
    name="Weather Agent",
    model="claude-sonnet-4-6",
    tools=[
        {"type": "agent_toolset_20260401"},
        {
            "type": "custom",
            "name": "get_weather",
            "description": "특정 도시의 현재 날씨 조회. 날씨 관련 질문에만 사용.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "도시 이름"}
                },
                "required": ["location"],
            },
        },
    ],
)

커스텀 도구 베스트 프랙티스

1. 극도로 상세한 description 작성 — 가장 중요한 요소. 언제 써야 하는지, 언제 쓰면 안 되는지, 각 파라미터의 의미와 동작에 미치는 영향, 중요한 제한사항까지 명시. 도구당 최소 3~4문장.
2. 관련 작업은 하나의 도구로 통합 — create_pr, review_pr, merge_pr 대신 action 파라미터를 가진 단일 pull_request 도구로.
3. 도구 이름에 네임스페이스 사용 — db_query, storage_read 등 리소스 접두사로 명확성 확보.
4. 응답은 high-signal 정보만 — 의미 있는 안정적인 식별자(슬러그, UUID)만 반환. Claude가 다음 단계를 추론하는 데 필요한 필드만 포함.

---

8. 멀티 에이전트 (Multi-Agent) — Research Preview

접근 요청 필요: https://claude.com/form/claude-managed-agents

하나의 코디네이터(Orchestrator) 에이전트가 다른 전문 에이전트들을 호출하여 복잡한 작업을 병렬 처리.

8.1 아키텍처

Session
  └── Primary Thread (coordinator)
        ├── Thread A (reviewer agent)    ← 각자 독립된 컨텍스트
        ├── Thread B (test writer agent) ← 같은 컨테이너/파일시스템 공유
        └── Thread C (research agent)

• 공유: 컨테이너와 파일시스템
• 격리: 각 에이전트는 독립된 스레드에서 실행 (별도 대화 이력)
• 제한: 1단계 위임만 가능 (코디네이터 → 서브에이전트, 서브에이전트는 추가 위임 불가)

8.2 코디네이터 설정

# 서브에이전트 먼저 생성
reviewer_agent = client.beta.agents.create(
    name="Code Reviewer",
    model="claude-sonnet-4-6",
    system="코드 리뷰 전문가. 읽기 전용 도구만 사용.",
    tools=[{"type": "agent_toolset_20260401"}],
)
 
# 코디네이터에 callable_agents 등록
orchestrator = client.beta.agents.create(
    name="Engineering Lead",
    model="claude-sonnet-4-6",
    system="엔지니어링 작업 조율. 코드 리뷰는 reviewer 에이전트에게 위임.",
    tools=[{"type": "agent_toolset_20260401"}],
    callable_agents=[
        {"type": "agent", "id": reviewer_agent.id, "version": reviewer_agent.version},
    ],
)

8.3 멀티에이전트 적합 작업

케이스	설명
코드 리뷰	읽기 전용 도구를 가진 전문 리뷰어 에이전트
테스트 생성	프로덕션 코드를 건드리지 않고 테스트 작성
리서치	웹 도구를 가진 검색 에이전트가 요약 후 코디네이터에 전달

8.4 스레드 이벤트 타입

타입	설명
session.thread_created	코디네이터가 새 스레드 생성
session.thread_idle	에이전트 스레드 작업 완료
agent.thread_message_sent	에이전트가 다른 스레드로 메시지 전송
agent.thread_message_received	에이전트가 다른 스레드에서 메시지 수신

---

9. 메모리 시스템 (Memory) — Research Preview

접근 요청 필요: https://claude.com/form/claude-managed-agents

세션이 종료되어도 학습 내용이 유지되는 영구 메모리. 사용자 선호도, 프로젝트 규약, 이전 실수, 도메인 컨텍스트 보존.

9.1 메모리 구조

Memory Store (workspace 범위)
  ├── Memory (텍스트 문서, 최대 100KB)
  │     └── Memory Version (변경 이력 — 불변, 감사/롤백용)
  └── Memory (...)

9.2 메모리 도구 (세션에 메모리 스토어 연결 시 자동 활성화)

도구	설명
memory_list	스토어의 메모리 목록 조회 (경로 접두사 필터 가능)
memory_search	전체 텍스트 검색
memory_read	메모리 내용 읽기
memory_write	경로에 메모리 생성/덮어쓰기
memory_edit	기존 메모리 수정
memory_delete	메모리 삭제

9.3 메모리 스토어 생성 및 세션 연결

# 1. 스토어 생성
store = client.beta.memory_stores.create(
    name="User Preferences",
    description="사용자별 선호도 및 프로젝트 컨텍스트.",
)
 
# 2. (선택) 초기 메모리 씨딩
client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="항상 탭 대신 스페이스 2칸 사용. ISO-8601 날짜 형식.",
)
 
# 3. 세션에 연결
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[{
        "type": "memory_store",
        "memory_store_id": store.id,
        "access": "read_write",           # 또는 "read_only"
        "prompt": "작업 시작 전 반드시 확인하세요.",
    }],
)

9.4 메모리 관리 팁

• 세션당 최대 8개 메모리 스토어 연결 가능
• 메모리 하나당 100KB 제한 (~25K 토큰)
• 큰 파일 하나보다 작고 집중된 파일 여러 개가 효율적
• 낙관적 동시성 제어: precondition 파라미터로 동시 쓰기 충돌 방지
  • {"type": "not_exists"} — 경로에 아무것도 없을 때만 쓰기
  • {"type": "content_sha256", "content_sha256": "..."} — 특정 해시와 일치할 때만 쓰기

9.5 버전 및 감사

# 변경 이력 조회
for v in client.beta.memory_stores.memory_versions.list(store.id, memory_id=mem.id):
    print(f"{v.id}: {v.operation}")  # created / modified / deleted
 
# 특정 버전 내용 조회 (롤백용)
version = client.beta.memory_stores.memory_versions.retrieve(
    version_id, memory_store_id=store.id
)
 
# 민감 정보 삭제 (규정 준수 — 감사 trail은 유지, 내용만 삭제)
client.beta.memory_stores.memory_versions.redact(
    version_id, memory_store_id=store.id
)

---

10. 이벤트 타입 참고

타입	방향	설명
user.message	앱 → 에이전트	사용자 메시지 전송
agent.message	에이전트 → 앱	에이전트 텍스트 응답
agent.tool_use	에이전트 → 앱	도구 사용 이벤트
user.tool_confirmation	앱 → 에이전트	도구 사용 허가/거부
user.custom_tool_result	앱 → 에이전트	커스텀 도구 실행 결과 반환
session.status_idle	에이전트 → 앱	에이전트 작업 완료
session.thread_created	에이전트 → 앱	멀티에이전트: 새 스레드 생성
session.thread_idle	에이전트 → 앱	멀티에이전트: 스레드 작업 완료

---

11. API Rate Limits

작업	제한
Create 엔드포인트 (agents, sessions, environments 생성 등)	분당 60 요청
Read 엔드포인트 (retrieve, list, stream 등)	분당 600 요청

• 조직 수준의 지출 한도 및 티어 기반 Rate Limit도 별도 적용.

---

12. 브랜딩 가이드라인 (파트너용)

허용	불허
”Claude Agent"	"Claude Code” 또는 “Claude Code Agent"
"Claude” (에이전트 메뉴 내부)	“Claude Cowork"
"{제품명} Powered by Claude”	Claude Code 스타일 ASCII 아트

---

13. 베타 상태 및 연구 프리뷰

기능	상태
기본 에이전트/세션/환경	공개 베타 (모든 API 계정 기본 활성화)
Outcomes (결과 정의)	Research Preview — 접근 요청 필요
Multi-agent (다중 에이전트)	Research Preview — 접근 요청 필요
Memory (메모리)	Research Preview — 접근 요청 필요

---

14. 실제 활용 사례 (기업)

기업	활용 내용
Notion	Custom Agents 알파 — 코드 배포, 웹사이트·프레젠테이션 병렬 제작
Rakuten	전사 에이전트 Slack/Teams 통합 (제품·영업·마케팅·재무·HR), 에이전트 1주 내 배포
Asana	AI Teammates — 인간과 협업하는 에이전트를 프로젝트 내 통합
Sentry	디버깅 에이전트 Seer + 패치 작성 에이전트 → 버그 탐지→PR 생성 자동화

---

15. 학습 체크리스트

• Agent, Environment, Session, Events 4대 개념 설명 가능한가?
• Messages API와 Managed Agents의 차이를 언제 어느 것을 쓸지 설명 가능한가?
• agent_toolset_20260401로 도구를 화이트리스트/블랙리스트 방식으로 설정 가능한가?
• 커스텀 도구 정의 시 좋은 description을 작성할 수 있는가?
• Multi-agent의 Thread 개념과 1단계 위임 제한을 이해하는가?
• Memory Store를 생성하고 세션에 연결하는 코드를 쓸 수 있는가?
• content_sha256 precondition으로 낙관적 동시성 제어를 구현할 수 있는가?
• SSE 스트림을 열고 이벤트 타입별로 처리하는 코드를 쓸 수 있는가?

---

Related

• Claude Managed Agents — 프로덕션 속도 10배 (마케팅 노트)
• Multica — 오픈소스 매니지드 AI 에이전트 플랫폼
• MOC: AI 에이전트 하네스
• MOC: AI 에이전트 메모리
• MOC: AI 에이전트 오케스트레이션

Sources

• 공식 개요
• 퀵스타트
• 도구 문서
• 멀티에이전트 문서
• 메모리 문서