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

Como funciona

Todos os agentes compartilham o mesmo sandbox, sistema de arquivos e credenciais de vault, mas cada agente é executado em sua própria session thread (thread de sessão), um fluxo de eventos com contexto isolado e seu próprio histórico de conversa. O coordenador relata a atividade na primary thread (thread principal), que é a mesma que o fluxo de eventos no nível da sessão; threads adicionais são criadas em tempo de execução quando o coordenador delega trabalho.

As threads são persistentes: o coordenador pode enviar uma mensagem de acompanhamento a um agente que chamou anteriormente, e esse agente retém tudo de seus turnos anteriores.

Cada agente usa sua própria configuração: modelo, prompt do sistema, ferramentas, servidores MCP e skills. As substituições de configuração do agente no nível da sessão são a exceção; elas se aplicam ao coordenador e às suas cópias self. Ferramentas, servidores MCP e contexto não são compartilhados.

O que delegar

A coordenação multiagente é mais adequada para tarefas complexas que exigem trabalho em uma variedade de superfícies, ou nas quais múltiplas tarefas bem delimitadas contribuem para um objetivo geral.

Padrões que funcionam bem:

• Paralelização: Distribua subtarefas independentes simultaneamente (pesquisar em múltiplas fontes, analisar arquivos separados) e faça com que o coordenador sintetize os resultados.
• Especialização: Direcione 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.

Configure o coordenador

Ao definir seu agente, defina multiagent para declarar a lista de agentes aos quais o coordenador pode delegar:

ant beta:agents create < coordinator.agent.yaml

name: Engineering Lead
model: claude-opus-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: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID # replace before running command
    - type: agent
      id: $TEST_WRITER_AGENT_ID # replace before running command

multiagent.agents pode aceitar qualquer um dos seguintes:

• {"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 desse agente no momento em que o coordenador é criado.
• {"type": "agent", "id": agent.id, "version": agent.version} fixa uma versão específica do agente.
• {"type": "self"} permite que o coordenador crie cópias de si mesmo. 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; as entradas da lista referenciadas por ID não são afetadas.
• {"type": "advisor", "model": "<model id>"} dá à thread principal da sessão um advisor que ela pode consultar no meio de um turno. No máximo uma entrada de advisor por lista. Consulte Dê um advisor à sessão.

A configuração do coordenador, incluindo sua lista multiagent.agents, é capturada em um snapshot quando o coordenador é criado ou atualizado. Os agentes referenciados permanecem fixados nas versões resolvidas naquele momento e não incorporam automaticamente atualizações posteriores em suas definições. Para delegar a uma versão mais recente de um agente referenciado, atualize o coordenador para que sua lista referencie essa versão.

O coordenador só pode delegar a um nível de agentes; referenciar um agente que tenha sua própria lista multiagent.agents faz com que a solicitação de criação ou atualização falhe com um erro de validação. Um máximo de 20 agentes únicos pode ser listado em multiagent.agents, mas o coordenador pode chamar múltiplas cópias de cada agente.

Quando os agentes fixam uma geografia de inferência (model.inference_geo na definição do agente), a fixação do coordenador e a fixação de cada membro da lista devem estar todas definidas com o mesmo valor ou todas não definidas. Uma lista incompatível é rejeitada com um erro de validação 400, tanto quando o agente é salvo quanto quando uma substituição na criação da sessão altera qualquer uma das fixações.

Dê um advisor à sessão

Uma entrada de advisor em multiagent.agents dá à thread principal da sessão um advisor (conselheiro): 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 finalizar. A entrada tem exatamente dois campos, type e model:

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": "coordinator",
      "agents": [
        {"type": "advisor", "model": "claude-opus-5"}
      ]
    }
  }'

Uma lista pode conter no máximo uma entrada de advisor, junto com qualquer uma das outras formas de entrada da lista. A entrada ocupa o nome reservado anthropic.advisor na lista: uma lista que contenha tanto uma entrada de advisor quanto um membro literalmente chamado anthropic.advisor é rejeitada com um erro de validação 400. Nas respostas, a entrada de advisor é ecoada por último na lista, independentemente da posição em que foi enviada.

O modelo advisor deve atender a um patamar 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. 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 do Managed Agents difere em configuração e entrega: a entrada da lista 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 eventos da própria thread do advisor, o conselho também aparece lá como um evento agent.thread_message_sent. Não há garantia de que a entrega do conselho (evento 3) chegue antes dos eventos idle e terminated da thread do advisor, portanto não trate esses eventos como um sinal de que o conselho já foi entregue.

Se o seu cliente pode ler o conselho é uma política do modelo advisor, e isso espelha a divisão de variantes de resultado na ferramenta advisor da Messages API. Modelos advisor que retornam resultados em texto simples lá entregam o conselho como conteúdo de texto legível aqui; modelos advisor que retornam resultados redigidos lá entregam um placeholder [{"type": "redacted"}] como conteúdo da mensagem em todas as superfícies do cliente, enquanto o próprio agente ainda lê o conselho completo no lado do servidor. No exemplo anterior, o Claude Opus 5 é um advisor de resultado redigido, então seu cliente vê o placeholder enquanto o agente lê o conselho completo; escolha o Claude Opus 4.8 como advisor se quiser que o conselho seja legível no fluxo de eventos. O pensamento do advisor nunca é exposto. Os clientes não podem enviar blocos redacted por conta própria; um evento contendo um deles é rejeitado com um erro de validação 400.

Uma consulta com 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 agente da lista: ele é invisível para a ferramenta list_agents do coordenador, não pode receber mensagens via send_to_agent, e apenas a thread principal da sessão pode consultá-lo. Os agentes da lista não podem.

As threads do advisor estão isentas do limite de threads simultâneas. Elas aparecem na lista de threads da sessão com agent definido na forma de advisor exatamente como configurado ({"type": "advisor", "model": ...}) e parent_thread_id definido como 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.

Removendo o advisor

Para remover o advisor, atualize o agente com uma lista que não inclua mais a entrada de advisor. Se o advisor for a única entrada da lista, limpe a lista inteiramente definindo "multiagent": null.

Crie a sessão

Crie uma sessão referenciando o coordenador. O coordenador delega aos agentes em sua lista conforme necessário.

session = client.beta.sessions.create(
    agent=coordinator.id,
    environment_id=environment.id,
)

Conecte agentes a servidores MCP

Os servidores MCP têm escopo de agente (cada definição de agente declara seus próprios servidores e ferramentas), enquanto as credenciais de 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 de 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.

As substituições de configuração do agente na criação da sessão podem substituir os servidores MCP do coordenador e os de suas cópias self.

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-5",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

session = client.beta.sessions.create(
    agent=coordinator.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 coordenador não tem acesso. Os vault_ids da sessão fornecem a credencial do GitHub à thread do pesquisador.

Threads

O fluxo de eventos no nível da sessão (/v1/sessions/{session_id}/events/stream) é considerado a thread principal, contendo uma visão condensada de toda a atividade em todas as threads. Você não vê a atividade completa dos subagentes, mas vê o início e o fim do trabalho deles, além de eventos bloqueantes, como solicitações de permissão de ferramentas.

As threads de sessão são onde você se aprofunda na atividade de um agente específico.

O status da sessão é uma agregação de toda a atividade dos agentes; se pelo menos uma thread estiver running, então o status geral da sessão também será running.

Um orçamento de sessão é um único limite compartilhado entre todas as threads de uma sessão. À medida que o limite é atingido, as threads pausam de forma independente, e o custo de cada thread é precificado de acordo com o próprio modelo servido da thread.

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent.name}] {thread.status}")

Eventos da thread principal

Esses eventos expõem a atividade multiagente na thread principal em /v1/sessions/{session_id}/events/stream. Os eventos de direção de mensagem são nomeados em relação à thread em cujo fluxo aparecem: agent.thread_message_received significa que uma mensagem chegou a esta thread vinda de outra thread, e agent.thread_message_sent significa que esta thread enviou uma. A tarefa que o coordenador delega, por exemplo, chega ao fluxo da própria thread filha como um evento agent.thread_message_received.

As consultas ao advisor emitem esses mesmos eventos de thread sob o nome reservado anthropic.advisor (como agent_name nos eventos de ciclo de vida da thread e from_agent_name na entrega do conselho); consulte Dê um advisor à sessão para ver a sequência.

Eventos de thread de sessão

Eventos críticos são encaminhados para a thread principal. No entanto, você ainda pode querer investigar o raciocínio e as chamadas de ferramentas de um agente específico. Para isso, faça streaming ou liste os eventos da thread de sessão associada.

Cada thread de sessão tem seu próprio fluxo de eventos em /v1/sessions/{session_id}/threads/{thread_id}/stream, e ele aceita o mesmo parâmetro event_deltas[] que o fluxo no nível da sessão, para que você possa pré-visualizar o texto de um subagente à medida que o modelo o gera. Uma conexão pré-visualiza apenas a thread que está lendo: as pré-visualizações de uma thread filha nunca aparecem no fluxo no nível da sessão, portanto, para acompanhar um subagente ao vivo, abra o fluxo da própria thread dele. Consulte Pré-visualizar eventos de thread de sessão para saber como optar por participar, acumular e reconciliar pré-visualizações.

with client.beta.sessions.threads.events.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_status_idle":
                break

Permissões de ferramentas e ferramentas personalizadas

Se um subagente precisar de algo do seu cliente, como permissão para executar uma ferramenta always_ask, ou o resultado de uma ferramenta personalizada, o evento é publicado também na thread principal com session_thread_id identificando a thread de sessão de origem.

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["sevt_01XYZ..."]
  }
}

Publique user.tool_confirmation (com tool_use_id) ou user.custom_tool_result (com custom_tool_use_id); o servidor roteia a resposta para a thread correta automaticamente.

O exemplo a seguir estende o manipulador de confirmação de ferramenta para rotear respostas. O mesmo padrão se aplica a user.custom_tool_result.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )