Claude Managed Agents 동적 워크플로 사용법: 병렬 분석부터 결과 통합까지

Claude Managed Agents의 동적 워크플로(dynamic workflows)는 여러 에이전트를 단계 안에서 병렬로 실행하고, 반환값을 다음 단계에 넘겨 합치는 기능입니다. Anthropic은 2026년 10월 9일 이 기능을 베타로 출시했습니다.

문서 묶음을 나눠 분석한 뒤 하나의 보고서로 합치는 작업에 적용할 수 있습니다. 여기서는 Claude Platform API의 설정과 요청 방법, 완료 확인 조건을 다룹니다. Claude 앱이나 Claude Code의 설정법과는 구분해야 합니다.

이 글에서 사용하는 주요 용어 정의

아래 구분을 알면 설정 대상과 실행 기록을 혼동하지 않습니다.

용어정의

agent	모델·지침·도구를 담은 에이전트 설정입니다.
session	에이전트와 실행 환경을 연결해 작업하는 단위입니다.
workflow run	에이전트가 작성한 워크플로 프로그램의 실행입니다.
phase / thread	phase는 실행 단계, thread는 개별 에이전트의 대화 맥락입니다.

1. 준비한 agent에 워크플로 설정 넣기

Console 계정과 API 키를 준비하고, 공식 시작 문서에 따라 agent와 environment를 만든 뒤 이를 참조하는 session을 생성합니다. Python SDK 설치 명령은 pip install anthropic, 키 환경변수는 ANTHROPIC_API_KEY입니다. Managed Agents의 베타 헤더는 managed-agents-2026-04-01입니다.

Anthropic의 Multiagent orchestration 문서에 따른 설정은 아래와 같습니다. 공식 문서 기반 미실행 예제이며, 완전한 API 요청이 아닌 agent 정의의 부분 객체입니다.

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": { "type": "enabled" },
    "subagents": { "type": "disabled" }
  }
}

이 예제는 워크플로를 허용하고 직접 서브에이전트 위임은 끕니다. 해당 타입에서는 둘 다 기본 활성화되므로 사용할 방식을 명시하면 설정 의도가 분명해집니다. agent를 수정했다면 새 session을 만들어야 변경이 반영됩니다.

2. 병렬 분석과 통합 조건을 요청에 적기

시스템 지침이나 user.message에 워크플로를 쓸 조건을 넣습니다. 별도의 워크플로 시작 API를 호출하는 방식이 아니라 에이전트가 요청을 보고 시작 여부를 판단합니다.

다음은 기술 문서 분석용 요청 예제입니다. 실제 실행 결과가 아니며 파일명도 설명용입니다. 먼저 세션에서 문서 파일을 읽을 수 있도록 준비한 뒤, 이벤트 스트림을 열고 메시지를 보냅니다.

입력: 세션에 준비한 기술 문서 A, B, C.
동적 워크플로를 사용해 다음 순서로 처리해 주세요.

1단계: 문서별 분석을 병렬 실행합니다.
각 결과에는 문서명, 핵심 주장, 근거 위치,
확인할 수 없는 항목을 같은 형식으로 담습니다.

2단계: 분석 결과를 모아 공통점과 충돌을 비교합니다.
근거가 없는 결론은 보류하고 누락 문서를 표시합니다.

최종 결과: summary.md에 통합 보고서를 작성하고,
실패한 작업과 처리하지 못한 항목을 별도로 보고합니다.

이 설계에서 병렬로 처리하는 부분은 1단계의 문서 분석입니다. 통합 단계는 앞선 결과를 받아 수행합니다. 문서명과 근거 위치를 공통 출력 항목으로 정하면 합칠 때 출처를 추적하기 쉽습니다.

실제 단계 구성과 에이전트 수는 작업과 모델 판단에 따라 달라질 수 있습니다. 고정된 실행 순서를 보장하는 설정으로 받아들이면 안 됩니다.

3. 실행 종료와 결과 품질을 따로 확인하기

Anthropic의 Workflow runs 문서는 세션 이벤트 스트림으로 실행을 추적하도록 안내합니다. 다음 순서로 관찰합니다.

1. workflow_run.created에서 생성된 실행을 기록합니다.
2. phase_started·phase_ended로 단계 진행을 확인합니다.
3. workflow_run.status_ended의 result에서 종료 유형을 읽습니다.
4. 생성된 모든 run이 끝난 뒤, session.status_idle의 stop_reason이 end_turn인지 확인합니다.

completed만으로 결과 품질까지 통과한 것은 아닙니다. 일부 작업 실패를 처리하고도 실행은 completed로 끝날 수 있습니다. 개별 thread 이벤트와 최종 보고서의 누락 목록을 함께 확인해야 합니다. 직접 interrupt해서 생긴 idle도 완료로 세면 안 됩니다.

적용 전에 정할 것

run의 모델 사용량은 session 예산에 포함됩니다. session 생성 시 예산을 설정하되 병렬 요청으로 예산을 초과할 수 있다는 점을 고려하세요. 병렬 처리만으로 비용 절감이나 일정한 속도 향상이 보장되지는 않습니다.

thread들은 파일을 공유하므로, 위 예제를 확장할 때는 문서별 출력 경로를 나누고 통합 단계에서 최종 파일을 쓰도록 요청하는 편이 좋습니다. user.interrupt만으로 run이 종료되지는 않으며, 중지하려면 에이전트에게 실행 중지를 요청해야 합니다.

처음에는 작은 문서 묶음으로 시작하세요. 통합 보고서에서 문서별 근거와 누락 항목을 추적할 수 있는지 확인한 뒤 입력 범위를 늘리면 됩니다.

참고 링크

• Anthropic — Multiagent orchestration
• Anthropic — Workflow runs