Claude Managed Agents는 이제 큰 작업의 일부를 여러 에이전트에 할당하고, 각 에이전트의 조사 결과를 모아 결합하는 워크플로 프로그램을 작성할 수 있습니다. 이 기능은 베타입니다. 다음은 문서 폴더를 검토해 확인된 결과 파일을 만들려는 소프트웨어 개발자를 위한 문서화된 설정 방법입니다.

이 설정은 Anthropic의 Claude Platform API와 CLI를 사용합니다. BIG CHANGE는 최신 문서를 검토했으며 설정을 실행하거나 워크플로를 시험하지 않았습니다.

워크플로의 기능

하나의 동적 워크플로 는 한 번의 실행을 위한 프로그램입니다. 프로그램은 작업을 단계로 나누고, 에이전트 스레드를 병렬로 시작하며, 단계 간 결과를 전달하고, 실패한 분기를 재시도하거나 처리하고, 결과를 합칠 수 있습니다. 예를 들어 첫 단계에서 파일을 따로 살펴보고 다음 단계에서 결과를 조정할 수 있습니다. 기본 에이전트가 실행을 시작하고 서버가 백그라운드에서 수행합니다.

이는 주 에이전트에 별도 실행을 만들라고 요청하는 것과 다릅니다. 워크플로 실행은 하나의 실행 안에서 하위 스레드를 조정하고 시작한 에이전트에 결과를 돌려줍니다. 일반 세션 메시지 자체는 실행을 시작하지 않습니다. 에이전트가 작업과 시스템 프롬프트를 바탕으로 실행 시점을 결정합니다. Anthropic은 한 세션에 여러 실행이 열려 있을 수 있지만 각 실행은 고유한 단계와 결과를 가진다고 설명합니다.

시작하기 전에

Claude Console 계정, API 키, Claude Managed Agents 액세스가 필요합니다. Anthropic에 따르면 API 계정에는 기본적으로 활성화되어 있습니다. 에이전트 및 워크플로 엔드포인트에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. Anthropic SDK는 이 헤더를 자동으로 설정합니다. SDK 없이 API를 호출할 때는 직접 포함해야 합니다.

현재 문서에서 Managed Agents는 여전히 베타로 표시됩니다. Anthropic의 릴리스 노트 에 따르면 공개 베타는 2026년 4월 9일, 다중 에이전트 오케스트레이션은 5월 11일, 동적 워크플로는 10월 9일에 시작됐습니다. 동적 워크플로도 베타입니다. 날짜가 중요한 이유는 ‘에이전트 1,000개’가 현재 워크플로 실행 전체의 한도이며, 새로 생긴 1,000개 동시 실행 기능이 아니기 때문입니다.

플랫폼은 세션 대화 기록, 샌드박스 상태와 출력을 서버에 저장합니다. Anthropic은 Managed Agents가 현재 Zero Data Retention 또는 HIPAA Business Associate Agreement 적용 대상이 아니라고말합니다. 조직이 적용되는 데이터 규정과 설정을 확인하지 않았다면 규제 대상 또는 기밀 자료를 세션에 넣지 마세요.

1. CLI와 SDK 설치

Anthropic의 ant CLI를 운영체제에 맞는 방법으로 Managed Agents 빠른 시작 안내에 따라 설치합니다. 예를 들어 문서에 나온 macOS 명령은 다음과 같습니다:

Terminal
brew install anthropics/tap/ant

Python의 경우 SDK를 설치하고 API 키를 소스 파일에 넣지 말고 환경을 통해 제공합니다:

Terminal
pip install anthropic
export ANTHROPIC_API_KEY="your-api-key"

위 키는 자리 표시자입니다. 실제 값은 일반적인 비밀 관리 도구나 보호된 환경 설정에 보관하세요.

2. 워크플로를 사용할 에이전트 정의

다음을 만듭니다 document-reviewer.md. multiagent 블록이 10월 워크플로 유형을 활성화합니다. 하위 에이전트를 비활성화하면 설정된 위임 경로가 명확해집니다. 이 에이전트는 일회성 하위 에이전트 위임 대신 동적 워크플로를 사용합니다.

YAML
---
name: document-reviewer
model: claude-sonnet-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: disabled
  workflows:
    type: enabled
---

You review documents for a user-defined checklist.

When a request contains more than 20 independent files, use a dynamic workflow.
Make one phase that checks the files independently and a later phase that
reconciles duplicate findings. Do not infer missing facts. Save the final
machine-readable results to report.json and a concise explanation to summary.md.
Include the source filename and a short evidence excerpt for every finding.
If a file cannot be read or a worker fails, record that file as unresolved;
do not silently omit it. The final response must report the number of files
reviewed, unresolved files, and whether every output file was written.

임계값과 검토 지침은 Anthropic의 기본값이 아니라 사용자의 정책 선택입니다. 작업과 오류 비용에 맞게 조정하세요. claude-sonnet-5-5 는 예시 모델 ID입니다. 계정과 예산에서 현재 사용할 수 있는 모델을 선택하세요.

에이전트를 만들고 반환된 ID를 보관합니다:

Terminal
ant apply document-reviewer.md

CLI는 에이전트 ID를 출력하고 이를 claude-lock.json에 기록합니다. Managed Agents는 재사용 가능한 에이전트 정의(모델, 지침, 도구)와 세션이 실행되는 환경을 분리합니다.

3. 샌드박스 설정

환경은 세션이 Anthropic 관리 클라우드 샌드박스 또는 자체 인프라의 자체 호스팅 샌드박스 중 어디에서 실행될지 제어합니다. 빠른 시작의 클라우드 예시는 네트워크를 제한하고 패키지 관리자를 허용합니다:

YAML
# environment.yaml
name: document-review
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

다음으로 적용합니다 ant apply environment.yaml. ID도 claude-lock.json에 저장됩니다. 에이전트에 네트워크 액세스가 필요하면 allowed_hosts에 필요한 호스트만 나열합니다. 제한된 네트워크에서는 해당 호스트 목록이 Managed Agents의 웹 검색 및 가져오기 도구도 제한합니다. 패키지 관리자를 허용해도 웹사이트가 허용 목록에 추가되지는 않습니다.

첫 실행에는 민감하지 않은 작은 폴더와 필요한 도구만 사용하세요. 기본 에이전트 도구 모음에는 셸과 파일 작업이 포함됩니다. 도구를 더하면 에이전트가 할 수 있는 일이 늘어날 수 있습니다. 외부 시스템이나 자격 증명에 대한 액세스를 허용하기 전에 문서화된 권한 정책과 샌드박스 제어를 확인하세요.

4. 세션을 시작하고 범위가 정해진 작업 보내기

에이전트와 환경 ID를 사용해 Python SDK로 세션을 만듭니다:

Python
import anthropic

client = anthropic.Anthropic()
session = client.beta.sessions.create(
    agent="AGENT_ID_FROM_CLAUDE_LOCK",
    environment_id="ENVIRONMENT_ID_FROM_CLAUDE_LOCK",
    title="Small document review",
)
print(session.id)

두 ID 자리 표시자를 claude-lock.json에 있는 값으로 바꿉니다. 그런 다음 세션 이벤트 스트림으로 구체적인 작업을 보냅니다. 이벤트를 보내기 전에 스트림을 시작해야 실행과 진행 상황을 실시간으로 볼 수 있습니다:

Python
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": (
                    "Review each Markdown file in /review-set for a missing "
                    "owner, deadline, or acceptance criterion. Quote evidence; "
                    "do not infer missing details. Reconcile duplicate findings "
                    "and write /mnt/session/outputs/report.json plus "
                    "/mnt/session/outputs/summary.md. In report.json, use "
                    "a files array with one record per input: path, status "
                    "(reviewed or unresolved), and findings; each finding has "
                    "a check, evidence excerpt, and source location. Include "
                    "input, reviewed, and unresolved counts."
                ),
            }],
        }],
    )
    open_runs = {}
    run_results = {}
    for event in stream:
        if event.type == "workflow_run.created":
            open_runs[event.workflow_run_id] = event.name
            print(f"Run started: {event.name}")
        elif event.type == "workflow_run.status_ended":
            run_results[event.workflow_run_id] = event.result.type
            open_runs.pop(event.workflow_run_id, None)
            print(f"Run ended: {event.result.type}")
        elif event.type == "workflow_run.error":
            print(f"Run error: {event.error}")
        elif event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text)
        elif event.type == "session.status_idle":
            if event.stop_reason.type == "end_turn" and not open_runs:
                break

    # Inspect the child threads associated with completed workflow runs.
    for thread in client.beta.sessions.threads.list(session.id):
        if thread.workflow_run_id in run_results:
            print(f"Thread {thread.id}: {thread.status}")
            for thread_event in client.beta.sessions.threads.events.list(
                thread.id, session_id=session.id
            ):
                if thread_event.type == "session.error":
                    print(f"Thread error: {thread_event}")

이 예시는 구성한 세션 입력 방식이 파일을 /review-set에 노출한다고 가정합니다. 에이전트에 검토를 요청하기 전에 문서화된 입력 방식을 사용해 세션 샌드박스에 파일을 넣으세요. 출력은 에이전트가 /mnt/session/outputs/에 쓰도록 합니다. Managed Agents 파일 문서 에는 세션 범위 파일을 나열하고 다운로드하는 방법이 나와 있습니다. Python SDK에서 문서화된 읽기 결과 형태는 다음과 같습니다:

Python
files = client.beta.files.list(
    scope_id=session.id,
    betas=["managed-agents-2026-04-01"],
)
for report in files:
    if report.filename == "report.json":
        content = client.files.download(report.id)
        content.write_to_file("report.json")
        break

세션이 유휴 상태가 된 뒤 파일이 나타나기까지 몇 초 걸릴 수 있습니다. 파일이 없으면 잠시 기다린 후 다시 나열하세요. 안전한 첫 검토를 위해 예상 결과를 직접 확인할 수 있는 문서 몇 개로 시험 폴더를 만드세요. 예시 프롬프트는 검토 작업을 정의하지만 에이전트가 모든 문제를 찾는다고 보장하지 않습니다.

출력 계약은 감사할 수 있을 만큼 엄격해야 합니다. 예를 들면:

JSON
{
  "files": [
    {
      "path": "requirements.md",
      "status": "reviewed",
      "findings": [
        {
          "check": "deadline",
          "evidence_excerpt": "...",
          "source_location": "requirements.md, section 2"
        }
      ]
    }
  ],
  "input_count": 1,
  "reviewed_count": 1,
  "unresolved_count": 0
}

이는 워크플로에 권장하는 스키마이며 Anthropic이 제공한 스키마는 아닙니다. 해결되지 않았거나 읽을 수 없는 파일도 기록으로 남겨 결과 누락이 문제가 없는 검토처럼 보이지 않게 하세요.

5. 실행과 출력 확인

워크플로가 시작되면 이벤트 스트림은 workflow_run.created를 보고하고 실행 ID와 선언된 단계를 포함합니다. 예시는 각 실행 ID를 해당 workflow_run.status_ended가 올 때까지 열어 둡니다. 기본 세션이 유휴 상태라는 사실만으로 백그라운드 워크플로가 끝난 것은 아닙니다. 기본 스트림은 하위 스레드 상태를 요약하고 각 스레드의 이벤트 목록에는 메시지와 오류가 들어 있습니다. 예시는 workflow_run_id 를 기준으로 스레드를 나열하고 session.error 이벤트를 표시합니다. 재시도를 모두 소진했는지( retry_status.type == "exhausted"포함) 또는 다른 하위 오류가 있는지 확인하고 해당 파일을 미해결로 표시하세요.

‘완료됨’이라는 단어가 아니라 출력 파일을 산출물로 취급하세요. Anthropic은 스레드 작업이 실패하거나 스레드 생성에 실패해도 실행이 completed 로 끝날 수 있다고 명시적으로 경고합니다. report.json 를 열어 입력 파일마다 결과 또는 명시적인 미해결 상태가 있는지, 증거 발췌가 올바른 원본 파일을 가리키는지, 파일 수가 제공한 수와 일치하는지 확인하세요. 더 큰 자료 모음에 워크플로를 적용하기 전에 작은 시험 폴더를 예상 결과와 비교하세요.

클라이언트 연결이 끊기면 새 이벤트 스트림은 열린 뒤 발생한 이벤트만 보냅니다. 문서화된 이벤트 유형 필터와 페이지네이션을 사용해 이전 세션 이벤트를 나열하면서 실행 상태를 복원하세요. 하위 스레드가 계속 작업 중일 수 있으므로 기본 에이전트가 유휴 상태라고 실행이 끝났다고 추론하지 마세요. 관찰된 모든 실행이 끝나면 세션 범위 파일을 나열하고 문서화된 Files API로 /mnt/session/outputs/report.json 와 summary.md 를 다운로드합니다. 제공한 각 파일에 검토됨 또는 미해결 기록이 있는지, 건수가 맞는지 확인하세요. 예시 이벤트 루프는 보고서를 다운로드하거나 검증하지 않습니다.

설계를 바꾸는 한도

Anthropic의 현재 워크플로 실행 한도 문서에는 한 번의 실행에서 최대 64개 워크플로 스레드가 동시에 작업할 수 있다고 되어 있지만, API가 이 동시성을 보장하지 않으며 값이 바뀔 수 있다고도 설명합니다. 에이전트 1,000개 한도는 실행 전체 기간 동안 시작된 에이전트 수를 셉니다. 동시 스레드 수가 아닙니다. 이 한도에 도달한 뒤 워크플로가 다른 에이전트를 시작하려 하면 실행이 thread_limit_error로 끝납니다. 실패한 에이전트를 재시도하면 스레드가 추가로 만들어질 수 있습니다.

실행은 기본적으로 24시간 지속되며, 에이전트가 더 짧은 수명을 설정하면 그보다 짧습니다. 클라이언트가 기다리는 시간도 계산되며 일시 중지된 실행도 시간 초과될 수 있습니다. 세션은 기본적으로 유휴 실행을 포함해 10개의 실행을 열어 둘 수 있습니다. 세션 사용량 예산은 모든 워크플로 에이전트에 적용됩니다. 예산에 도달하면 예산을 올리거나 제거할 때까지 열린 실행이 일시 중지됩니다. 작은 작업 단위를 계획하고 파일에 체크포인트를 저장하며, 조정 단계에서 검토하지 않은 항목을 완료한 것처럼 다루지 말고 미완료로 보고하게 하세요.

실패가 발생하면 workflow_run.error 와 해당 스레드를 확인하세요. program_error 는 워크플로 코드 또는 하위 스레드의 실패를 의미할 수 있습니다. thread_limit_error 는 에이전트 1,000개 상한을 가리키고 timeout_error 는 실행 수명 한도를 가리킵니다. 실행이 세션 예산에 도달하면 예산을 높이거나 제거해 재개하세요. 워크플로를 중지해야 한다면 기본 에이전트에 실행 중지를 요청하세요. 세션 턴을 중단하는 것 자체는 실행 취소 명령이 아닙니다.

비용

Anthropic의 가격 문서 에 따르면 Managed Agents 모델 토큰은 선택한 모델 요율로, 세션 런타임은 실행 중인 세션 시간당 $0.08로 청구됩니다. 세션 상태가 running일 때 런타임이 누적됩니다. 유휴, 재예약, 종료 시간은 계산되지 않습니다. 워크플로 실행 자체의 별도 요금은 없지만 스레드의 토큰 사용량은 세션 비용에 포함됩니다. 세션 내 웹 검색은 검색 1,000회당 $10로 표시됩니다. 정확한 총액은 모델, 입력·출력 토큰, 도구, 세션 실행 시간에 따라 달라집니다. 에이전트 1,000개 한도만으로 추정하지 말고 Console에서 사용량을 확인하세요.

실용적인 설정은 파일 몇 개로 시작해 워크플로 출력이 각 파일을 다루는지 확인하고, 실패한 스레드를 살펴본 다음, 검토 정책과 비용이 적절할 때만 입력을 늘리는 것입니다. 관리형 워크플로는 비동기 병렬 작업을 조정하는 방법을 제공하지만 결과의 정확성을 인증하지는 않습니다.

가장 큰 변화

10월 9일부터 Managed Agents 에이전트는 서버가 여러 에이전트 스레드와 단계에 걸쳐 실행하는 워크플로 프로그램을 작성할 수 있습니다. 개발자는 기본 세션에서 진행 상황을 확인하면서 범위가 정해지고 감사 가능한 분산 작업에 이 방식을 사용할 수 있습니다. 기능은 여전히 베타이며 공개된 한도는 모든 실행이 최대 동시성에 도달하거나 정확한 결과를 낸다고 보장하지 않습니다.

출처 및 추가 읽을거리