Sessões multiagente

A orquestração de múltiplos agentes permite que um agente coordene com outros para completar trabalhos complexos. Os agentes podem agir em paralelo com seu próprio contexto isolado, o que ajuda a melhorar a qualidade da saída e reduzir o tempo de conclusão.

Como funciona

Todos os agentes compartilham o mesmo contêiner e sistema de arquivos, mas cada agente é executado em sua própria thread de sessão, um fluxo de eventos isolado de contexto com seu próprio histórico de conversa. O coordenador relata atividade na thread primária (que é a mesma que o fluxo de eventos no nível da sessão); threads adicionais são geradas em tempo de execução quando o coordenador decide delegar.

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 habilidades) conforme definido quando esse agente foi criado. Ferramentas e contexto não são compartilhados.

O que delegar

As sessões multiagente funcionam melhor quando há múltiplas tarefas bem definidas e especializadas em um objetivo geral:

• Revisão de código: Um agente revisor com um prompt do sistema focado e ferramentas somente leitura.
• Geração de testes: Um agente de teste que escreve e executa testes sem tocar no código de produção.
• Pesquisa: Um agente de busca com ferramentas web que resume as descobertas de volta para o coordenador.

Declare agentes chamáveis

Ao definir seu agente, liste IDs adicionais de agentes que ele tem permissão para chamar:

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-7
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
callable_agents:
  - type: agent
    id: $REVIEWER_AGENT_ID
    version: $REVIEWER_AGENT_VERSION
  - type: agent
    id: $TEST_WRITER_AGENT_ID
    version: $TEST_WRITER_AGENT_VERSION
YAML

Cada entrada em callable_agents deve ser o ID de um agente existente. Apenas um nível de delegação é suportado: o coordenador pode chamar outros agentes, mas esses agentes não podem chamar agentes próprios.

Em seguida, crie uma sessão referenciando o orquestrador:

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

Os agentes chamáveis são resolvidos a partir da configuração do orquestrador. Você não precisa referenciá-los na criação da sessão.

Threads de sessão

O fluxo de eventos no nível da sessão (/v1/sessions/:id/stream) é considerado a thread primária, contendo uma visualização condensada de toda a atividade em todas as threads. Você não verá os rastreamentos individuais dos agentes chamados, mas verá o início e o fim de seu trabalho. As threads de sessão são onde você analisa o raciocínio e as chamadas de ferramentas de um agente específico.

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

Liste todas as threads em uma sessão da seguinte forma:

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

Transmita eventos de uma thread específica:

with client.beta.sessions.threads.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_idle":
                break

Liste eventos passados para uma thread:

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

Tipos de eventos multiagente

Esses eventos exibem atividade multiagente no fluxo de sessão de nível superior.

Permissões de ferramentas e ferramentas personalizadas em threads

Quando uma thread callable_agent precisa de algo do seu cliente (permissão para executar uma ferramenta always_ask, ou o resultado de uma ferramenta personalizada) a solicitação aparece no fluxo de sessão com um campo session_thread_id. Inclua o mesmo session_thread_id quando você postar sua resposta para que a plataforma a roteie de volta para a thread em espera.

• session_thread_id está presente: o evento originou-se em uma thread de subagenente. Repita-o em sua resposta.
• session_thread_id está ausente: o evento veio da thread primária. Responda sem o campo.
• Corresponda em tool_use_id para emparelhar solicitações com respostas.

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

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])