Sesiones multiagente

La orquestación multiagente permite que un agente se coordine con otros para completar trabajo complejo. Los agentes pueden actuar en paralelo con su propio contexto aislado, lo que ayuda a mejorar la calidad del resultado y reduce el tiempo de finalización.

Cómo funciona

Todos los agentes comparten el mismo contenedor y sistema de archivos, pero cada agente se ejecuta en su propia sesión thread, un flujo de eventos aislado en contexto con su propio historial de conversación. El coordinador reporta actividad en el thread primario (que es lo mismo que el flujo de eventos a nivel de sesión); los threads adicionales se generan en tiempo de ejecución cuando el coordinador decide delegar.

Los threads son persistentes: el coordinador puede enviar un seguimiento a un agente al que llamó anteriormente, y ese agente retiene todo de sus turnos anteriores.

Cada agente usa su propia configuración (modelo, prompt del sistema, herramientas, servidores MCP y habilidades) tal como se definió cuando se creó ese agente. Las herramientas y el contexto no se comparten.

Qué delegar

Las sesiones multiagente funcionan mejor cuando hay múltiples tareas bien delimitadas y especializadas en un objetivo general:

• Revisión de código: Un agente revisor con un prompt del sistema enfocado y herramientas de solo lectura.
• Generación de pruebas: Un agente de pruebas que escribe y ejecuta pruebas sin tocar código de producción.
• Investigación: Un agente de búsqueda con herramientas web que resume hallazgos de vuelta al coordinador.

Declara agentes invocables

Cuando defines tu agente, lista IDs adicionales de agentes que se le permite invocar:

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
)

Cada entrada en callable_agents debe ser el ID de un agente existente. Solo se admite un nivel de delegación: el coordinador puede llamar a otros agentes, pero esos agentes no pueden llamar a agentes propios.

Luego crea una sesión que haga referencia al orquestador:

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'"}')

Los agentes invocables se resuelven desde la configuración del orquestador. No necesitas hacer referencia a ellos en la creación de la sesión.

Threads de sesión

El flujo de eventos a nivel de sesión (/v1/sessions/:id/stream) se considera el thread primario, que contiene una vista condensada de toda la actividad en todos los threads. No verás los rastreos individuales de los agentes llamados, pero verás el inicio y el final de su trabajo. Los threads de sesión son donde profundizas en el razonamiento y las llamadas a herramientas de un agente específico.

El estado de la sesión también es una agregación de toda la actividad del agente; si al menos un thread está running, entonces el estado general de la sesión también será running.

Lista todos los threads en una sesión de la siguiente manera:

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)"'

Transmite eventos desde un thread específico:

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

Lista eventos pasados para un thread:

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)"'

Tipos de eventos multiagente

Estos eventos muestran actividad multiagente en el flujo de sesión de nivel superior.

Permisos de herramientas y herramientas personalizadas en threads

Cuando un thread de callable_agent necesita algo de tu cliente (permiso para ejecutar una herramienta always_ask, o el resultado de una herramienta personalizada) la solicitud aparece en el flujo de sesión con un campo session_thread_id. Incluye el mismo session_thread_id cuando publiques tu respuesta para que la plataforma la enrute de vuelta al thread en espera.

• session_thread_id está presente: el evento se originó en un thread de subagente. Repítelo en tu respuesta.
• session_thread_id está ausente: el evento provino del thread primario. Responde sin el campo.
• Coincide en tool_use_id para emparejar solicitudes con respuestas.

El ejemplo a continuación extiende el controlador de confirmación de herramientas para enrutar respuestas. El mismo patrón se aplica a user.custom_tool_result.

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