Claude Agent SDK 가이드: 동적 멀티에이전트 워크플로우

InYourLeague 리서치 · 2026-08-30

Answer in brief

claude-agent-sdk는 JavaScript 동적 워크플로우를 시작해 깨끗한 컨텍스트를 가진 서브에이전트를 병렬 팬아웃, 단계형 파이프라인, 모델 라우팅, 코드로 강제된 검증 구조로 조율할 수 있습니다. 완료 여부는 생성된 스크립트와 실행 진행 상황뿐 아니라 단계별 출력, 검증 결과, 명시적인 수용 기준을 함께 확인해야 입증할 수 있습니다.

Key facts at a glance

Failure modes and verification

FAQ

단일 에이전트 대신 동적 워크플로우를 선택해야 하는 경우는 언제입니까?

단일 대화로 조율하기 어려운 규모이거나, 독립적으로 처리할 항목이 많거나, 코드로 검증 실행을 강제해야 하거나, 오케스트레이션을 저장해 다시 실행할 가치가 있을 때 적합합니다. 대신 토큰 사용량이 크게 늘어날 수 있습니다.

서브에이전트는 서로 완전히 격리됩니까?

각 서브에이전트는 깨끗한 컨텍스트로 시작하고 스크립트가 제공한 프롬프트만 받습니다. 그러나 세션의 작업 디렉터리에서 작업하고 구성된 도구 허용 목록을 따르므로, 공식 근거가 설명하는 격리는 컨텍스트 격리이며 에이전트별 별도 파일시스템을 의미하지 않습니다.

하나의 워크플로우에서 병렬 단계와 파이프라인 단계를 함께 사용할 수 있습니까?

가능합니다. JavaScript 오케스트레이션 스크립트는 독립 서브에이전트를 동시에 실행하고 출력을 변수에 저장한 다음, 선택된 결과를 후속 필터링, 판단, 종합 또는 적대적 검증 단계에 전달할 수 있습니다.

서브에이전트의 모델은 어떻게 배정됩니까?

서브에이전트는 기본적으로 세션 모델을 사용합니다. 워크플로우 프롬프트로 특정 단계의 라우팅을 다르게 유도할 수 있고, CLAUDE_CODE_SUBAGENT_MODEL로 모든 서브에이전트의 모델을 재정의할 수 있습니다. 제공된 근거에는 지원 모델의 전체 목록이 없습니다.

워크플로우가 올바르게 완료되었다는 증거는 무엇입니까?

생성된 스크립트, 실행 진행 상황, 항목별·단계별 출력, 검증 결과, 실패 내역, 명시적인 수용 기준과의 최종 비교를 함께 검토해야 합니다. 실행 시작 이벤트만으로는 모든 항목과 필수 검증 단계가 결과를 생성했다는 점을 입증할 수 없습니다.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-30

Extended guide

직접 답변

claude-agent-sdk의 동적 워크플로우는 독립적으로 처리할 항목이 많거나, 단일 대화로 원활히 조율하기 어려운 규모이거나, 검증 단계를 반드시 실행하도록 구조적으로 강제해야 할 때 적합합니다. Claude는 작업에 맞는 JavaScript 오케스트레이션 스크립트를 작성해 Workflow 도구에 전달합니다. 런타임은 이 스크립트를 백그라운드에서 실행하며, Python 애플리케이션은 Agent SDK를 통해 워크플로우를 시작하고 진행 상황을 스트리밍할 수 있습니다. 공식 동적 워크플로우 쿡북은 병렬 검증자와 회의론자 서브에이전트로 보고서를 사실 확인하는 예제를 통해 이 구조를 설명합니다.

실행 방식과 격리 범위

각 서브에이전트는 완전한 Claude Code 에이전트이며, 깨끗한 컨텍스트로 시작합니다. 에이전트가 받는 지시는 오케스트레이션 스크립트가 전달한 프롬프트로 제한됩니다. 다만 각 에이전트는 세션의 작업 디렉터리에서 작업하며, 사용자가 구성한 도구 허용 목록을 따릅니다. 따라서 공식 근거가 설명하는 격리는 컨텍스트 격리입니다. 제공된 근거만으로 서브에이전트마다 별도의 파일시스템이 만들어진다고 판단해서는 안 됩니다.

스크립트는 서브에이전트의 출력을 변수에 보관하고, 일반적인 JavaScript 코드로 필터링, 반복, 결과 연결, 후속 처리, 검증 단계를 수행할 수 있습니다. 이 방식으로 다음 세 가지 구성을 함께 사용할 수 있습니다.

• 병렬 팬아웃은 서로 의존하지 않는 항목을 여러 서브에이전트에 나눠 동시에 처리합니다.
• 단계형 파이프라인은 앞 단계의 결과를 후속 추출, 판단, 필터링, 종합 단계의 입력으로 전달합니다.
• 적대적 검증은 앞선 결과를 검증자 또는 회의론자 역할의 에이전트가 다시 검토하도록 해, 리뷰를 선택 사항으로 남기지 않습니다.

런타임은 최대 16개 에이전트를 동시에 실행할 수 있습니다. CPU 코어가 제한된 시스템에서는 실제 동시 실행 수가 더 적을 수 있습니다. 단일 워크플로우 실행에는 최대 1,000개 에이전트라는 상한이 있습니다. 계획된 작업이 동시 실행 한도를 넘으면, 남은 작업은 실행 슬롯이 생길 때까지 대기열에 들어갑니다. 따라서 대규모 팬아웃을 설계할 때는 전체 작업 수와 동시에 실행되는 작업 수를 구분해야 합니다.

권장 구현 순서

1. 입력 항목, 기대 출력, 수용 기준을 먼저 정의합니다. 독립적으로 처리할 수 있는 항목과 앞 단계의 결과에 의존하는 항목을 구분하고, 누락이나 실패를 어떻게 판정할지도 정합니다.
2. 사람이 검토하기 쉬운 JavaScript 오케스트레이션 스크립트를 작성하도록 요청합니다. 병렬 팬아웃, 결과 수집, 필터링, 후속 단계, 필수 검증이 코드에 명시적으로 드러나야 합니다.
3. Python에서 query()와 ClaudeAgentOptions를 사용해 워크플로우를 시작합니다. 쿡북이 제시하는 요구 사항은 Python 3.11 이상과 Claude Code CLI v2.1.154 이상입니다. claude-agent-sdk 0.2.90 이상은 호환되는 CLI를 번들로 제공합니다.
4. 실행 중 진행 상황을 스트리밍하고, 생성된 스크립트와 필요한 단계별 출력을 보존합니다. 스크립트는 읽고 검토하거나 편집하고 저장한 뒤 다시 실행할 수 있으므로, 오케스트레이션 자체가 재사용 가능한 산출물이 됩니다.
5. 최종 결과를 처음 정의한 입력 목록과 수용 기준에 대조합니다. 사실 확인 작업이라면 모든 주장이 처리되었는지, 누락되거나 실패한 항목이 있는지, 검증자 또는 회의론자 단계가 실제 결과를 생성했는지 확인합니다.

모델 라우팅

서브에이전트는 기본적으로 세션 모델을 사용합니다. 워크플로우는 특정 단계를 다른 모델로 라우팅할 수 있으므로, 기계적인 추출과 어려운 판단에 서로 다른 라우팅 전략을 적용할 수 있습니다. 이러한 라우팅은 프롬프트를 통해 유도할 수 있으며, CLAUDE_CODE_SUBAGENT_MODEL 환경 변수는 해당 실행의 모든 서브에이전트 모델을 한꺼번에 재정의합니다. 제공된 근거는 이와 같은 라우팅 방식은 설명하지만, 지원되는 모델의 전체 목록을 제시하지는 않습니다. 따라서 이 근거만으로 특정 모델 ID의 선택 가능 여부나 공식 지원 여부를 확정해서는 안 됩니다.

완료 증거 체크리스트

• 생성된 JavaScript 오케스트레이션 스크립트를 직접 검토할 수 있습니다.
• 모든 입력 항목이 실행, 대기 또는 명시적인 실패 상태 중 하나로 확인됩니다.
• 필요한 파이프라인 단계와 검증 단계가 스크립트에 포함되어 있습니다.
• 실행 진행 상황과 단계별 출력이 수집되었습니다.
• 검증 단계가 요청에만 머물지 않고 실제 결과를 생성했습니다.
• 최종 출력이 명시적인 수용 기준과 비교되었습니다.
• 다수의 서브에이전트가 단일 에이전트보다 훨씬 많은 토큰을 사용할 수 있다는 비용 특성을 검토했습니다.

워크플로우가 시작되었다는 이벤트만으로는 완료를 입증할 수 없습니다. 신뢰할 수 있는 완료 증거는 사람이 검토할 수 있는 실행 계획, 런타임 기록, 단계별 결과, 최종 판정을 서로 연결해야 합니다. 동적 워크플로우는 일관된 처리, 강제된 검증, 재실행 가능한 오케스트레이션의 가치가 추가 토큰 비용보다 클 때 선택하는 것이 타당합니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.