클로드 매니지드 에이전트 다이내믹 워크플로우 설정·한도 정리

클로드 매니지드 에이전트(Claude Managed Agents)의 다이내믹 워크플로우는 에이전트가 문서 수백 건 검토처럼 조각이 많은 일을 만나면 여러 에이전트를 단계별로 돌리는 프로그램을 스스로 짜서 서버에서 실행하는 기능이다. Anthropic은 릴리스 노트에서 2026년 10월 9일 이 기능을 베타로 열었다고 밝혔다. 이 글은 2026년 10월 10일 기준으로 켜는 방법, 실행을 따라가는 방법, 한도와 비용을 정리한다.

클로드 매니지드 에이전트는 무엇인가

클로드 매니지드 에이전트는 에이전트 반복 루프, 도구 실행, 샌드박스(격리된 실행 환경)를 Anthropic이 맡아 주는 서비스다. 개발자는 에이전트(모델·시스템 프롬프트·도구), 환경, 세션, 이벤트 네 가지만 다룬다. 몇 분에서 몇 시간 걸리는 비동기 작업에 맞고, 베타 기간에는 모든 요청에 managed-agents-2026-04-01 베타 헤더가 필요하다(SDK는 자동으로 붙인다).

다이내믹 워크플로우로 달라진 점

공식 문서는 멀티에이전트 문서에서 에이전트가 일을 넘기는 방식을 세 가지로 구분한다. 이번에 추가된 것은 두 번째다.

방식	누가 흐름을 정하나	적합한 일
서브에이전트	에이전트가 직접 위임하고 각자의 보고를 읽는다	몇 개 안 되는 하위 작업
다이내믹 워크플로우	에이전트가 짠 프로그램이 여러 에이전트를 돌리고 결과를 합친다	문서 수백 건 검토, 여러 출처 교차 확인 같은 큰 작업
어드바이저	에이전트가 작업하며 자문 모델에게 조언을 구한다	판단이 어려운 지점의 점검

워크플로우 프로그램은 에이전트를 동시에 돌리고(팬아웃), 앞 단계 결과를 다음 단계 에이전트에 넘기고, 검토를 통과할 때까지 반복하고, 에이전트 하나가 실패했을 때 처리하는 일까지 맡는다. 실행이 끝나면 세션의 에이전트가 결과를 읽고 사용자에게 답하거나 새 실행을 시작한다. 실행 중에도 에이전트는 다른 일을 계속하거나 턴을 끝낼 수 있다.

다이내믹 워크플로우 켜는 방법

공식 문서대로 에이전트를 만들 때 multiagent 필드에 타입 multiagent_20261001을 주고 workflows를 켠다. 이 타입에서는 워크플로우와 서브에이전트가 모두 기본으로 켜지므로, 워크플로우만 쓰려면 "subagents": {"type": "disabled"}를 더한다. 공식 문서의 계약서 검토 예시는 다음과 같다.

{
  "name": "Contract Reviewer",
  "model": "claude-opus-5-5",
  "system": "You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.",
  "tools": [{"type": "agent_toolset_20260401"}],
  "multiagent": {"type": "multiagent_20261001", "workflows": {"type": "enabled"}}
}

실행을 시작하는 별도의 API 호출은 없다. 사용자가 user.message로 일을 설명하면 에이전트가 워크플로우를 쓸지 판단한다. 위 예시처럼 시스템 프롬프트에 "몇 건 이상이면 실행을 시작하라"는 기준을 적어 주는 것이 판단을 안내하는 방법이다. 기존 에이전트의 multiagent.type을 바꾸기 전에는 공식 문서의 이전 안내를 먼저 본다.

실행 안의 에이전트는 워크플로우가 직접 정의한 인라인 에이전트이거나 workflows.predefined_agents에 미리 등록한 에이전트다. 인라인 에이전트는 세션 에이전트와 같은 모델을 쓰므로, 일부 작업에 다른 모델을 쓰려면 그 에이전트를 따로 만들어 predefined_agents에 올린다.

워크플로우 실행 상태와 이벤트 확인하는 법

공식 문서에 따르면 서버가 실행을 백그라운드로 돌리고, 진행은 세션의 이벤트 스트림에서 workflow_run.* 이벤트로 받는다. 폴링보다 스트림을 따라가는 쪽이 읽기 한도를 아낀다.

이벤트	의미
workflow_run.created	에이전트가 실행을 시작했다. 실행 이름과 선언된 단계(phases)를 담는다
workflow_run.status_running / status_idle	실행 중, 또는 예산 도달 등으로 일시 정지
workflow_run.phase_started / phase_ended	단계 시작과 종료
workflow_run.status_ended	실행 종료
workflow_run.error	시작 거부나 한도 초과 등의 오류

작업이 끝났는지는 세션이 idle이 됐는지만으로 판단하면 안 된다. 지금까지 시작된 모든 실행에 status_ended가 온 뒤에 사용자 요청과 무관한 session.status_idle(stop_reason이 end_turn)이 도착해야 끝난 것이다. 예산에서 멈춘 실행은 세션이 idle이어도 아직 열려 있다. 실행 안의 각 에이전트는 별도 세션 스레드에서 일하므로, 스레드를 조회해 각자 무엇을 했는지 읽을 수도 있다.

성공 여부는 세 가지로 확인한다. 첫째, 세션 이벤트에 workflow_run.created가 찍히고 phases에 선언한 단계가 보이는지 본다. 둘째, 단계마다 phase_started와 phase_ended가 짝으로 오는지 본다. 셋째, status_ended 뒤에 에이전트가 결과를 읽고 답하는 턴이 이어지는지 본다. 도중에 workflow_run.error가 오면 error.type으로 원인을 구분한다.

한도와 비용: 쓰기 전에 알아둘 숫자

실행에는 별도 가격이 없고, 에이전트들이 쓴 토큰이 각 모델의 요금으로 세션의 다른 토큰과 같이 청구된다. 실행의 모델 요청은 세션 예산에 포함되며, 예산에 닿으면 열린 실행이 모두 멈춘다. 예산을 올리거나 없애면 다시 돈다. 워크플로우 실행 문서가 밝힌 한도는 아래와 같다.

항목	값	한도에 닿으면
한 실행에서 동시에 일하는 스레드	64개	하나가 끝날 때까지 더 만들지 않는다(수치는 바뀔 수 있다)
워크플로우가 실행 전체에서 시작하는 에이전트	1,000개	thread_limit_error로 종료
실행 수명	기본 24시간	timeout_error로 종료
세션에서 동시에 열린 실행	기본 10개	max_workflow_runs_error, idle 실행도 포함해 센다

공식 문서는 한 실행 안의 에이전트들이 동시에 일해 긴 작업이 더 빨리 끝날 수 있다고 설명한다. 큰 작업을 맡기기 전에 세션 예산을 먼저 정하고, 한 실행의 사용량은 세션 스레드 목록에서 해당 workflow_run_id의 usage를 합산해 확인한다. 요금 자체는 매니지드 에이전트 요금표를 본다.

자주 하는 실수는 두 가지다. 하나는 세션이 idle이 된 순간을 작업 완료로 읽는 것이다. 예산에서 멈춘 실행은 세션이 idle이어도 열려 있으므로, 앞서 본 두 조건을 모두 확인한 뒤에 결과를 가져가야 한다. 다른 하나는 기준 없이 워크플로우를 켜 두는 것이다. 공식 문서는 실행을 쓸 시점을 시스템 프롬프트에 적어 에이전트의 판단을 안내하라고 권하므로, 몇 건 이상일 때 실행하라는 조건을 적어 둔다.

같은 주에 바뀐 매니지드 에이전트 소식

릴리스 노트에는 10월 7일 변경도 있다. 네트워크를 limited로 둔 클라우드 환경의 allowed_hosts가 이제 web_search와 web_fetch 도구에도 적용된다. 이때 웹 도구의 allowed_domains에 allowed_hosts 밖의 항목이 있으면 세션 생성이 400 오류로 실패한다. 또 web_fetch는 해당 세션에 이미 나온 URL만 가져온다. 기존 환경에 허용 목록을 쓰고 있다면 세션 생성 오류가 나는지 확인한다.

자주 묻는 질문

다이내믹 워크플로우는 따로 신청해야 하나요?

공식 문서는 매니지드 에이전트가 모든 API 계정에 기본으로 열려 있다고 안내한다. 에이전트의 multiagent 설정만 켜면 된다. 다만 기능이 베타라 동작이 바뀔 수 있다.

ZDR이나 HIPAA BAA 대상인가요?

아니다. 매니지드 에이전트는 세션 기록과 샌드박스 상태를 서버에 저장하는 구조라 현재 제로 데이터 보존(ZDR)과 HIPAA BAA 적용 대상이 아니라고 공식 문서에 적혀 있다.

서브에이전트와 워크플로우를 같이 켤 수 있나요?

된다. multiagent_20261001 타입은 둘 다 기본으로 켜지고, 워크플로우만 쓰려면 서브에이전트를 disabled로 바꾼다.