---
title: Orquestração multiagente
url: https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration
description: Coordene vários agentes em uma única sessão.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
A orquestração multiagente permite que um agente coordene com outros para concluir trabalhos complexos. Os agentes podem atuar em paralelo com seu próprio contexto isolado, o que ajuda a melhorar a qualidade da saída e também pode melhorar o tempo até a conclusão.
Não tem certeza se uma configuração multiagente se encaixa no seu problema? Consulte [quando usar sistemas multiagente (e quando não usar)](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them).
## Repassar trabalho para outros agentes
O agente que uma sessão executa pode repassar trabalho para outros agentes de duas maneiras. Com **subagentes**, ele mesmo delega tarefas e lê o que cada subagente relata. Com **workflows dinâmicos**, ele escreve um workflow: um programa que executa muitos agentes em segundo plano e combina seus resultados. Ele também pode consultar um modelo **advisor** (consultor) para obter orientação enquanto faz o trabalho por conta própria.
Você decide quais desses recursos o agente pode usar, e o agente determina quando usá-los. Para orientar essa escolha, diga ao agente, no prompt do sistema dele, quando usar uma execução de workflow. Consulte [Informar ao agente quando usar uma execução](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run). Você também pode limitar o agente aos agentes que você listar.
Com subagentes, o próprio agente determina o que acontece em seguida. A [thread de um subagente](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads) permanece disponível até que você a arquive, para que o agente possa enviar mensagens de acompanhamento a ela. Com workflows dinâmicos, Claude escreve um programa para orquestrar agentes sem o envolvimento direto de Claude. O contexto e os resultados são passados programaticamente de um agente para outro, liberando a thread principal da sessão para se comunicar com o usuário e verificar um ou vários workflows em execução para relatar o progresso. O agente não pode enviar mensagens de acompanhamento às threads de uma execução, e o servidor arquiva cada uma delas até o fim da execução.
| Abordagem | O que acontece | Use quando | Considere |
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Subagentes](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#delegate-to-subagents) | O agente delega tarefas aos seus subagentes. Cada subagente trabalha em sua própria [thread de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads), que você pode listar e acompanhar via streaming. | O agente deve dar continuidade com um subagente depois que ele relatar, ou precisa de especialistas que você lista, com seus próprios prompts do sistema e ferramentas. | A delegação tem apenas um nível de profundidade, e uma sessão pode ter no máximo 25 threads filhas por vez, incluindo as ociosas. Threads do advisor e threads de uma execução de workflow não contam. |
| [Workflows dinâmicos](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#dynamic-workflows) | O agente escreve um workflow: um programa que executa muitos agentes em fases e combina seus resultados. O servidor o executa em segundo plano como uma execução de workflow, que você pode acompanhar. O workflow define os agentes ou os escolhe de uma lista que você fornece. | A maior parte do trabalho que precisa de mais de um agente: trabalho com muitas partes, trabalho paralelo ou uma tarefa longa que deveria terminar mais cedo. Exemplos são auditorias, migrações, pesquisa aprofundada e verificação cruzada. | Cada agente em uma execução usa tokens, então defina um [orçamento de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/budgets) para limitar o gasto da sessão, incluindo as execuções. Diga ao agente, no prompt do sistema dele, quando usar uma execução. Você acompanha a execução por suas fases e pode ler cada uma de suas threads. |
| [Dar um advisor à sessão](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#give-the-session-an-advisor) | A [thread principal](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#how-it-works) da sessão consulta um modelo advisor no meio do turno para obter orientação, como planejar uma abordagem ou revisar o trabalho, e continua fazendo o trabalho por conta própria. | Um único agente deve fazer o trabalho, com o julgamento de um modelo advisor em momentos-chave, como o planejamento ou uma revisão final. | Apenas a thread principal pode consultar o advisor, e as consultas são cobradas pelas tarifas do modelo advisor. |
Você configura esses recursos no bloco `multiagent` da definição do agente, que tem um `type`. Com o tipo `multiagent_20261001`, um agente pode usar os três juntos, e você pode ativar ou desativar cada um. Por padrão, `subagents` e `workflows` estão ambos habilitados. `subagents` e `workflows` têm cada um `inline_agents` habilitado, a configuração para [agentes que o próprio agente ou um workflow define](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents):
```json
{
"multiagent": { "type": "multiagent_20261001" }
}
```
Para definir quais agentes o agente pode chamar, consulte [Agentes predefinidos e inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents). Para desativar uma configuração, consulte [Ativar workflows dinâmicos](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
## Agentes predefinidos e inline
Cada subagente, e cada agente em uma execução de workflow, é de um de dois tipos:
* **Agente predefinido:** Um agente que você já [criou](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup) e que você lista no bloco `multiagent` (csharp, go: `Multiagent`). Ele usa sua própria configuração: modelo, prompt do sistema, ferramentas, servidores MCP e skills.
* **Agente inline:** Um agente que não é salvo. O agente que a sessão executa, ou um workflow, o define quando distribui o trabalho. Ele usa o modelo, as ferramentas, os servidores MCP e as skills desse agente.
Ambos os tipos funcionam sob `subagents` e sob `workflows`:
| Tipo de agente | Sob `subagents` | Sob `workflows` |
| -------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Predefinido | O agente pode delegar aos agentes que você lista em `subagents.predefined_agents`. | Um workflow pode usar os agentes que você lista em `workflows.predefined_agents`. |
| Inline | O agente pode definir um agente inline quando delega. `subagents.inline_agents` ativa ou desativa isso. | Um workflow pode definir agentes inline e escreve um prompt do sistema para cada um. `workflows.inline_agents` ativa ou desativa isso. |
`subagents.predefined_agents` e `workflows.predefined_agents` são duas listas separadas. Um agente em uma lista não é adicionado à outra. Ambas as listas estão vazias por padrão. Uma entrada de qualquer uma das listas assume uma destas formas:
* `{"type": "agent", "id": agent.id}` referencia um `agent` criado anteriormente pelo ID. Se nenhuma `version` for especificada, a referência é fixada na versão mais recente do agente quando o agente que o lista é criado, ou quando uma atualização envia a lista.
* `{"type": "agent", "id": agent.id, "version": agent.version}` fixa uma versão específica do agente.
* `agent.id` sozinho, como string, é uma forma abreviada de `{"type": "agent", "id": agent.id}`.
* `{"type": "self"}` lista o próprio agente, para que cópias dele possam fazer o trabalho. Se a sessão foi criada com [substituições de configuração do agente](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#override-agent-configuration-for-a-session), essas substituições também se aplicam a essas cópias. Entradas referenciadas por ID não são afetadas.
As regras para essas entradas, e para os agentes que elas nomeiam, se aplicam a ambas as listas. Consulte [Listar os subagentes](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#list-the-subagents).
Agentes inline estão ativados por padrão em ambas as configurações. Para permitir apenas os agentes que você lista, defina `inline_agents` como `{"type": "disabled"}` sob `subagents`, sob `workflows` ou sob ambos. Uma configuração com agentes inline desativados precisa de pelo menos um agente em sua lista `predefined_agents`. Com uma lista vazia, a solicitação falha com um erro 400. Em uma atualização, o servidor verifica as configurações como ficam após a atualização.
O agente a seguir permite apenas os agentes que ele lista. Ele pode delegar a um agente e a cópias de si mesmo, e um workflow pode usar a versão 2 de outro agente:
```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 }
]
}
}
}
```
## Delegar a subagentes
### O que delegar
A coordenação multiagente é mais adequada para tarefas complexas que exigem trabalho em uma variedade de superfícies, ou em que várias tarefas bem delimitadas contribuem para um objetivo geral.
Padrões que funcionam bem:
* **Paralelização:** Distribua subtarefas independentes simultaneamente (pesquisando várias fontes, analisando arquivos separados) e faça o agente sintetizar os resultados.
* **Especialização:** Encaminhe para agentes com prompts do sistema e ferramentas focados em um domínio, como um agente de segurança ou um agente de documentação, em vez de carregar um único agente com todas as capacidades.
* **Escalonamento:** Consulte um agente ou modelo mais capaz para um subconjunto de subtarefas complexas. Para consultar um modelo, [dê um advisor à sessão](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
### Como funciona
Todos os agentes compartilham o mesmo sandbox, sistema de arquivos e [credenciais do vault](https://platform.claude.com/docs/pt-BR/managed-agents/vaults), mas cada agente é executado em sua própria **thread de sessão**, um fluxo de eventos com contexto isolado e seu próprio histórico de conversa. O agente que a sessão executa relata a atividade na **thread principal**, que é o [fluxo de eventos](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming) no nível da sessão. Threads adicionais são criadas em tempo de execução quando ele delega trabalho. Uma execução de workflow também cria threads.
A thread de um subagente é persistente. O agente pode enviar uma mensagem de acompanhamento a um subagente que chamou anteriormente, e esse subagente retém tudo de seus turnos anteriores.
Qual configuração um subagente usa depende de ele ser um [agente predefinido ou inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents). As [substituições de configuração do agente](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#override-agent-configuration-for-a-session) no nível da sessão se aplicam ao agente que a sessão executa e às suas cópias `self`. Cada agente mantém seu próprio histórico de conversa.
### Listar os subagentes
Ao [definir seu agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup), defina a lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) no bloco `multiagent` (csharp, go: `Multiagent`) para listar os agentes aos quais ele pode delegar:
```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}
]
}
}
)
```
O agente também pode delegar a agentes inline, a menos que você os desative. Para essa configuração, e para as formas que uma entrada da lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) assume, consulte [Agentes predefinidos e inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
`"advisor": {"type": "enabled", "model": ""}` dá à thread principal da sessão um advisor que ela pode consultar no meio do turno. O advisor é uma configuração no bloco `multiagent` (csharp, go: `Multiagent`), não uma entrada nesta lista. Consulte [Dar um advisor à sessão](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
Workflows dinâmicos também estão habilitados por padrão com este tipo, então este agente pode planejar trabalhos grandes que executam muitos agentes em segundo plano. Para desativá-los, ou para listar agentes que um workflow pode usar, consulte [Ativar workflows dinâmicos](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
As regras a seguir se aplicam aos agentes que você lista em `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), e também aos agentes que você lista em `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`):
* **Fixação:** A configuração do agente, incluindo a lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`), é capturada em um snapshot quando o agente é criado ou atualizado. Os agentes referenciados permanecem fixados nas versões resolvidas naquele momento e não recebem atualizações posteriores de suas definições. Uma atualização que não envia a lista mantém as versões que já estão fixadas. Para delegar a uma versão mais recente de um agente referenciado, [atualize o agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#update-an-agent) para que a lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) referencie essa versão.
* **Um nível:** O agente pode delegar a apenas um nível de agentes. Referenciar outro agente que tenha `multiagent` (csharp, go: `Multiagent`) definido faz a solicitação de criação ou atualização falhar com um erro de validação 400.
* **Até 20 agentes:** A lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) pode listar até 20 agentes únicos. O limite é por lista: a lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`) também pode listar até 20. O agente pode chamar várias cópias de cada subagente, dentro do [limite de threads](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads) da sessão.
* **Geografia de inferência:** O agente e cada agente que você lista, na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou de `workflows` (csharp, go: `Workflows`), devem fixar a mesma [geografia de inferência](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency) (`inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) no `model` (csharp, go: `Model`) da [definição do agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup)), ou nenhum deles pode fixar uma. Uma incompatibilidade em qualquer uma das listas é rejeitada com um erro de validação 400. Essa verificação é executada tanto quando o agente é salvo quanto quando uma [substituição na criação da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#override-agent-configuration-for-a-session) altera qualquer uma das fixações.
### Criar a sessão
Crie uma sessão referenciando o agente. O agente delega aos agentes que você lista em `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) conforme necessário. Ele também pode delegar a [agentes inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents), a menos que você os desative.
```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
)
```
### Conectar agentes a servidores MCP
Os servidores MCP têm escopo de agente: cada definição de agente declara seus próprios servidores e ferramentas. Um agente inline não tem definição de agente, então ele usa os servidores MCP e as ferramentas do agente que a sessão executa. As credenciais do vault têm escopo de sessão: os `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) passados na criação da sessão se aplicam a todas as threads. Duas implicações para sua integração:
* Para autenticar servidores MCP, inclua uma credencial do vault para cada servidor MCP usado em todos os agentes.
* Para limitar o acesso de um agente, declare apenas os servidores de que ele precisa em sua definição de agente. Você não pode limitar um agente inline dessa forma. Para permitir apenas os agentes que você lista, desative `inline_agents` (java, php: `inlineAgents`; csharp, go: `InlineAgents`) tanto em `subagents` (csharp, go: `Subagents`) quanto em `workflows` (csharp, go: `Workflows`), e liste pelo menos um agente em cada. Consulte [Agentes predefinidos e inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
As [substituições de configuração do agente](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#override-agent-configuration-for-a-session) na criação da sessão podem substituir os servidores MCP do agente que a sessão executa e os de suas cópias `self`.
Com um [ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/environments#networking) `limited`, a criação da sessão falha com um erro 400 quando o agente, ou um agente que você lista em `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou de `workflows` (csharp, go: `Workflows`), declara um servidor MCP cujo host não está em `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Definir `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) como `true` na configuração de rede do ambiente desativa essa verificação.
Crie o pesquisador, que declara o servidor MCP do GitHub, e o agente que delega ao pesquisador:
```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}
]
}
}
)
```
Em seguida, crie a sessão com o vault que contém a credencial do GitHub:
```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
```
Neste exemplo, apenas o pesquisador declara o servidor MCP do GitHub, então o agente que a sessão executa não tem acesso. Os `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) da sessão fornecem a credencial do GitHub à thread do pesquisador.
Se as chamadas MCP de um agente falharem na autenticação depois que você declarar o servidor, confirme se o `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) da credencial se refere ao mesmo servidor que o `mcp_servers[].url` (java, php: `mcpServers[].url`; csharp: `McpServers[].Url`; go: `MCPServers[].URL`) do agente. Ambas as URLs são normalizadas antes da comparação (esquema e host convertidos para minúsculas, portas padrão e barras finais removidas), então diferenças de maiúsculas/minúsculas no host, uma porta padrão ou uma barra final não impedem a correspondência; um caminho, subdomínio ou porta não padrão diferente impede.
### Threads
A thread de sessão de cada agente tem seu próprio fluxo de eventos. Para listar, interromper ou arquivar threads, ler seus eventos e lidar com permissões de ferramentas entre elas, consulte [Threads de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads).
## Workflows dinâmicos
Com workflows dinâmicos, um agente pode assumir trabalhos com muitas partes, como revisar centenas de documentos ou fazer a verificação cruzada de muitas fontes. O agente escreve um **workflow**: um programa que executa muitos agentes em fases e combina o que eles retornam. O servidor o executa em segundo plano como uma **execução de workflow**, enquanto o agente continua trabalhando ou encerra seu turno. Você ativa ou desativa os workflows dinâmicos com a configuração `workflows` (csharp, go: `Workflows`) no bloco `multiagent` (csharp, go: `Multiagent`) do agente. Os agentes de uma execução podem trabalhar ao mesmo tempo, então uma tarefa longa pode terminar mais cedo do que se um único agente fizesse cada parte em sequência.
* **Como uma execução começa:** Você descreve o trabalho em uma `user.message`. A partir disso, o agente determina se e quando iniciar uma execução, então não há nenhuma chamada de API adicional. Em vez disso, você influencia a determinação do agente descrevendo quando usar uma execução na `user.message` ou no prompt do sistema do agente. (As políticas de permissão se aplicam às ferramentas que os agentes de uma execução chamam, não ao início da execução.)
* **Quais agentes ela usa:** [Agentes inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents) que o workflow define, agentes predefinidos que você lista em `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`), ou ambos. Se você não listar nenhum, o workflow define todos eles. Um agente inline usa o modelo do agente que a sessão executa. Para permitir que uma execução use outro modelo para alguns de seus agentes, crie-os como agentes e liste-os em `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`).
* **Como você a acompanha:** Os eventos da execução chegam no fluxo de eventos da sessão, e cada agente na execução trabalha em uma [thread de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads) que você pode listar, ler e acompanhar via streaming. Consulte [Execuções de workflow](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs) para ver os eventos, interrupções, [limites](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#limits) e [o que as threads de uma execução mostram](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#a-runs-threads).
### Ativar workflows dinâmicos
Ao [definir seu agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup), defina `multiagent.type` como `"multiagent_20261001"` e habilite `workflows`. Os workflows dinâmicos e a delegação (`subagents`) vêm ativados por padrão com esse tipo. Para usar apenas workflows dinâmicos, adicione `"subagents": {"type": "disabled"}`.
Antes de alterar o `multiagent.type` de um agente existente, consulte [como migrar um agente para este tipo](https://platform.claude.com/docs/pt-BR/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,
},
],
// A classe de configuração define o tipo para você.
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()
)
// A classe de configuração define o tipo para você.
.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"}}
)
```
Para permitir que um workflow use agentes que você já criou, liste-os em `workflows.predefined_agents`. As configurações `subagents` e `advisor` ficam no mesmo bloco `multiagent`. Para listar subagentes, consulte [Delegar a subagentes](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#delegate-to-subagents). Para definir um advisor, consulte [Dar um advisor à sessão](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#give-the-session-an-advisor). Este agente permite que um workflow use um agente que você criou, lista dois subagentes e tem um 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" }
}
}
```
Cada configuração é habilitada ou desabilitada de forma independente:
| Configuração | O que ela ativa | Onde ficam os agentes | Padrão |
| ------------ | ------------------------------------------------------------------------------------------ | ------------------------------------- | ------------ |
| `workflows` | Workflows dinâmicos | `workflows.predefined_agents`, até 20 | Habilitado |
| `subagents` | Delegação a subagentes: os agentes que você lista e os agentes que o próprio agente define | `subagents.predefined_agents`, até 20 | Habilitado |
| `advisor` | Um modelo advisor | Nenhum. Defina `model`. | Desabilitado |
Para saber o que vai em cada lista e como permitir apenas os agentes que você lista, consulte [Agentes predefinidos e inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Tenha em mente o seguinte:
* **Atualização:** Uma atualização que mantém o tipo `multiagent_20261001` altera apenas o que ela envia:
* Uma configuração ou campo que você omite mantém seu valor armazenado.
* Uma configuração ou campo que você envia como `null` assume seu padrão, assim como tudo dentro dele, independentemente do que você tinha armazenado.
* Uma lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) que você envia substitui a lista armazenada.
* Uma configuração que você envia com um `type` diferente substitui a configuração armazenada, e os campos que você omite nela assumem seus padrões.
* Todo objeto que você envia precisa do seu `type`, e um `advisor` habilitado precisa do seu `model`.
* **Desativação:** Defina `workflows` como `{"type": "disabled"}`. Ele permanece desativado até que uma atualização o ative novamente. Enviar `null` o ativa, porque seu padrão é habilitado. O mesmo se aplica a `subagents`.
* **Sessões existentes:** Uma sessão copia a configuração quando é criada, portanto alterar o agente depois não altera uma sessão que já existe.
* **Agentes que você pode listar:** Um agente que tem `multiagent` (csharp, go: `Multiagent`) definido não pode ser listado como subagente de outro agente, nem na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `workflows` (csharp, go: `Workflows`) em outro agente. Um agente pode listar a si mesmo em qualquer uma das listas com `{"type": "self"}`, que é lido de volta como seu próprio `id` e `version`.
* **Nomes de ferramentas:** O prefixo `ant__` é reservado. Se seu agente já tem uma ferramenta personalizada cujo nome começa com `ant__`, uma atualização falha com um erro 400 até que você envie `tools` (csharp, go: `Tools`) sem esse nome. Uma nova sessão também é recusada com um erro 400 se seu agente, ou um agente em qualquer uma das listas, tiver tal ferramenta. Renomeie ou remova a ferramenta na mesma atualização que ativa os workflows dinâmicos. Consulte [Ferramentas personalizadas](https://platform.claude.com/docs/pt-BR/managed-agents/tools#custom-tools).
* **Orçamento:** Defina um [orçamento de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/budgets) ao criar a sessão para limitar os gastos da sessão, incluindo as execuções; você não pode adicionar um a uma sessão existente. As execuções são pausadas quando a sessão atinge o orçamento, e as execuções que o orçamento pausou são retomadas quando você o aumenta ou remove, a menos que uma interrupção também as tenha pausado. Consulte [Custo e orçamentos](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#cost-and-budgets).
### Informar ao agente quando usar uma execução
Ativar os workflows dinâmicos dá ao agente a capacidade de iniciar execuções de workflow. O agente determina quando iniciar uma. Para orientar essa escolha, adicione uma instrução como a seguinte ao prompt do sistema do agente. O agente de revisão de contratos em [Ativar workflows dinâmicos](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) usa este prompt do sistema:
```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.
```
Para adaptá-lo, nomeie as tarefas no domínio do seu agente que exigem uma execução e as tarefas pequenas que o agente deve fazer por conta própria. Você também pode orientar como uma execução realiza o trabalho, como nestes exemplos:
* **Como dividir o trabalho:** "Em uma execução, use um agente por contrato. Em seguida, faça um segundo agente revisar todos os contratos, não apenas aqueles em que o primeiro agente encontrou algo, e procurar o que o primeiro agente deixou passar. Qualquer coisa que falhar na revisão é refeita e revisada novamente."
* **O que fazer quando um agente falha:** "A falha de um agente não deve fazer a execução falhar. Se um agente não conseguir ler um contrato, liste esse contrato como não coberto. Quando a execução terminar, diga-me quais contratos não foram cobertos."
* **Um limite de tempo:** "Dê à execução um limite de tempo de uma hora."
* **Planejar primeiro:** "Antes de iniciar uma execução, descreva suas fases e quantos agentes cada uma executa. Depois, aguarde minha autorização." Não há etapa de aprovação antes de uma execução começar, então nada garante isso.
Restrinja as execuções às tarefas que precisam delas, porque cada agente em uma execução usa tokens.
Em seguida, [crie uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions) com o agente, como faria com qualquer agente, e descreva o trabalho em uma `user.message`. Você também pode pedir uma execução nessa mensagem.
Para os eventos de uma execução, a interrupção de uma sessão com execuções abertas, o que muda enquanto uma execução está aberta e orçamentos e limites, consulte [Execuções de workflow](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs).
## Dar um advisor à sessão
Uma configuração `advisor` habilitada no bloco `multiagent` (csharp, go: `Multiagent`) do agente dá à thread principal da sessão um **advisor**: um modelo que ela pode consultar no meio de um turno para obter orientação estratégica, como planejar uma abordagem, sair de um impasse ou revisar o trabalho antes de concluir. A configuração é desabilitada por padrão. Para habilitá-la, defina `advisor` como `{"type": "enabled", "model": "..."}`, que tem exatamente dois campos, `type` e `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
```
Este exemplo define apenas `advisor` (csharp, go: `Advisor`). As outras duas configurações, `subagents` (csharp, go: `Subagents`) e `workflows` (csharp, go: `Workflows`), mantêm seus padrões, então ambas estão habilitadas, e o agente também pode delegar a agentes inline e iniciar execuções de workflow. Para um agente que consulta um advisor e faz todo o trabalho por conta própria, defina ambas como `{"type": "disabled"}`.
Você não pode listar o advisor na lista `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) de `subagents` (csharp, go: `Subagents`) ou de `workflows` (csharp, go: `Workflows`). Um `advisor` (csharp, go: `Advisor`) habilitado reserva o nome `anthropic.advisor`. Enquanto ele estiver habilitado, nenhuma das listas pode conter um agente literalmente chamado `anthropic.advisor`: a solicitação é rejeitada com um erro de validação 400.
O modelo advisor deve atender a um nível mínimo de capacidade, e o próprio modelo do agente não deve ser mais capaz que seu advisor; modelos de capacidade igual podem formar par. Um pareamento inválido é rejeitado com um erro de validação 400 quando o agente é salvo e novamente quando uma sessão é criada. O pareamento também é verificado quando cada consulta começa: se ele não for mais válido, essa consulta falha e a sessão continua. Os pareamentos válidos seguem a tabela de [compatibilidade de modelos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#model-compatibility) da ferramenta advisor.
O advisor também está disponível como uma [ferramenta de servidor na Messages API](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool). A superfície de Managed Agents difere em configuração e entrega: a configuração `advisor` (csharp, go: `Advisor`) não tem os campos `max_uses`, `max_tokens` ou `caching`, e o conselho chega por meio de eventos de thread em vez de blocos `advisor_tool_result`.
### Como as consultas funcionam
Cada consulta é executada como uma thread criada pela plataforma chamada `anthropic.advisor`, que se encerra quando a consulta é concluída, e o conselho é entregue à thread principal como um evento `agent.thread_message_received`. Uma consulta emite os eventos de thread padrão, identificados pelo nome reservado `anthropic.advisor` (os eventos de ciclo de vida da thread o carregam como `agent_name` (java, php: `agentName`; csharp, go: `AgentName`), e a entrega do conselho o carrega como `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`)), normalmente nesta ordem:
1. `session.thread_created`
2. `session.thread_status_running`
3. `agent.thread_message_received` (o conselho)
4. `session.thread_status_idle` (`stop_reason: end_turn`)
5. `session.thread_status_terminated`
Nenhum evento `agent.tool_use` é emitido para uma consulta, e nenhum evento `agent.thread_message_sent` aparece no fluxo de eventos da sessão, porque a entrada da consulta é composta pela plataforma em vez de enviada pelo agente. Se você listar os próprios eventos da thread do advisor, o conselho também aparece ali como um evento `agent.thread_message_sent`. Não há garantia de que a entrega do conselho (evento 3) chegue antes dos eventos de ociosidade e encerramento da thread do advisor, portanto não os trate como um sinal de que o conselho já foi entregue.
Se o seu cliente pode ler o conselho depende da política do modelo advisor. Isso espelha a divisão de [variantes de resultado](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#result-variants) na ferramenta advisor da Messages API. Um modelo advisor que retorna resultados em texto simples lá entrega texto legível aqui. Um que retorna resultados redigidos entrega um placeholder `[{"type": "redacted"}]` em todas as superfícies do cliente, enquanto o agente ainda lê o conselho completo no lado do servidor. O exemplo anterior usa como advisor o modelo Opus mais recente disponível para você. Claude Opus 5.5 retorna resultados redigidos, então seu cliente vê apenas o placeholder. Para ler o conselho no fluxo de eventos, use um advisor que retorne texto simples, como Claude Opus 4.8. A política de um modelo pode mudar sem nenhuma alteração na API, então trate tanto blocos `text` quanto `redacted`. Alguns modelos de agente só podem ser pareados com advisors de resultado redigido; consulte a [tabela de compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#model-compatibility) da ferramenta advisor. O pensamento do advisor nunca é exposto. Os clientes não podem enviar blocos `redacted` por conta própria; um evento que contenha um é rejeitado com um erro de validação 400.
Uma consulta que falha ou é interrompida nunca faz o turno do agente falhar: o agente continua após um aviso genérico de que a consulta falhou. Um `user.interrupt` no nível da sessão durante uma consulta encerra a thread do advisor sem que nenhum conselho seja entregue; um `user.interrupt` com o `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) da thread do advisor abandona apenas essa consulta.
### Threads do advisor
O advisor não é um subagente. A ferramenta `list_agents` do agente não o mostra, e `send_to_agent`, que envia uma mensagem de acompanhamento a um subagente, não consegue alcançá-lo. Apenas a thread principal da sessão pode consultá-lo; os subagentes não podem.
As threads do advisor estão isentas do limite de 25 threads filhas. Elas aparecem na [lista de threads](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads) da sessão. Seu `agent` é a forma de advisor, `{"type": "advisor", "model": ...}`, com o modelo que você configurou, e seu `parent_thread_id` é a thread principal.
O cache de prompt no lado do advisor é automático; não há nada a configurar. As consultas são cobradas pelas tarifas do modelo advisor, e seus tokens aparecem no uso da thread do advisor e nos totais de uso da sessão. Elas também contam para um [orçamento de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/budgets), pelo preço de lista do modelo advisor. Cada consulta envia ao advisor a conversa da thread principal até aquele momento, portanto consultas feitas mais tarde em uma sessão longa usam mais tokens de entrada.
### Remover o advisor
Para remover o advisor, [atualize o agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#update-an-agent) com `advisor` definido como `{"type": "disabled"}`. Em um agente que já tem o tipo `multiagent_20261001`, uma configuração que a atualização omite mantém seu valor armazenado, portanto você não precisa enviar `subagents` ou `workflows` novamente. Pelo mesmo motivo, uma atualização que omite `advisor` mantém o advisor. Antes de alterar o `multiagent.type` de um agente existente, consulte [como migrar um agente para este tipo](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#move-from-the-coordinator-type).
## Migrar do tipo `coordinator`
Assim como `multiagent_20261001`, o tipo `coordinator` permite que um agente delegue a subagentes que você lista e consulte um modelo advisor. Com o tipo `coordinator`, o agente não pode iniciar execuções de workflow nem definir subagentes por conta própria. A API aceita ambos os tipos.
Para migrar um agente para `multiagent_20261001`, [atualize o agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#update-an-agent) com um bloco `multiagent` desse tipo:
1. Defina `type` como `"multiagent_20261001"`.
2. Liste os agentes que o agente pode chamar em `subagents.predefined_agents`. As entradas mantêm a forma que têm agora.
3. Se o agente tiver um advisor, defina `advisor` como `{"type": "enabled", "model": "..."}` com o modelo do advisor.
4. Envie o bloco inteiro em uma única atualização.
Por exemplo, este bloco dá a um agente dois subagentes e um advisor:
```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" }
}
}
```
Esse bloco omite `workflows` e `subagents.inline_agents`, portanto ambos assumem seu padrão e ficam habilitados. O agente migrado também pode iniciar execuções de workflow e definir subagentes por conta própria. Para manter qualquer um deles desativado, defina-o como `{"type": "disabled"}` na mesma atualização. Consulte [Ativar workflows dinâmicos](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) e [Agentes predefinidos e inline](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#predefined-and-inline-agents).
Se o agente tiver um advisor e nenhum subagente, defina `subagents` como `{"type": "disabled"}` para manter a delegação desativada. Uma solicitação que desabilita `subagents.inline_agents` e não lista nenhum agente falha com um erro 400.
A atualização substitui o bloco `multiagent` inteiro, portanto envie novamente a lista de agentes e o advisor, como faz o exemplo. O que você omite assume seu padrão:
* **`subagents.predefined_agents`:** A lista fica vazia, portanto o agente perde os subagentes que você listou.
* **`advisor`:** O advisor é desabilitado.
Depois que o agente tiver o tipo `multiagent_20261001`, uma configuração que uma atualização posterior omitir mantém seu valor armazenado.
A atualização não altera sessões que já existem. Para usar o novo bloco, crie uma sessão após a atualização.