Orquestração multiagente

A orquestração multiagente permite que um agente se 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 do resultado e também pode melhorar o tempo de 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 thread de sessão, um fluxo de eventos com contexto isolado e com seu próprio histórico de conversa. O coordenador relata a atividade na thread primária (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 um acompanhamento para 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 de 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 onde múltiplas tarefas bem delimitadas contribuem para um objetivo geral.

Padrões que funcionam bem:

• Paralelização: Distribua subtarefas independentes simultaneamente (pesquisar múltiplas fontes, analisar arquivos separados) e faça com que o coordenador sintetize 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 sobrecarregar 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 <<YAML
name: Engineering Lead
model: claude-opus-4-8
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
    - type: agent
      id: $TEST_WRITER_AGENT_ID
YAML

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 de agente, essas substituições também se aplicam a essas cópias; as entradas da lista referenciadas por ID não são afetadas.

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



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 de 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-4-8",
    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 para a thread do pesquisador.



Threads

O fluxo de eventos no nível da sessão (/v1/sessions/{session_id}/events/stream) é considerado a thread primária, 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, e 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 é running.

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



Eventos da thread primária

Esses eventos exibem a atividade multiagente na thread primária em /v1/sessions/{session_id}/events/stream. Os eventos de direção de mensagem são nomeados em relação à thread em cujo fluxo eles aparecem: agent.thread_message_received significa que uma mensagem chegou nesta 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 no próprio fluxo da thread filha como um evento agent.thread_message_received.



Eventos de thread de sessão

Eventos críticos são encaminhados para a thread primária. 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 aceita o mesmo parâmetro event_deltas[] que o fluxo no nível da sessão, então você pode pré-visualizar o texto de um subagente conforme 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, então, para observar um subagente ao vivo, abra o fluxo da própria thread dele. Consulte Pré-visualizar eventos de thread de sessão para ativar, 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 primária 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": ["toolu_01XYZ..."]
  }
}

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

O exemplo a seguir estende o manipulador de confirmação de ferramentas para encaminhar 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",
            }
        ],
    )