Sessões multiagente

A orquestração multiagente permite que um agente coordene 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 reduzir o tempo de conclusão.



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 reporta 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 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 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 o coordenador sintetizar os resultados.
• Especialização: Encaminhe para agentes com prompts do sistema e ferramentas focados em domínios específicos, 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.



Configurar 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 por 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; entradas da lista referenciadas por ID não são afetadas.

A configuração do coordenador, incluindo sua lista multiagent.agents, é capturada como snapshot quando o coordenador é criado ou atualizado. Os agentes referenciados permanecem fixados nas versões resolvidas naquele momento e não recebem 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; profundidade > 1 é ignorada. 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.



Criar 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,
)



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), enquanto as credenciais de vault têm escopo de sessão (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/: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, além de eventos bloqueantes, como solicitações de permissão de ferramentas.

As threads de sessão são onde você investiga em detalhes a 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.



Eventos da thread primária

Estes eventos expõem a atividade multiagente na thread primária em /v1/sessions/:id/events/stream.



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.



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..."]
  }
}

Envie 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 handler de confirmação de ferramenta 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",
            }
        ],
    )