Orquestração multiagente

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).

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. 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 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.

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:

{
  "multiagent": { "type": "multiagent_20261001" }
}

Para definir quais agentes o agente pode chamar, consulte Agentes predefinidos e inline. Para desativar uma configuração, consulte Ativar workflows dinâmicos.

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 e que você lista no bloco 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:

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, 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.

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:

{
  "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.

Como funciona

Todos os agentes compartilham o mesmo sandbox, sistema de arquivos e credenciais do vault, 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 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. As substituições de configuração do agente 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, defina a lista predefined_agents de subagents no bloco multiagent para listar os agentes aos quais ele pode delegar:

ant apply engineering-lead.md reviewer.md test-writer.md

---
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.

---
name: reviewer
model: claude-haiku-5-5
---

You are a code reviewer.

---
name: test-writer
model: claude-haiku-5-5
---

You write unit tests.

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 de subagents assume, consulte Agentes predefinidos e inline.

"advisor": {"type": "enabled", "model": "<model id>"} dá à thread principal da sessão um advisor que ela pode consultar no meio do turno. O advisor é uma configuração no bloco multiagent, não uma entrada nesta lista. Consulte Dar um advisor à sessão.

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.

As regras a seguir se aplicam aos agentes que você lista em predefined_agents de subagents, e também aos agentes que você lista em predefined_agents de workflows:

• Fixação: A configuração do agente, incluindo a lista predefined_agents de 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 para que a lista predefined_agents de 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 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 de subagents pode listar até 20 agentes únicos. O limite é por lista: a lista predefined_agents de workflows também pode listar até 20. O agente pode chamar várias cópias de cada subagente, dentro do limite de threads da sessão.
• Geografia de inferência: O agente e cada agente que você lista, na lista predefined_agents de subagents ou de workflows, devem fixar a mesma geografia de inferência (inference_geo no model da definição do agente), 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 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 de subagents conforme necessário. Ele também pode delegar a agentes inline, a menos que você os desative.

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 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 tanto em subagents quanto em workflows, e liste pelo menos um agente em cada. Consulte Agentes predefinidos e inline.

As substituições de configuração do agente 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 limited, a criação da sessão falha com um erro 400 quando o agente, ou um agente que você lista em predefined_agents de subagents ou de workflows, declara um servidor MCP cujo host não está em allowed_hosts. Definir allow_mcp_servers 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:

ant apply lead.md researcher.md

---
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
---

---
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
---

Em seguida, crie a sessão com o vault que contém a credencial do GitHub:

session = client.beta.sessions.create(
    agent=lead_agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
print(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 da sessão fornecem a credencial do GitHub à thread do pesquisador.

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.

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 no bloco 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 que o workflow define, agentes predefinidos que você lista em predefined_agents de 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 de 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 que você pode listar, ler e acompanhar via streaming. Consulte Execuções de workflow para ver os eventos, interrupções, limites e o que as threads de uma execução mostram.

Ativar workflows dinâmicos

Ao definir seu agente, 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.

ant apply contract-reviewer.md

---
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.

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. Para definir um advisor, consulte Dar um advisor à sessão. Este agente permite que um workflow use um agente que você criou, lista dois subagentes e tem um advisor:

{
  "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:

Para saber o que vai em cada lista e como permitir apenas os agentes que você lista, consulte Agentes predefinidos e inline.

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 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 definido não pode ser listado como subagente de outro agente, nem na lista predefined_agents de 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 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.
• Orçamento: Defina um orçamento de sessão 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.

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 usa este prompt do sistema:

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 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.

Dar um advisor à sessão

Uma configuração advisor habilitada no bloco 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:

ant apply backend-engineer.md

---
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.

Este exemplo define apenas advisor. As outras duas configurações, subagents e 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 de subagents ou de workflows. Um 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 da ferramenta advisor.

O advisor também está disponível como uma ferramenta de servidor na Messages API. A superfície de Managed Agents difere em configuração e entrega: a configuração 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, e a entrega do conselho o carrega como from_agent_name), 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 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 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 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 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, 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 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.

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 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:

{
  "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 e Agentes predefinidos e inline.

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.