Sessões multiagente

Multiagente é um recurso de Pré-visualização de Pesquisa. Solicite acesso para experimentar.

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 o tempo de conclusão.

Todas as solicitações da API de Agentes Gerenciados requerem o cabeçalho beta managed-agents-2026-04-01. Um cabeçalho beta adicional é necessário para recursos de pré-visualização de pesquisa. O SDK define esses cabeçalhos beta automaticamente.

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 com contexto isolado com seu próprio histórico de conversas. O coordenador relata atividades 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 decide delegar.

As threads são persistentes: o coordenador pode enviar um 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 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 de sistema focado e ferramentas somente leitura.
Geração de testes: Um agente de testes que escreve e executa testes sem tocar no código de produção.
Pesquisa: Um agente de busca com ferramentas web que resume os resultados para o coordenador.

Declarar agentes chamáveis

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

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:

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 visão condensada de toda a atividade em todas as threads. Você não verá os rastros individuais dos agentes chamados, mas verá o início e o fim de seu trabalho. As threads de sessão são onde você aprofunda 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 dos agentes; 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:

Transmita eventos de uma thread específica:

Liste eventos passados de uma thread:

Tipos de eventos multiagente

Esses eventos expõem a atividade multiagente no fluxo de sessão de nível superior.

Tipo	Descrição
`session.thread_created`	O coordenador criou uma nova thread. Inclui o `session_thread_id` e o `model`.
`session.thread_idle`	Uma thread de agente concluiu seu trabalho atual.
`agent.thread_message_sent`	Um agente enviou uma mensagem para outra thread. Inclui `to_thread_id` e `content`.
`agent.thread_message_received`	Um agente recebeu uma mensagem de outra thread. Inclui `from_thread_id` e `content`.

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 ao 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 subagente. Repita-o na sua resposta.
session_thread_id está ausente: o evento veio da thread primária. Responda sem o campo.
Combine em tool_use_id para parear solicitações com respostas.

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

orchestrator=$(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 @- <<EOF
{
  "name": "Engineering Lead",
  "model": "claude-sonnet-4-6",
  "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}
  ]
}
EOF
)

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -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 '{"agent": "'$ORCHESTRATOR_ID'", "environment_id": "'$ENVIRONMENT_ID'"}')

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.agent_name)] \(.status)"'

curl -fsSN "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" |
  while IFS= read -r line; do
    [[ $line == data:* ]] || continue
    json=${line#data: }
    case $(jq -r '.type' <<<"$json") in
      agent.message)
        printf '%s' "$(jq -j '.content[] | select(.type == "text") | .text' <<<"$json")"
        ;;
      session.thread_idle)
        break
        ;;
    esac
  done

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.type)] \(.processed_at)"'

while IFS= read -r event_id; do
  pending=$(jq -r --arg id "$event_id" '.[$id]' <<<"$events_by_id")
  thread_id=$(jq -r '.session_thread_id // empty' <<<"$pending")
  jq -n --arg id "$event_id" --arg thread "$thread_id" '
    {events: [
      {type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}
      + (if $thread != "" then {session_thread_id: $thread} else {} end)
    ]}' |
    curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
      -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 @-
done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")