LLM Wiki

Claude Managed Agents — 멀티 에이전트와 메모리

6 min read

Claude Managed Agents — 멀티 에이전트와 메모리

Managed Agents 심층 학습 노트의 고급 편. 두 기능 모두 Research Preview로, 코디네이터 기반 멀티 에이전트와 세션 간 영구 메모리 시스템을 다룬다.

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
)

그래프 뷰

백링크