--- title: 멀티에이전트 오케스트레이션 url: https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration description: 단일 세션 내에서 여러 에이전트를 조율합니다. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- "Multiagent orchestration"(멀티에이전트 오케스트레이션)을 사용하면 하나의 에이전트가 다른 에이전트들과 협력하여 복잡한 작업을 완료할 수 있습니다. 에이전트들은 각자 격리된 컨텍스트를 가지고 병렬로 동작할 수 있으며, 이는 출력 품질을 향상시키는 데 도움이 되고 완료 시간도 단축할 수 있습니다. 멀티에이전트 구성이 여러분의 문제에 적합한지 확신이 서지 않으시나요? [멀티에이전트 시스템을 사용해야 할 때(그리고 사용하지 말아야 할 때)](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them)를 참조하세요. ## 다른 에이전트에게 작업 넘기기 세션이 실행하는 에이전트는 두 가지 방식으로 다른 에이전트에게 작업을 넘길 수 있습니다. **Subagents**(서브에이전트)를 사용하면 에이전트가 직접 작업을 위임하고 각 서브에이전트가 보고하는 내용을 읽습니다. **Dynamic workflows**(동적 워크플로)를 사용하면 에이전트가 워크플로, 즉 백그라운드에서 여러 에이전트를 실행하고 그 결과를 결합하는 프로그램을 작성합니다. 또한 에이전트는 작업을 직접 수행하면서 지침을 얻기 위해 **advisor**(어드바이저) 모델에 자문을 구할 수도 있습니다. 에이전트가 이 중 무엇을 사용할 수 있는지는 사용자가 결정하고, 언제 사용할지는 에이전트가 결정합니다. 이 선택을 안내하려면 에이전트의 시스템 프롬프트에서 언제 워크플로 실행을 사용해야 하는지 알려 주세요. [실행을 사용할 시점을 에이전트에 알려주기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run)를 참조하세요. 또한 에이전트가 사용자가 나열한 에이전트만 사용하도록 제한할 수도 있습니다. 서브에이전트를 사용하면 다음에 무슨 일이 일어날지는 에이전트 자체가 결정합니다. [서브에이전트의 스레드](https://platform.claude.com/docs/ko/managed-agents/session-threads)는 사용자가 보관할 때까지 계속 사용할 수 있으므로, 에이전트는 후속 메시지를 보낼 수 있습니다. 동적 워크플로를 사용하면 Claude는 Claude의 직접적인 개입 없이 에이전트를 오케스트레이션하는 프로그램을 작성합니다. 컨텍스트와 결과는 한 에이전트에서 다른 에이전트로 프로그래밍 방식으로 전달되므로, 기본 세션 스레드는 사용자와 소통하고 실행 중인 하나 또는 여러 워크플로를 확인하여 진행 상황을 보고하는 데 집중할 수 있습니다. 에이전트는 실행의 스레드에 후속 메시지를 보낼 수 없으며, 서버는 늦어도 실행이 끝나는 시점에는 각 스레드를 보관합니다. | 접근 방식 | 동작 방식 | 사용 시점 | 고려 사항 | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [서브에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#delegate-to-subagents) | 에이전트가 서브에이전트에게 작업을 위임합니다. 각 서브에이전트는 자체 [세션 스레드](https://platform.claude.com/docs/ko/managed-agents/session-threads)에서 작업하며, 이 스레드를 나열하고 스트리밍할 수 있습니다. | 에이전트가 서브에이전트의 보고 후 후속 조치를 해야 하거나, 자체 시스템 프롬프트와 도구를 갖춘, 사용자가 나열한 전문 에이전트가 필요한 경우. | 위임은 한 단계 깊이로만 가능하며, 세션은 유휴 스레드를 포함하여 한 번에 최대 25개의 하위 스레드를 가질 수 있습니다. 어드바이저 스레드와 워크플로 실행의 스레드는 포함되지 않습니다. | | [동적 워크플로](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#dynamic-workflows) | 에이전트가 워크플로, 즉 여러 에이전트를 단계별로 실행하고 그 결과를 결합하는 프로그램을 작성합니다. 서버는 이를 하나의 워크플로 실행으로 백그라운드에서 실행하며, 사용자는 이를 추적할 수 있습니다. 워크플로는 에이전트를 정의하거나 사용자가 제공한 목록에서 선택합니다. | 둘 이상의 에이전트가 필요한 대부분의 작업: 여러 부분으로 구성된 작업, 병렬 작업, 또는 더 빨리 끝나야 하는 긴 작업. 감사, 마이그레이션, 심층 리서치, 교차 검증 등이 그 예입니다. | 실행의 모든 에이전트가 토큰을 사용하므로, 실행을 포함한 세션의 지출을 제한하려면 [세션 예산](https://platform.claude.com/docs/ko/managed-agents/budgets)을 설정하세요. 에이전트의 시스템 프롬프트에서 언제 실행을 사용해야 하는지 알려 주세요. 실행은 단계별로 추적할 수 있으며 각 스레드를 읽을 수 있습니다. | | [세션에 어드바이저 제공하기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#give-the-session-an-advisor) | 세션의 [기본 스레드](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#how-it-works)가 턴 도중에 접근 방식 계획이나 작업 검토 등의 지침을 얻기 위해 어드바이저 모델에 자문을 구하고, 작업은 계속 직접 수행합니다. | 하나의 에이전트가 작업을 수행하되, 계획이나 최종 검토 같은 핵심 시점에 어드바이저 모델의 판단이 필요한 경우. | 기본 스레드만 어드바이저에 자문을 구할 수 있으며, 자문은 어드바이저 모델의 요금으로 청구됩니다. | 이러한 기능은 에이전트 정의의 `multiagent` 블록에서 설정하며, 이 블록에는 `type`이 있습니다. `multiagent_20261001` 유형을 사용하면 에이전트가 세 가지를 모두 함께 사용할 수 있으며, 각각을 켜거나 끌 수 있습니다. 기본적으로 `subagents`와 `workflows`는 모두 활성화되어 있습니다. `subagents`와 `workflows`에는 각각 [에이전트나 워크플로가 직접 정의하는 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)에 대한 설정인 `inline_agents`가 활성화되어 있습니다: ```json { "multiagent": { "type": "multiagent_20261001" } } ``` 에이전트가 호출할 수 있는 에이전트를 설정하려면 [사전 정의 에이전트와 인라인 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)를 참조하세요. 설정을 끄려면 [동적 워크플로 켜기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)를 참조하세요. ## 사전 정의 에이전트와 인라인 에이전트 모든 서브에이전트와 워크플로 실행의 모든 에이전트는 다음 두 종류 중 하나입니다: * **사전 정의 에이전트:** 이미 [생성](https://platform.claude.com/docs/ko/managed-agents/agent-setup)했으며 `multiagent` (csharp, go: `Multiagent`) 블록에 나열한 에이전트입니다. 모델, 시스템 프롬프트, 도구, MCP 서버, 스킬 등 자체 구성을 사용합니다. * **인라인 에이전트:** 저장되지 않은 에이전트입니다. 세션이 실행하는 에이전트 또는 워크플로가 작업을 배분할 때 정의합니다. 해당 에이전트의 모델, 도구, MCP 서버, 스킬을 사용합니다. 두 종류 모두 `subagents`와 `workflows`에서 작동합니다: | 에이전트 종류 | `subagents`에서 | `workflows`에서 | | ------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | | 사전 정의 | 에이전트는 `subagents.predefined_agents`에 나열한 에이전트에게 위임할 수 있습니다. | 워크플로는 `workflows.predefined_agents`에 나열한 에이전트를 사용할 수 있습니다. | | 인라인 | 에이전트는 위임할 때 인라인 에이전트를 정의할 수 있습니다. `subagents.inline_agents`로 이를 켜거나 끕니다. | 워크플로는 인라인 에이전트를 정의할 수 있으며, 각각에 대한 시스템 프롬프트를 작성합니다. `workflows.inline_agents`로 이를 켜거나 끕니다. | `subagents.predefined_agents`와 `workflows.predefined_agents`는 별개의 두 목록입니다. 한 목록에 있는 에이전트는 다른 목록에 추가되지 않습니다. 두 목록 모두 기본적으로 비어 있습니다. 각 목록의 항목은 다음 형식 중 하나를 취합니다: * `{"type": "agent", "id": agent.id}`는 이전에 생성된 `agent`를 ID로 참조합니다. `version`을 지정하지 않으면, 이를 나열하는 에이전트가 생성될 때 또는 업데이트가 목록을 전송할 때 참조가 해당 에이전트의 최신 버전으로 고정됩니다. * `{"type": "agent", "id": agent.id, "version": agent.version}`은 특정 에이전트 버전을 고정합니다. * 문자열로 된 `agent.id`만 사용하면 `{"type": "agent", "id": agent.id}`의 축약형입니다. * `{"type": "self"}`는 에이전트 자신을 나열하여 그 복사본이 작업을 수행할 수 있게 합니다. 세션이 [에이전트 구성 재정의](https://platform.claude.com/docs/ko/managed-agents/sessions#override-agent-configuration-for-a-session)와 함께 생성된 경우, 해당 재정의는 이러한 복사본에도 적용됩니다. ID로 참조된 항목은 영향을 받지 않습니다. 이러한 항목과 항목이 지정하는 에이전트에 대한 규칙은 두 목록 모두에 적용됩니다. [서브에이전트 나열하기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#list-the-subagents)를 참조하세요. 인라인 에이전트는 두 설정 모두에서 기본적으로 켜져 있습니다. 나열한 에이전트만 허용하려면 `subagents`, `workflows` 또는 둘 다에서 `inline_agents`를 `{"type": "disabled"}`로 설정하세요. 인라인 에이전트가 꺼진 설정에는 `predefined_agents` 목록에 최소 하나의 에이전트가 필요합니다. 목록이 비어 있으면 요청이 400 오류로 실패합니다. 업데이트 시 서버는 업데이트 후의 설정 상태를 확인합니다. 다음 에이전트는 자신이 나열한 에이전트만 허용합니다. 하나의 에이전트와 자신의 복사본에게 위임할 수 있으며, 워크플로는 다른 에이전트의 버전 2를 사용할 수 있습니다: ```json { "multiagent": { "type": "multiagent_20261001", "subagents": { "type": "enabled", "inline_agents": { "type": "disabled" }, "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }] }, "workflows": { "type": "enabled", "inline_agents": { "type": "disabled" }, "predefined_agents": [ { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 } ] } } } ``` ## 서브에이전트에 위임하기 ### 위임할 작업 멀티에이전트 조정은 다양한 영역에 걸친 작업이 필요하거나, 범위가 잘 정의된 여러 작업이 전체 목표에 기여하는 복잡한 작업에 가장 적합합니다. 잘 작동하는 패턴: * **병렬화:** 독립적인 하위 작업(여러 소스 검색, 개별 파일 분석)을 동시에 분산하고 에이전트가 결과를 종합하도록 합니다. * **전문화:** 하나의 에이전트에 모든 기능을 부여하는 대신, 보안 에이전트나 문서화 에이전트처럼 도메인에 특화된 시스템 프롬프트와 도구를 갖춘 에이전트로 라우팅합니다. * **에스컬레이션:** 복잡한 하위 작업 일부에 대해 더 유능한 에이전트나 모델에 자문을 구합니다. 모델에 자문을 구하려면 [세션에 어드바이저를 제공하세요](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#give-the-session-an-advisor). ### 작동 방식 모든 에이전트는 동일한 샌드박스, 파일 시스템, [vault 자격 증명](https://platform.claude.com/docs/ko/managed-agents/vaults)을 공유하지만, 각 에이전트는 자체 대화 기록을 가진 컨텍스트 격리 이벤트 스트림인 자체 **세션 스레드**에서 실행됩니다. 세션이 실행하는 에이전트는 세션 수준의 [이벤트 스트림](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming)인 **기본 스레드**에서 활동을 보고합니다. 추가 스레드는 에이전트가 작업을 위임할 때 런타임에 생성됩니다. 워크플로 실행도 스레드를 생성합니다. 서브에이전트의 스레드는 지속됩니다. 에이전트는 이전에 호출한 서브에이전트에게 후속 메시지를 보낼 수 있으며, 해당 서브에이전트는 이전 턴의 모든 내용을 유지합니다. 서브에이전트가 사용하는 구성은 그것이 [사전 정의 에이전트인지 인라인 에이전트인지](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)에 따라 달라집니다. 세션 수준의 [에이전트 구성 재정의](https://platform.claude.com/docs/ko/managed-agents/sessions#override-agent-configuration-for-a-session)는 세션이 실행하는 에이전트와 그 `self` 복사본에 적용됩니다. 각 에이전트는 자체 대화 기록을 유지합니다. ### 서브에이전트 나열하기 [에이전트를 정의](https://platform.claude.com/docs/ko/managed-agents/agent-setup)할 때, `multiagent` (csharp, go: `Multiagent`) 블록에서 `subagents` (csharp, go: `Subagents`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록을 설정하여 에이전트가 위임할 수 있는 에이전트를 나열하세요: ```bash cURL curl -fsS https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "Engineering Lead", "model": "claude-opus-5-5", "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": "multiagent_20261001", "subagents": { "type": "enabled", "predefined_agents": [ {"type": "agent", "id": "'"$REVIEWER_AGENT_ID"'"}, {"type": "agent", "id": "'"$TEST_WRITER_AGENT_ID"'"} ] } } }' ``` ```bash CLI ant apply engineering-lead.md reviewer.md test-writer.md ``` ```markdown --- name: Engineering Lead model: claude-opus-5-5 tools: - type: agent_toolset_20260401 multiagent: type: multiagent_20261001 subagents: type: enabled predefined_agents: # ant apply replaces each path with {type: agent, id, version} - ./reviewer.md - ./test-writer.md --- You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent. ``` ```markdown --- name: reviewer model: claude-haiku-5-5 --- You are a code reviewer. ``` ```markdown --- name: test-writer model: claude-haiku-5-5 --- You write unit tests. ``` ```python Python lead_agent = client.beta.agents.create( name="Engineering Lead", model="claude-opus-5-5", 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": "multiagent_20261001", "subagents": { "type": "enabled", "predefined_agents": [ {"type": "agent", "id": reviewer_agent.id}, {"type": "agent", "id": test_writer_agent.id}, ], }, }, ) ``` ```typescript TypeScript const leadAgent = await client.beta.agents.create({ name: "Engineering Lead", model: "claude-opus-5-5", 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: "multiagent_20261001", subagents: { type: "enabled", predefined_agents: [ { type: "agent", id: reviewerAgent.id }, { type: "agent", id: testWriterAgent.id } ] } } }); ``` ```csharp C# var leadAgent = await client.Beta.Agents.Create(new() { Name = "Engineering Lead", Model = BetaManagedAgentsModel.ClaudeOpus5_5, System = "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.", Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, }, ], Multiagent = new BetaManagedAgentsMultiagent20261001Params { Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams { PredefinedAgents = [reviewerAgent.ID, testWriterAgent.ID], }, }, }); ``` ```go Go leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Engineering Lead", Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5}, System: anthropic.String("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent."), Tools: []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }}, Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{ OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{ Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{ OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{ PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{ {OfString: anthropic.String(reviewerAgent.ID)}, {OfString: anthropic.String(testWriterAgent.ID)}, }, }, }, }, }, }) if err != nil { panic(err) } ``` ```java Java var leadAgent = client.beta().agents().create( AgentCreateParams.builder() .name("Engineering Lead") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .system("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.") .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .multiagent(BetaManagedAgentsMultiagent20261001Params.builder() .subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder() .addPredefinedAgent(BetaManagedAgentsAgentParams.builder() .type(BetaManagedAgentsAgentParams.Type.AGENT) .id(reviewerAgent.id()) .build()) .addPredefinedAgent(BetaManagedAgentsAgentParams.builder() .type(BetaManagedAgentsAgentParams.Type.AGENT) .id(testWriterAgent.id()) .build()) .build()) .build()) .build() ); ``` ```php PHP $leadAgent = $client->beta->agents->create( name: 'Engineering Lead', model: 'claude-opus-5-5', 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' => 'multiagent_20261001', 'subagents' => [ 'type' => 'enabled', 'predefined_agents' => [ ['type' => 'agent', 'id' => $reviewerAgent->id], ['type' => 'agent', 'id' => $testWriterAgent->id], ], ], ], ); ``` ```ruby Ruby lead_agent = client.beta.agents.create( name: "Engineering Lead", model: "claude-opus-5-5", 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: "multiagent_20261001", subagents: { type: "enabled", predefined_agents: [ {type: "agent", id: reviewer_agent.id}, {type: "agent", id: test_writer_agent.id} ] } } ) ``` 인라인 에이전트를 끄지 않는 한 에이전트는 인라인 에이전트에게도 위임할 수 있습니다. 해당 설정과 `subagents` (csharp, go: `Subagents`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록 항목이 취하는 형식에 대해서는 [사전 정의 에이전트와 인라인 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)를 참조하세요. `"advisor": {"type": "enabled", "model": ""}`는 세션의 기본 스레드에 턴 도중 자문할 수 있는 어드바이저를 제공합니다. 어드바이저는 이 목록의 항목이 아니라 `multiagent` (csharp, go: `Multiagent`) 블록의 설정입니다. [세션에 어드바이저 제공하기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#give-the-session-an-advisor)를 참조하세요. 이 유형에서는 동적 워크플로도 기본적으로 활성화되어 있으므로, 이 에이전트는 백그라운드에서 여러 에이전트를 실행하는 대규모 작업을 계획할 수 있습니다. 이를 끄거나 워크플로가 사용할 수 있는 에이전트를 나열하려면 [동적 워크플로 켜기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)를 참조하세요. 다음 규칙은 `subagents` (csharp, go: `Subagents`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열한 에이전트와 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열한 에이전트 모두에 적용됩니다: * **고정:** `subagents` (csharp, go: `Subagents`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록을 포함한 에이전트의 구성은 에이전트가 생성되거나 업데이트될 때 스냅샷으로 저장됩니다. 참조된 에이전트는 그 시점에 확인된 버전으로 고정된 상태를 유지하며, 이후 정의가 업데이트되어도 반영되지 않습니다. 목록을 전송하지 않는 업데이트는 이미 고정된 버전을 유지합니다. 참조된 에이전트의 최신 버전에 위임하려면 `subagents` (csharp, go: `Subagents`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록이 해당 버전을 참조하도록 [에이전트를 업데이트](https://platform.claude.com/docs/ko/managed-agents/agent-setup#update-an-agent)하세요. * **한 단계:** 에이전트는 한 단계의 에이전트에게만 위임할 수 있습니다. `multiagent` (csharp, go: `Multiagent`)가 설정된 다른 에이전트를 참조하면 생성 또는 업데이트 요청이 400 유효성 검사 오류로 실패합니다. * **최대 20개 에이전트:** `subagents` (csharp, go: `Subagents`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에는 최대 20개의 고유한 에이전트를 나열할 수 있습니다. 이 제한은 목록별로 적용됩니다. `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에도 최대 20개를 나열할 수 있습니다. 에이전트는 세션의 [스레드 제한](https://platform.claude.com/docs/ko/managed-agents/session-threads) 내에서 각 서브에이전트의 여러 복사본을 호출할 수 있습니다. * **추론 지역:** 에이전트와 `subagents` (csharp, go: `Subagents`) 또는 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열한 모든 에이전트는 동일한 [추론 지역](https://platform.claude.com/docs/ko/manage-claude/data-residency)([에이전트 정의](https://platform.claude.com/docs/ko/managed-agents/agent-setup)의 `model` (csharp, go: `Model`)에 있는 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`))을 고정하거나, 모두 고정하지 않아야 합니다. 어느 목록에서든 불일치가 있으면 400 유효성 검사 오류로 거부됩니다. 이 검사는 에이전트가 저장될 때와 [세션 생성 재정의](https://platform.claude.com/docs/ko/managed-agents/sessions#override-agent-configuration-for-a-session)가 고정 값을 변경할 때 모두 실행됩니다. ### 세션 생성하기 에이전트를 참조하는 세션을 생성하세요. 에이전트는 필요에 따라 `subagents` (csharp, go: `Subagents`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열한 에이전트에게 위임합니다. 인라인 에이전트를 끄지 않는 한 [인라인 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)에게도 위임할 수 있습니다. ```bash cURL curl -fsSL https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$LEAD_AGENT_ID"'", "environment_id": "'"$ENVIRONMENT_ID"'" }' ``` ```bash CLI ant beta:sessions create \ --agent "$LEAD_AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" ``` ```python Python session = client.beta.sessions.create( agent=lead_agent.id, environment_id=environment.id, ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: leadAgent.id, environment_id: environment.id }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = leadAgent.ID, EnvironmentID = environment.ID, }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{ OfString: anthropic.String(leadAgent.ID), }, EnvironmentID: environment.ID, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create(SessionCreateParams.builder() .agent(leadAgent.id()) .environmentId(environment.id()) .build()); ``` ```php PHP $session = $client->beta->sessions->create( agent: $leadAgent->id, environmentID: $environment->id, ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: lead_agent.id, environment_id: environment.id ) ``` ### 에이전트를 MCP 서버에 연결하기 MCP 서버는 에이전트 범위입니다. 각 에이전트 정의는 자체 서버와 도구를 선언합니다. 인라인 에이전트에는 에이전트 정의가 없으므로, 세션이 실행하는 에이전트의 MCP 서버와 도구를 사용합니다. Vault 자격 증명은 세션 범위입니다. 세션 생성 시 전달된 `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`)는 모든 스레드에 적용됩니다. 통합 시 고려해야 할 두 가지 사항은 다음과 같습니다: * MCP 서버를 인증하려면 모든 에이전트에서 사용되는 모든 MCP 서버에 대한 vault 자격 증명을 포함하세요. * 에이전트의 접근을 제한하려면 에이전트 정의에 필요한 서버만 선언하세요. 인라인 에이전트는 이 방식으로 제한할 수 없습니다. 나열한 에이전트만 허용하려면 `subagents` (csharp, go: `Subagents`)와 `workflows` (csharp, go: `Workflows`) 모두에서 `inline_agents` (java, php: `inlineAgents`; csharp, go: `InlineAgents`)를 비활성화하고, 각각에 최소 하나의 에이전트를 나열하세요. [사전 정의 에이전트와 인라인 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)를 참조하세요. 세션 생성 시 [에이전트 구성 재정의](https://platform.claude.com/docs/ko/managed-agents/sessions#override-agent-configuration-for-a-session)를 사용하면 세션이 실행하는 에이전트와 그 `self` 복사본의 MCP 서버를 대체할 수 있습니다. `limited` [환경](https://platform.claude.com/docs/ko/managed-agents/environments#networking)에서는 에이전트 또는 `subagents` (csharp, go: `Subagents`)나 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열한 에이전트가 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`)에 없는 호스트의 MCP 서버를 선언하면 세션 생성이 400 오류로 실패합니다. 환경의 네트워킹에서 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`)를 `true`로 설정하면 이 검사가 꺼집니다. GitHub MCP 서버를 선언하는 researcher와 researcher에게 위임하는 에이전트를 생성하세요: ```bash cURL # Create the researcher curl --fail-with-body -sS https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "researcher", "model": "claude-haiku-5-5", "mcp_servers": [{"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"}], "tools": [{"type": "mcp_toolset", "mcp_server_name": "github"}] }' # Create the agent that delegates to it: research_agent_id is the id from the first response curl --fail-with-body -sS https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "lead", "model": "claude-opus-5-5", "tools": [{"type": "agent_toolset_20260401"}], "multiagent": { "type": "multiagent_20261001", "subagents": { "type": "enabled", "predefined_agents": [{"type": "agent", "id": "'"$research_agent_id"'"}] } } }' ``` ```bash CLI ant apply lead.md researcher.md ``` ```markdown --- name: lead model: claude-opus-5-5 tools: - type: agent_toolset_20260401 multiagent: type: multiagent_20261001 subagents: type: enabled predefined_agents: # ant apply replaces each path with {type: agent, id, version} - ./researcher.md --- ``` ```markdown --- name: researcher model: claude-haiku-5-5 mcp_servers: - type: url name: github url: https://api.githubcopilot.com/mcp/ tools: - type: mcp_toolset mcp_server_name: github --- ``` ```python Python research_agent = client.beta.agents.create( name="researcher", model="claude-haiku-5-5", mcp_servers=[ {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"}, ], tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}], ) lead_agent = client.beta.agents.create( name="lead", model="claude-opus-5-5", tools=[{"type": "agent_toolset_20260401"}], multiagent={ "type": "multiagent_20261001", "subagents": { "type": "enabled", "predefined_agents": [{"type": "agent", "id": research_agent.id}], }, }, ) ``` ```typescript TypeScript const researchAgent = await client.beta.agents.create({ name: "researcher", model: "claude-haiku-5-5", mcp_servers: [{ type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/" }], tools: [{ type: "mcp_toolset", mcp_server_name: "github" }] }); const leadAgent = await client.beta.agents.create({ name: "lead", model: "claude-opus-5-5", tools: [{ type: "agent_toolset_20260401" }], multiagent: { type: "multiagent_20261001", subagents: { type: "enabled", predefined_agents: [{ type: "agent", id: researchAgent.id }] } } }); ``` ```csharp C# var researchAgent = await client.Beta.Agents.Create(new() { Name = "researcher", Model = BetaManagedAgentsModel.ClaudeHaiku5_5, McpServers = [ new() { Type = BetaManagedAgentsUrlMcpServerParamsType.Url, Name = "github", Url = "https://api.githubcopilot.com/mcp/", }, ], Tools = [ new BetaManagedAgentsMcpToolsetParams { Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset, McpServerName = "github", }, ], }); var leadAgent = await client.Beta.Agents.Create(new() { Name = "lead", Model = BetaManagedAgentsModel.ClaudeOpus5_5, Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, }, ], Multiagent = new BetaManagedAgentsMultiagent20261001Params { Subagents = new BetaManagedAgentsMultiagentSubagentsEnabledParams { PredefinedAgents = [ new BetaManagedAgentsAgentParams { Type = BetaManagedAgentsAgentParamsType.Agent, ID = researchAgent.ID, }, ], }, }, }); ``` ```go Go researcher, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "researcher", Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeHaiku5_5}, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{ Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "github", URL: "https://api.githubcopilot.com/mcp/", }}, Tools: []anthropic.BetaAgentNewParamsToolUnion{{ OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "github", }, }}, }) if err != nil { panic(err) } leadAgent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "lead", Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5}, Tools: []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }}, Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{ OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{ Subagents: anthropic.BetaManagedAgentsMultiagentSubagentsParamsUnion{ OfEnabled: &anthropic.BetaManagedAgentsMultiagentSubagentsEnabledParams{ PredefinedAgents: []anthropic.BetaManagedAgentsMultiagentPredefinedAgentParamsUnion{{ OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{ Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent, ID: researcher.ID, }, }}, }, }, }, }, }) if err != nil { panic(err) } ``` ```java Java var researcher = client.beta().agents().create( AgentCreateParams.builder() .name("researcher") .model(BetaManagedAgentsModel.CLAUDE_HAIKU_5_5) .addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder() .name("github") .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .url("https://api.githubcopilot.com/mcp/") .build()) .addTool(BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("github") .build()) .build() ); var leadAgent = client.beta().agents().create( AgentCreateParams.builder() .name("lead") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build()) .multiagent(BetaManagedAgentsMultiagent20261001Params.builder() .subagents(BetaManagedAgentsMultiagentSubagentsEnabledParams.builder() .addPredefinedAgent(BetaManagedAgentsAgentParams.builder() .type(BetaManagedAgentsAgentParams.Type.AGENT) .id(researcher.id()) .build()) .build()) .build()) .build() ); ``` ```php PHP $researchAgent = $client->beta->agents->create( name: 'researcher', model: 'claude-haiku-5-5', mcpServers: [ ['type' => 'url', 'name' => 'github', 'url' => 'https://api.githubcopilot.com/mcp/'], ], tools: [ ['type' => 'mcp_toolset', 'mcp_server_name' => 'github'], ], ); $leadAgent = $client->beta->agents->create( name: 'lead', model: 'claude-opus-5-5', tools: [ ['type' => 'agent_toolset_20260401'], ], multiagent: [ 'type' => 'multiagent_20261001', 'subagents' => [ 'type' => 'enabled', 'predefined_agents' => [ ['type' => 'agent', 'id' => $researchAgent->id], ], ], ], ); ``` ```ruby Ruby research_agent = client.beta.agents.create( name: "researcher", model: "claude-haiku-5-5", mcp_servers: [ {type: "url", name: "github", url: "https://api.githubcopilot.com/mcp/"} ], tools: [ {type: "mcp_toolset", mcp_server_name: "github"} ] ) lead_agent = client.beta.agents.create( name: "lead", model: "claude-opus-5-5", tools: [ {type: "agent_toolset_20260401"} ], multiagent: { type: "multiagent_20261001", subagents: { type: "enabled", predefined_agents: [ {type: "agent", id: research_agent.id} ] } } ) ``` 그런 다음 GitHub 자격 증명을 보관하는 vault로 세션을 생성하세요: ```bash cURL curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$lead_agent_id"'", "environment_id": "'"$environment_id"'", "vault_ids": ["'"$vault_id"'"] }' ``` ```bash CLI ant beta:sessions create \ --agent "$lead_agent_id" \ --environment-id "$environment_id" \ --vault-id "$vault_id" ``` ```python Python session = client.beta.sessions.create( agent=lead_agent.id, environment_id=environment.id, vault_ids=[vault.id], ) print(session.id) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: leadAgent.id, environment_id: environment.id, vault_ids: [vault.id] }); console.log(session.id); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = leadAgent.ID, EnvironmentID = environment.ID, VaultIds = [vault.ID], }); Console.WriteLine(session.ID); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{ OfString: anthropic.String(leadAgent.ID), }, EnvironmentID: environment.ID, VaultIDs: []string{vault.ID}, }) if err != nil { panic(err) } fmt.Println(session.ID) ``` ```java Java var session = client.beta().sessions().create(SessionCreateParams.builder() .agent(leadAgent.id()) .environmentId(environment.id()) .vaultIds(List.of(vault.id())) .build()); IO.println(session.id()); ``` ```php PHP $session = $client->beta->sessions->create( agent: $leadAgent->id, environmentID: $environment->id, vaultIDs: [$vault->id], ); echo "{$session->id}\n"; ``` ```ruby Ruby session = client.beta.sessions.create( agent: lead_agent.id, environment_id: environment.id, vault_ids: [vault.id] ) puts session.id ``` 이 예제에서는 researcher만 GitHub MCP 서버를 선언하므로, 세션이 실행하는 에이전트는 접근 권한이 없습니다. 세션의 `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`)가 researcher의 스레드에 GitHub 자격 증명을 제공합니다. 서버를 선언한 후에도 에이전트의 MCP 호출이 인증에 실패하면, 자격 증명의 `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`)이 에이전트의 `mcp_servers[].url` (java, php: `mcpServers[].url`; csharp: `McpServers[].Url`; go: `MCPServers[].URL`)과 동일한 서버를 가리키는지 확인하세요. 두 URL은 매칭 전에 정규화되므로(스킴과 호스트는 소문자로 변환되고, 기본 포트와 후행 슬래시는 제거됨) 호스트 대소문자, 기본 포트 또는 후행 슬래시의 차이는 매칭을 방해하지 않습니다. 하지만 경로, 하위 도메인 또는 기본값이 아닌 포트가 다르면 매칭되지 않습니다. ### 스레드 각 에이전트의 세션 스레드에는 자체 이벤트 스트림이 있습니다. 스레드를 나열, 중단 또는 보관하고, 이벤트를 읽고, 스레드 전반의 도구 권한을 처리하려면 [세션 스레드](https://platform.claude.com/docs/ko/managed-agents/session-threads)를 참조하세요. ## 동적 워크플로 동적 워크플로를 사용하면 에이전트가 수백 개의 문서를 검토하거나 여러 소스를 교차 검증하는 것처럼 여러 부분으로 구성된 작업을 맡을 수 있습니다. 에이전트는 **workflow**(워크플로), 즉 여러 에이전트를 단계별로 실행하고 그 반환 결과를 결합하는 프로그램을 작성합니다. 서버는 이를 **workflow run**(워크플로 실행)으로 백그라운드에서 실행하며, 그동안 에이전트는 계속 작업하거나 턴을 종료합니다. 동적 워크플로는 에이전트의 `multiagent` (csharp, go: `Multiagent`) 블록에 있는 `workflows` (csharp, go: `Workflows`) 설정으로 켜거나 끕니다. 실행의 에이전트들은 동시에 작업할 수 있으므로, 긴 작업을 하나의 에이전트가 각 부분을 차례로 처리할 때보다 더 빨리 끝낼 수 있습니다. * **실행이 시작되는 방식:** `user.message`에서 작업을 설명합니다. 이를 바탕으로 에이전트가 실행을 시작할지 여부와 시점을 결정하므로, 추가 API 호출이 필요하지 않습니다. 대신 `user.message` 또는 에이전트의 시스템 프롬프트에서 언제 실행을 사용해야 하는지 설명하여 에이전트의 결정에 영향을 줄 수 있습니다. (권한 정책은 실행 시작이 아니라 실행의 에이전트가 호출하는 도구에 적용됩니다.) * **사용하는 에이전트:** 워크플로가 정의하는 [인라인 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents), `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열한 사전 정의 에이전트, 또는 둘 다입니다. 아무것도 나열하지 않으면 워크플로가 모든 에이전트를 정의합니다. 인라인 에이전트는 세션이 실행하는 에이전트의 모델을 사용합니다. 실행이 일부 에이전트에 다른 모델을 사용하도록 하려면, 해당 에이전트를 에이전트로 생성하고 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열하세요. * **추적 방법:** 실행 이벤트는 세션의 이벤트 스트림으로 도착하며, 실행의 각 에이전트는 나열, 읽기, 스트리밍이 가능한 [세션 스레드](https://platform.claude.com/docs/ko/managed-agents/session-threads)에서 작업합니다. 이벤트, 중단, [제한](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#limits), [실행의 스레드가 보여 주는 내용](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#a-runs-threads)에 대해서는 [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs)을 참조하세요. ### 동적 워크플로 켜기 [에이전트를 정의](https://platform.claude.com/docs/ko/managed-agents/agent-setup)할 때 `multiagent.type`을 `"multiagent_20261001"`로 설정하고 `workflows`를 활성화하세요. 이 유형에서는 동적 워크플로와 위임(`subagents`)이 모두 기본적으로 켜져 있습니다. 동적 워크플로만 사용하려면 `"subagents": {"type": "disabled"}`를 추가하세요. 기존 에이전트의 `multiagent.type`을 변경하기 전에 [에이전트를 이 유형으로 옮기는 방법](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#move-from-the-coordinator-type)을 참조하세요. ```bash cURL curl -fsS https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "Contract Reviewer", "model": "claude-opus-5-5", "system": "You review contracts. When you are 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"}} }' ``` ```bash CLI ant apply contract-reviewer.md ``` ```markdown --- name: Contract Reviewer model: claude-opus-5-5 tools: - type: agent_toolset_20260401 multiagent: type: multiagent_20261001 workflows: type: enabled --- 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. ``` ```python Python agent = client.beta.agents.create( 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"}}, ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ 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" } } }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "Contract Reviewer", Model = BetaManagedAgentsModel.ClaudeOpus5_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 = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, }, ], // 구성 클래스가 타입을 자동으로 설정합니다. Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = new BetaManagedAgentsMultiagentWorkflowsEnabledParams(), }, }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Contract Reviewer", Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5}, System: anthropic.String("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: []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }}, Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{ OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{ Workflows: anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion{ OfEnabled: &anthropic.BetaManagedAgentsMultiagentWorkflowsEnabledParams{}, }, }, }, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Contract Reviewer") .model(BetaManagedAgentsModel.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.") .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) // 구성 클래스가 타입을 자동으로 설정합니다. .multiagent(BetaManagedAgentsMultiagent20261001Params.builder() .workflows(BetaManagedAgentsMultiagentWorkflowsEnabledParams.builder().build()) .build()) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( 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']], ); ``` ```ruby Ruby agent = client.beta.agents.create( 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"}} ) ``` 이미 생성해 둔 에이전트를 워크플로가 사용할 수 있도록 하려면 `workflows.predefined_agents`에 해당 에이전트를 나열하세요. `subagents` 및 `advisor` 설정은 같은 `multiagent` 블록에 들어갑니다. 서브에이전트를 나열하려면 [서브에이전트에 위임하기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#delegate-to-subagents)를 참조하세요. 어드바이저를 설정하려면 [세션에 어드바이저 제공하기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#give-the-session-an-advisor)를 참조하세요. 이 에이전트는 워크플로가 사용자가 생성한 에이전트 하나를 사용할 수 있도록 하고, 두 개의 서브에이전트를 나열하며, 어드바이저를 가집니다: ```json { "multiagent": { "type": "multiagent_20261001", "workflows": { "type": "enabled", "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }] }, "subagents": { "type": "enabled", "predefined_agents": [ { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" }, { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" } ] }, "advisor": { "type": "enabled", "model": "claude-opus-5-5" } } } ``` 각 설정은 개별적으로 활성화하거나 비활성화할 수 있습니다: | 설정 | 켜지는 기능 | 에이전트 위치 | 기본값 | | ----------- | --------------------------------------------- | ------------------------------------- | ---- | | `workflows` | 동적 워크플로 | `workflows.predefined_agents`, 최대 20개 | 활성화 | | `subagents` | 서브에이전트에 위임: 사용자가 나열한 에이전트 및 에이전트가 직접 정의한 에이전트 | `subagents.predefined_agents`, 최대 20개 | 활성화 | | `advisor` | 어드바이저 모델 | 없음. `model`을 설정합니다. | 비활성화 | 각 목록에 들어가는 항목과 사용자가 나열한 에이전트만 허용하는 방법은 [사전 정의 에이전트와 인라인 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)를 참조하세요. 다음 사항에 유의하세요: * **업데이트:** `multiagent_20261001` 유형을 유지하는 업데이트는 전송한 항목만 변경합니다: * 생략한 설정이나 필드는 저장된 값을 유지합니다. * `null`로 전송한 설정이나 필드는 저장된 값과 관계없이 기본값을 가지며, 그 안의 모든 항목도 마찬가지입니다. * 전송한 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록은 저장된 목록을 대체합니다. * 다른 `type`으로 전송한 설정은 저장된 설정을 대체하며, 그 안에서 생략한 필드는 기본값을 가집니다. * 전송하는 모든 객체에는 `type`이 필요하며, 활성화된 `advisor`에는 `model`이 필요합니다. * **끄기:** `workflows`를 `{"type": "disabled"}`로 설정하세요. 업데이트로 다시 켤 때까지 꺼진 상태로 유지됩니다. 기본값이 활성화이므로 `null`을 전송하면 켜집니다. `subagents`에도 동일하게 적용됩니다. * **기존 세션:** 세션은 생성될 때 설정을 복사하므로, 나중에 에이전트를 변경해도 이미 존재하는 세션은 변경되지 않습니다. * **나열할 수 있는 에이전트:** `multiagent` (csharp, go: `Multiagent`)가 설정된 에이전트는 다른 에이전트의 서브에이전트로 나열하거나, 다른 에이전트의 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열할 수 없습니다. 에이전트는 `{"type": "self"}`를 사용하여 두 목록 중 어디에든 자기 자신을 나열할 수 있으며, 이 항목은 조회 시 자신의 `id` 및 `version`으로 반환됩니다. * **도구 이름:** `ant__` 접두사는 예약되어 있습니다. 에이전트에 이름이 `ant__`로 시작하는 사용자 정의 도구가 이미 있는 경우, 해당 이름 없이 `tools` (csharp, go: `Tools`)를 전송할 때까지 업데이트가 400 오류로 실패합니다. 세션의 에이전트 또는 두 목록 중 하나에 있는 에이전트가 그러한 도구를 가지고 있으면 새 세션도 400 오류로 거부됩니다. 동적 워크플로를 켜는 동일한 업데이트에서 도구 이름을 변경하거나 도구를 제거하세요. [커스텀 도구](https://platform.claude.com/docs/ko/managed-agents/tools#custom-tools)를 참조하세요. * **예산:** 실행을 포함한 세션의 지출을 제한하려면 세션을 생성할 때 [세션 예산](https://platform.claude.com/docs/ko/managed-agents/budgets)을 설정하세요. 기존 세션에는 예산을 추가할 수 없습니다. 세션이 예산에 도달하면 실행이 일시 중지되며, 예산으로 인해 일시 중지된 실행은 예산을 늘리거나 제거하면 재개됩니다. 단, 중단으로도 일시 중지된 경우는 예외입니다. [비용 및 예산](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#cost-and-budgets)을 참조하세요. ### 실행을 사용할 시점을 에이전트에 알려주기 동적 워크플로를 켜면 에이전트가 워크플로 실행을 시작할 수 있게 됩니다. 실행을 시작할 시점은 에이전트가 결정합니다. 이 선택을 안내하려면 에이전트의 시스템 프롬프트에 다음과 같은 지침을 추가하세요. [동적 워크플로 켜기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)의 계약 검토 에이전트는 다음 시스템 프롬프트를 사용합니다: ```text wrap 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. ``` 이를 조정하려면 에이전트의 도메인에서 실행이 필요한 작업과 에이전트가 직접 수행해야 하는 작은 작업을 명시하세요. 다음 예시와 같이 실행이 작업을 수행하는 방식도 안내할 수 있습니다: * **작업 분할 방법:** "실행에서는 계약서당 하나의 에이전트를 사용하세요. 그런 다음 두 번째 에이전트가 첫 번째 에이전트가 무언가를 발견한 계약서뿐만 아니라 모든 계약서를 검토하고, 첫 번째 에이전트가 놓친 부분을 찾도록 하세요. 검토를 통과하지 못한 항목은 다시 수행하고 다시 검토합니다." * **에이전트가 실패했을 때 할 일:** "하나의 에이전트가 실패해도 실행이 실패해서는 안 됩니다. 에이전트가 계약서를 읽지 못하면 해당 계약서를 처리되지 않은 것으로 표시하세요. 실행이 끝나면 어떤 계약서가 처리되지 않았는지 알려주세요." * **시간 제한:** "실행에 1시간의 시간 제한을 두세요." * **먼저 계획하기:** "실행을 시작하기 전에 단계와 각 단계에서 실행할 에이전트 수를 설명하세요. 그런 다음 제 승인을 기다리세요." 실행이 시작되기 전에 승인 단계가 없으므로 이를 강제하는 장치는 없습니다. 실행에 포함된 모든 에이전트가 토큰을 사용하므로, 실행은 필요한 작업에만 사용하세요. 그런 다음 다른 에이전트와 마찬가지로 해당 에이전트로 [세션을 생성](https://platform.claude.com/docs/ko/managed-agents/sessions)하고 `user.message`에 작업을 설명하세요. 해당 메시지에서 실행을 요청할 수도 있습니다. 실행의 이벤트, 실행이 열려 있는 세션 중단, 실행이 열려 있는 동안 변경되는 사항, 예산 및 제한에 대해서는 [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs)을 참조하세요. ## 세션에 어드바이저 제공하기 에이전트의 `multiagent` (csharp, go: `Multiagent`) 블록에서 `advisor` 설정을 활성화하면 세션의 기본 스레드에 **어드바이저**가 제공됩니다. 어드바이저는 접근 방식 계획, 막힌 상황 해결, 완료 전 작업 검토 등 전략적 지침을 얻기 위해 턴 도중에 자문을 구할 수 있는 모델입니다. 이 설정은 기본적으로 비활성화되어 있습니다. 활성화하려면 `advisor`를 `{"type": "enabled", "model": "..."}`로 설정하세요. 이 설정에는 정확히 두 개의 필드, `type`과 `model`이 있습니다: ```bash cURL curl -fsS https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "name": "Backend engineer", "model": "claude-sonnet-5", "system": "You implement backend features end to end. Consult the advisor before major backend design decisions.", "multiagent": { "type": "multiagent_20261001", "advisor": {"type": "enabled", "model": "claude-opus-5-5"} } }' ``` ```bash CLI ant apply backend-engineer.md ``` ```markdown --- name: Backend engineer model: claude-sonnet-5 multiagent: type: multiagent_20261001 advisor: type: enabled model: claude-opus-5-5 --- You implement backend features end to end. Consult the advisor before major backend design decisions. ``` ```python Python agent = client.beta.agents.create( name="Backend engineer", model="claude-sonnet-5", system="You implement backend features end to end. Consult the advisor before major backend design decisions.", multiagent={ "type": "multiagent_20261001", "advisor": {"type": "enabled", "model": "claude-opus-5-5"}, }, ) print(agent.id) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Backend engineer", model: "claude-sonnet-5", system: "You implement backend features end to end. Consult the advisor before major backend design decisions.", multiagent: { type: "multiagent_20261001", advisor: { type: "enabled", model: "claude-opus-5-5" } } }); console.log(agent.id); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "Backend engineer", Model = BetaManagedAgentsModel.ClaudeSonnet5, System = "You implement backend features end to end. Consult the advisor before major backend design decisions.", Multiagent = new BetaManagedAgentsMultiagent20261001Params { Advisor = new BetaManagedAgentsMultiagentAdvisorEnabledParams { Model = "claude-opus-5-5" }, }, }); Console.WriteLine(agent.ID); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Backend engineer", Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeSonnet5}, System: anthropic.String("You implement backend features end to end. Consult the advisor before major backend design decisions."), Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{ OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{ Advisor: anthropic.BetaManagedAgentsMultiagentAdvisorParamsUnion{ OfEnabled: &anthropic.BetaManagedAgentsMultiagentAdvisorEnabledParams{ Model: "claude-opus-5-5", }, }, }, }, }) if err != nil { panic(err) } fmt.Println(agent.ID) ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Backend engineer") .model(BetaManagedAgentsModel.CLAUDE_SONNET_5) .system("You implement backend features end to end. Consult the advisor before major backend design decisions.") .multiagent(BetaManagedAgentsMultiagent20261001Params.builder() .advisor(BetaManagedAgentsMultiagentAdvisorEnabledParams.builder() .model("claude-opus-5-5") .build()) .build()) .build() ); IO.println(agent.id()); ``` ```php PHP $agent = $client->beta->agents->create( name: 'Backend engineer', model: 'claude-sonnet-5', system: 'You implement backend features end to end. Consult the advisor before major backend design decisions.', multiagent: [ 'type' => 'multiagent_20261001', 'advisor' => ['type' => 'enabled', 'model' => 'claude-opus-5-5'], ], ); echo $agent->id, PHP_EOL; ``` ```ruby Ruby agent = client.beta.agents.create( name: "Backend engineer", model: "claude-sonnet-5", system_: "You implement backend features end to end. Consult the advisor before major backend design decisions.", multiagent: { type: "multiagent_20261001", advisor: {type: "enabled", model: "claude-opus-5-5"} } ) puts agent.id ``` 이 예시는 `advisor` (csharp, go: `Advisor`)만 설정합니다. 나머지 두 설정인 `subagents` (csharp, go: `Subagents`)와 `workflows` (csharp, go: `Workflows`)는 기본값을 유지하므로 둘 다 활성화되며, 에이전트는 인라인 에이전트에 위임하고 워크플로 실행을 시작할 수도 있습니다. 어드바이저에 자문을 구하면서 모든 작업을 직접 수행하는 에이전트를 원한다면 두 설정을 모두 `{"type": "disabled"}`로 설정하세요. `subagents` (csharp, go: `Subagents`) 또는 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에는 어드바이저를 나열할 수 없습니다. 활성화된 `advisor` (csharp, go: `Advisor`)는 `anthropic.advisor`라는 이름을 예약합니다. 활성화되어 있는 동안에는 두 목록 모두 이름이 정확히 `anthropic.advisor`인 에이전트를 포함할 수 없으며, 해당 요청은 400 유효성 검사 오류로 거부됩니다. 어드바이저 모델은 최소 성능 기준을 충족해야 하며, 에이전트 자체의 모델은 어드바이저보다 성능이 높아서는 안 됩니다. 성능이 동일한 모델끼리는 짝을 이룰 수 있습니다. 유효하지 않은 조합은 에이전트를 저장할 때 400 유효성 검사 오류로 거부되며, 세션을 생성할 때도 다시 거부됩니다. 조합은 각 자문이 시작될 때도 확인됩니다. 더 이상 유효하지 않으면 해당 자문은 실패하고 세션은 계속됩니다. 유효한 조합은 어드바이저 도구의 [모델 호환성](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool#model-compatibility) 표를 따릅니다. 어드바이저는 [Messages API의 서버 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool)로도 사용할 수 있습니다. Managed Agents 환경은 구성과 전달 방식이 다릅니다. `advisor` (csharp, go: `Advisor`) 설정에는 `max_uses`, `max_tokens`, `caching` 필드가 없으며, 조언은 `advisor_tool_result` 블록이 아닌 스레드 이벤트를 통해 전달됩니다. ### 자문이 작동하는 방식 각 자문은 `anthropic.advisor`라는 이름의 플랫폼 생성 스레드로 실행되며, 이 스레드는 자문이 완료되면 스스로 종료됩니다. 조언은 `agent.thread_message_received` 이벤트로 기본 스레드에 전달됩니다. 자문은 예약된 이름 `anthropic.advisor`로 식별되는 표준 스레드 이벤트를 발생시키며(스레드 수명 주기 이벤트는 이를 `agent_name` (java, php: `agentName`; csharp, go: `AgentName`)으로, 조언 전달은 `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`)으로 포함합니다), 일반적으로 다음 순서를 따릅니다: 1. `session.thread_created` 2. `session.thread_status_running` 3. `agent.thread_message_received` (조언) 4. `session.thread_status_idle` (`stop_reason: end_turn`) 5. `session.thread_status_terminated` 자문 입력은 에이전트가 보내는 것이 아니라 플랫폼이 구성하므로, 자문에 대해서는 `agent.tool_use` 이벤트가 발생하지 않으며 세션의 이벤트 스트림에 `agent.thread_message_sent` 이벤트도 나타나지 않습니다. 어드바이저 스레드 자체의 이벤트를 나열하면 조언이 그곳에도 `agent.thread_message_sent` 이벤트로 나타납니다. 조언 전달(이벤트 3)이 어드바이저 스레드의 idle 및 terminated 이벤트보다 먼저 도착한다는 보장은 없으므로, 이러한 이벤트를 조언이 이미 전달되었다는 신호로 간주하지 마세요. 클라이언트가 조언을 읽을 수 있는지 여부는 어드바이저 모델의 정책에 따릅니다. 이는 Messages API 어드바이저 도구의 [결과 변형](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool#result-variants) 구분을 그대로 따릅니다. 그곳에서 평문 결과를 반환하는 어드바이저 모델은 여기서도 읽을 수 있는 텍스트를 전달합니다. 편집된(redacted) 결과를 반환하는 모델은 모든 클라이언트 환경에서 `[{"type": "redacted"}]` 플레이스홀더를 전달하며, 에이전트는 서버 측에서 여전히 전체 조언을 읽습니다. 앞의 예시는 사용 가능한 최신 Opus 모델을 어드바이저로 사용합니다. Claude Opus 5.5는 편집된 결과를 반환하므로 클라이언트에는 플레이스홀더만 표시됩니다. 이벤트 스트림에서 조언을 읽으려면 Claude Opus 4.8과 같이 평문을 반환하는 어드바이저를 사용하세요. 모델의 정책은 API 변경 없이 바뀔 수 있으므로 `text` 블록과 `redacted` 블록을 모두 처리하세요. 일부 에이전트 모델은 편집된 결과를 반환하는 어드바이저와만 짝을 이룹니다. 어드바이저 도구의 [호환성 표](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/advisor-tool#model-compatibility)를 참조하세요. 어드바이저의 사고 내용은 절대 노출되지 않습니다. 클라이언트는 `redacted` 블록을 직접 보낼 수 없으며, 이를 포함한 이벤트는 400 유효성 검사 오류로 거부됩니다. 실패하거나 중단된 자문은 에이전트의 턴을 실패시키지 않습니다. 에이전트는 자문이 실패했다는 일반적인 알림을 받은 후 계속 진행합니다. 자문 중 세션 수준의 `user.interrupt`는 조언을 전달하지 않고 어드바이저 스레드를 종료합니다. 어드바이저 스레드의 `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`)를 지정한 `user.interrupt`는 해당 자문만 중단합니다. ### 어드바이저 스레드 어드바이저는 서브에이전트가 아닙니다. 에이전트의 `list_agents` 도구에는 어드바이저가 표시되지 않으며, 서브에이전트에 후속 메시지를 보내는 `send_to_agent`로도 어드바이저에 도달할 수 없습니다. 세션의 기본 스레드만 어드바이저에 자문을 구할 수 있으며, 서브에이전트는 자문을 구할 수 없습니다. 어드바이저 스레드는 25개 하위 스레드 제한에서 제외됩니다. 어드바이저 스레드는 세션의 [스레드 목록](https://platform.claude.com/docs/ko/managed-agents/session-threads)에 나타납니다. 해당 스레드의 `agent`는 구성한 모델이 포함된 어드바이저 형식 `{"type": "advisor", "model": ...}`이며, `parent_thread_id`는 기본 스레드입니다. 어드바이저 측의 프롬프트 캐싱은 자동으로 이루어지며 별도로 구성할 것이 없습니다. 자문은 어드바이저 모델의 요금으로 청구되며, 해당 토큰은 어드바이저 스레드의 사용량과 세션의 사용량 합계에 나타납니다. 또한 어드바이저 모델의 정가 기준으로 [세션 예산](https://platform.claude.com/docs/ko/managed-agents/budgets)에도 포함됩니다. 각 자문은 지금까지의 기본 스레드 대화를 어드바이저에 전송하므로, 긴 세션의 후반부에 이루어지는 자문은 더 많은 입력 토큰을 사용합니다. ### 어드바이저 제거하기 어드바이저를 제거하려면 `advisor`를 `{"type": "disabled"}`로 설정하여 [에이전트를 업데이트](https://platform.claude.com/docs/ko/managed-agents/agent-setup#update-an-agent)하세요. 이미 `multiagent_20261001` 유형을 가진 에이전트에서는 업데이트에서 생략한 설정이 저장된 값을 유지하므로 `subagents`나 `workflows`를 다시 보낼 필요가 없습니다. 같은 이유로 `advisor`를 생략한 업데이트는 어드바이저를 유지합니다. 기존 에이전트의 `multiagent.type`을 변경하기 전에 [에이전트를 이 유형으로 옮기는 방법](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#move-from-the-coordinator-type)을 참조하세요. ## `coordinator` 유형에서 옮기기 `multiagent_20261001`과 마찬가지로 `coordinator` 유형은 에이전트가 사용자가 나열한 서브에이전트에 위임하고 어드바이저 모델에 자문을 구할 수 있게 합니다. `coordinator` 유형에서는 에이전트가 워크플로 실행을 시작하거나 서브에이전트를 직접 정의할 수 없습니다. API는 두 유형을 모두 허용합니다. 에이전트를 `multiagent_20261001`로 옮기려면 해당 유형의 `multiagent` 블록으로 [에이전트를 업데이트](https://platform.claude.com/docs/ko/managed-agents/agent-setup#update-an-agent)하세요: 1. `type`을 `"multiagent_20261001"`로 설정합니다. 2. 에이전트가 호출할 수 있는 에이전트를 `subagents.predefined_agents`에 나열합니다. 항목은 현재 형식을 그대로 유지합니다. 3. 에이전트에 어드바이저가 있는 경우 어드바이저의 모델로 `advisor`를 `{"type": "enabled", "model": "..."}`로 설정합니다. 4. 전체 블록을 한 번의 업데이트로 전송합니다. 예를 들어, 다음 블록은 에이전트에 두 개의 서브에이전트와 어드바이저를 제공합니다: ```json { "multiagent": { "type": "multiagent_20261001", "subagents": { "type": "enabled", "predefined_agents": [ { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" }, { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" } ] }, "advisor": { "type": "enabled", "model": "claude-opus-5-5" } } } ``` 이 블록은 `workflows`와 `subagents.inline_agents`를 생략하므로 둘 다 기본값을 가지며 활성화됩니다. 옮겨진 에이전트는 워크플로 실행을 시작하고 서브에이전트를 직접 정의할 수도 있습니다. 둘 중 하나를 끈 상태로 유지하려면 같은 업데이트에서 `{"type": "disabled"}`로 설정하세요. [동적 워크플로 켜기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) 및 [사전 정의 에이전트와 인라인 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#predefined-and-inline-agents)를 참조하세요. 에이전트에 어드바이저는 있지만 서브에이전트가 없는 경우, 위임을 끈 상태로 유지하려면 `subagents`를 `{"type": "disabled"}`로 설정하세요. `subagents.inline_agents`를 비활성화하고 에이전트를 나열하지 않는 요청은 400 오류로 실패합니다. 업데이트는 전체 `multiagent` 블록을 대체하므로, 예시와 같이 에이전트 목록과 어드바이저를 다시 전송하세요. 생략한 항목은 기본값을 가집니다: * **`subagents.predefined_agents`:** 목록이 비어 있게 되므로 에이전트는 사용자가 나열했던 서브에이전트를 잃게 됩니다. * **`advisor`:** 어드바이저가 비활성화됩니다. 에이전트가 `multiagent_20261001` 유형을 갖게 되면, 이후 업데이트에서 생략한 설정은 저장된 값을 유지합니다. 업데이트는 이미 존재하는 세션을 변경하지 않습니다. 새 블록을 사용하려면 업데이트 후에 세션을 생성하세요.