Back to BlogTutorial

Claude Managed Agents 10단계 가이드 — 단일 에이전트에서 20개 병렬 팀까지

7 min read0
#Claude Managed Agents#Multi Agent Sdk#코디네이터 패턴#Anthropic#Ai 에이전트 팀

Claude Managed Agents 10단계 가이드 — 단일 에이전트에서 20개 병렬 팀까지

혼자 일하는 프리랜서가 있습니다. 처음엔 괜찮아요. 그런데 프로젝트가 커지면서 코드 리뷰, 테스트 작성, 문서화, 배포까지 전부 혼자 처리하다 보면 결국 병목이 생겨요. 에이전트도 똑같아요.

Claude Managed Agents는 바로 그 문제를 해결합니다. 단일 에이전트를 코디네이터 + 전문 subagent 팀으로 분할해서, 각자 맡은 역할만 집중하도록 구성하는 Multi-Agent SDK예요. 2026-04-08 공개 베타로 출시됐고, 이 글은 10단계로 실제 에이전트 팀을 만드는 방법을 안내합니다.

단일 에이전트가 무너지는 이유

에이전트 하나에 너무 많은 역할을 주면 세 가지 문제가 생겨요.

첫째, 컨텍스트 한계입니다. 코드 리뷰 + 테스트 작성 + 문서화를 하나의 대화 스레드에 밀어 넣으면, 앞부분 맥락이 사라지기 시작해요.

둘째, 병렬 처리 불가입니다. 작업이 순차적으로만 처리되니까 전체 소요 시간이 선형으로 늘어나요. Anthropic 엔지니어링 블로그에 따르면, 에이전트 팀 구조로 전환했을 때 첫 번째 응답 시간(TTFT) p50이 60%, p95가 90% 이상 줄었다고 해요.

셋째, 모델 비용 비최적화입니다. 단순 분류 작업에 고성능 모델을 쓸 이유가 없는데, 에이전트가 하나면 선택지가 없어요.

에이전트 팀을 만들면 이 세 문제를 동시에 해결할 수 있어요.

3가지 빌딩 블록 — Brain / Hands / Sessions

Anthropic은 에이전트를 세 레이어로 설명해요.

  • Brain — Claude 모델 + 하네스(시스템 프롬프트, 에이전트 정의 YAML)
  • Hands — 샌드박스 환경 + 도구 세트(파일, bash, 웹 검색 등)
  • Sessions — 이벤트 로그. 추가만 가능한 append-only 구조로, 에이전트 간 맥락이 격리됩니다

Brain / Hands / Sessions 이 세 레이어를 이해하면 왜 에이전트가 독립적으로 동작하면서도 파일시스템을 공유할 수 있는지 바로 납득이 돼요.

각 subagent는 독립된 컨텍스트를 갖고 있어요. 다른 에이전트의 대화 기록을 직접 볼 수 없죠. 그런데 컨테이너, 파일시스템, 볼트(vault)는 팀 전체가 공유해요. 파일을 통해 결과를 주고받는 구조예요.

결정 단계 (Decide & Design) — 1~3단계

에이전트 팀은 코드부터 짜는 게 아니에요. 설계가 먼저예요.

1단계: 에이전트 팀이 필요한지 판단하기

Multi-Agent SDK를 쓰면 토큰 비용이 단일 에이전트 대비 10~15배 더 들어요. 병렬 처리로 시간을 줄이는 대신, 비용이 늘어나는 트레이드오프가 있어요. 단순한 작업이라면 오히려 단일 에이전트가 나아요.

에이전트 팀이 맞는 경우는 이럴 때예요:

  • 독립적으로 처리 가능한 서브태스크가 3개 이상
  • 각 서브태스크에 서로 다른 모델이나 도구가 필요
  • 전체 처리 시간을 단축해야 할 때

2단계: 코디네이터와 specialist 정의

코디네이터는 작업을 분배하고 결과를 취합하는 역할이에요. 직접 실행은 최소화하고, subagent에게 위임하는 게 핵심이에요.

specialist는 단일 역할에 집중해요. "코드 리뷰 전용", "테스트 작성 전용"처럼 명확하게 범위를 잘라야 컨텍스트가 깔끔하게 유지돼요.

3단계: depth 1 제약 인식

Claude Managed Agents는 depth 1단계만 허용해요. 코디네이터가 subagent에게 위임할 수 있지만, 그 subagent가 또 다른 subagent에게 위임하는 건 SDK 수준에서 무시돼요. 이 제약을 설계 초반에 인식하지 못하면 나중에 구조 전체를 다시 짜야 해요.

depth > 1이 필요하다면, 코디네이터를 여러 레이어로 나누는 대신 코디네이터 하나 아래에 specialist를 평탄하게(flat) 배치하는 방식으로 해결해요.

빌드 단계 (Build the Team) — 4~7단계

설계가 끝났으면 이제 코드로 구현해요.

4단계: 환경 준비

Multi-Agent SDK 베타를 활성화하려면 API 요청에 베타 헤더를 추가해야 해요.

anthropic-beta: managed-agents-2026-04-01

SDK를 직접 사용하면 이 헤더가 자동으로 주입돼요.

5단계: specialist 에이전트 정의

각 specialist를 YAML 또는 SDK로 정의해요. 모델 필드(model)는 필수예요. SDK에 기본값이 없어서 생략하면 오류가 나요. 공식 문서 예시는 claude-opus-4-7을 사용하고, 쿡북 예시는 claude-opus-4-6을 사용해요.

name: Code Reviewer
model: claude-opus-4-7
system: You are an expert code reviewer. Focus on correctness, security, and readability.
tools:
  - type: agent_toolset_20260401

agent_toolset_20260401은 bash, 파일 조작, 검색, 웹 접근 등 핵심 도구를 묶은 타입이에요.

6단계: 코디네이터 정의

코디네이터는 multiagent 블록에서 타입을 coordinator로 지정하고, 위임할 subagent를 나열해요.

name: Engineering Lead
model: claude-opus-4-7
system: |
  You coordinate engineering work.
  Delegate code review to the reviewer agent and
  test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID
    - type: agent
      id: $TEST_WRITER_AGENT_ID

코디네이터 하나에 최대 20개 unique 에이전트를 연결할 수 있어요. 20 에이전트가 동시에 돌아가니까 복잡한 파이프라인도 소화할 수 있어요.

7단계: 모델 믹스 전략

모든 에이전트에 같은 모델을 쓸 필요가 없어요. 비용과 품질을 동시에 잡는 전략이 있어요.

Spiral by Every는 실제 사례예요. 코디네이터에 Haiku 4.5(저비용, 빠름)를 쓰고, 실제 작업을 처리하는 subagent에 Opus 4.7(고성능)을 배치했어요. 결과는 "roughly 1/5 cost" — 단일 Opus 4.7 에이전트 대비 약 1/5 비용으로 frontier급 품질을 냈다고 해요.

코디네이터는 라우팅과 조율만 하니까 저렴한 모델로도 충분해요. 실제 추론이 필요한 specialist에만 비싼 모델을 쓰는 거예요.

운영 단계 (Run, Observe, Improve) — 8~10단계

팀을 만들었으면 이제 실행하고 관찰해야 해요.

8단계: Persistent Session Thread 활용

에이전트 팀은 멀티에이전트 세션을 지원해요. 2026-05-06에 별도 공개 베타로 출시됐어요. Session thread가 영속적이라서 동일 세션에서 후속 질문을 주고받는 follow-up이 가능해요.

예를 들어 "코드 리뷰해줘" 다음에 "방금 찾은 이슈 중 보안 관련만 다시 정리해줘"를 같은 세션에서 이어갈 수 있어요.

9단계: 쿡북으로 패턴 확인

Anthropic이 공식으로 제공하는 쿡북에는 12개 이상의 노트북이 들어 있어요. 대표 패턴 두 가지예요:

  • Sales Proposal (CMA_coordinate_specialist_team.ipynb) — 코디네이터가 리서처·라이터·가격 모델러 specialist에게 위임해서 제안서를 생성하는 패턴.
  • Incident Response — 장애 발생 시 deploy / logs / metrics / tickets 4개 specialist가 동시에 원인 분석을 병렬로 처리하는 패턴 (Anthropic Multi-agent docs 표준 예시).

처음 에이전트 팀을 만든다면 이 세 패턴 중 하나를 참고해서 시작하는 게 가장 빨라요.

10단계: 비용과 속도 모니터링

토큰 사용량을 주기적으로 확인하는 게 중요해요. 에이전트 수를 20개까지 늘리면 비용도 함께 늘어요. TTFT가 개선됐는지도 측정해야 병목이 어디 있는지 파악할 수 있어요.

자주 하는 5가지 실수

1. depth 1 제약을 모르고 설계 subagent가 또 다른 subagent를 호출하는 2단계 위임을 설계했다가 SDK 제약에 막혀요. 항상 코디네이터 → specialist의 단일 레이어만 동작한다고 기억하세요.

2. 모든 에이전트에 동일한 고성능 모델 사용 Opus 4.7을 20개 에이전트에 다 넣으면 비용이 폭발해요. 코디네이터는 경량 모델로, 핵심 추론 specialist에만 고성능 모델을 배치하세요.

3. 모델 필드 생략 SDK에 기본 모델이 없어요. model 필드를 빠뜨리면 오류가 나요. 에이전트 정의 YAML마다 반드시 명시하세요.

4. subagent 역할을 너무 넓게 정의 "무엇이든 다 하는 specialist"는 의미가 없어요. 역할이 명확할수록 컨텍스트가 깔끔하고 품질이 올라가요. 단일 책임 원칙은 코드뿐 아니라 에이전트에도 적용돼요.

5. Persistent Session 없이 stateless로만 운영 단발 실행만 구성하면 follow-up이 안 돼요. 멀티에이전트 세션(2026-05-06 베타)을 함께 설정하면 대화를 이어갈 수 있어요.

마무리 — 작게 시작하라

에이전트 팀을 처음 만들 때는 코디네이터 1개 + specialist 2개부터 시작하는 게 좋아요. 코드 리뷰어와 테스트 작성자처럼 명확하게 분리된 역할 두 개면 충분해요.

작게 시작해서 병목을 확인한 다음, specialist를 하나씩 추가하면서 20개 한도까지 확장해 나가는 게 안전한 방법이에요.

Claude Managed Agents는 아직 공개 베타(2026-04-08 출시)예요. 프로덕션 배포 전에 Anthropic 공식 Multiagent sessions 문서에서 최신 제약 사항을 반드시 확인하세요.

이 글은 2026-05-27 기준 공개된 Anthropic 1차 출처(T0/T1)를 바탕으로 작성했어요. Claude Managed Agents는 공개 베타 단계라 API 사양이 변경될 수 있습니다.

자주 묻는 질문 (FAQ)

Q: Claude Managed Agents는 무료로 사용할 수 있나요?

Claude Managed Agents 자체는 별도 비용 없이 Anthropic API를 통해 이용할 수 있어요. 다만 에이전트 팀을 구성하면 단일 에이전트 대비 토큰 소비가 10~15배 증가할 수 있어요. API 사용 비용은 각 에이전트가 사용하는 모델 요금에 따라 책정돼요.

Q: 코디네이터 하나에 몇 개까지 에이전트를 붙일 수 있나요?

최대 20개 unique 에이전트를 연결할 수 있어요. depth는 1단계만 지원해서, 코디네이터 아래에 specialist를 flat하게 배치하는 구조여야 해요. subagent가 또 다른 subagent에게 위임하는 depth > 1은 SDK에서 자동으로 무시됩니다.

Q: multiagent sessions와 Managed Agents는 다른 건가요?

네, 별도예요. Claude Managed Agents는 2026-04-08에 공개 베타로 출시됐고, Multiagent sessions는 2026-05-06에 별도 공개 베타로 나왔어요. 두 기능을 함께 사용하면 에이전트 팀이 영속적인 세션 스레드를 통해 follow-up 대화를 이어갈 수 있어요.

참고자료

  1. Multiagent sessions — Claude Platform Docs — 베타 헤더 managed-agents-2026-04-01, 20 agents roster, depth 1 제약, agent_toolset_20260401, persistent session thread 공식 명시
  2. Scaling Managed Agents: Decoupling the brain from the hands — Brain/Hands/Sessions 공식 용어 + TTFT p50 ~60% / p95 90%+ 감소
  3. Define your agent — Claude Platform Docs — agent 생성 명세, model 필드 Required
  4. Anthropic Cookbook — managed_agents — Sales proposal 등 12+ 노트북 예제
  5. Introducing Spiral v3 — Every — Haiku 4.5 lead + Opus 4.7 subagents 패턴
  6. How we built our multi-agent research system — multi-agent 10–15× more tokens (비용 측면)
  7. Scaling AI Agent Development at Netflix (Webinar) — Anthropic + Netflix 3,000+ 개발자 협업 (Claude Sonnet 4.5)
  8. Claude API Release Notes — Managed Agents 2026-04-08 / Multiagent sessions 2026-05-06 출시 일정

(접속일: 2026-05-27 KST)

© 퀀텀점프클럽 정상록 · qjc.app

⚠️ 면책 고지: 이 글은 AI 보조 도구의 지원을 받아 작성됐습니다. Claude Managed Agents는 공개 베타 단계로, 기능 및 API 사양이 변경될 수 있습니다. 프로덕션 적용 전 Anthropic 공식 문서를 최신 버전으로 확인하세요.