Sesiones multiagente

La orquestación multiagente permite que un agente se coordine con otros para completar trabajos complejos. 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 la 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 utiliza su propia configuración (modelo, indicación 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 definidas y especializadas en un objetivo general:

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

Declarar agentes invocables

Al definir tu agente, lista los IDs adicionales de agentes que se le permite invocar:

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 en callable_agents debe ser el ID de un agente existente. Solo se admite un nivel de delegación: el coordinador puede invocar otros agentes, pero esos agentes no pueden invocar agentes propios.

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

session = client.beta.sessions.create(
    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 rastros individuales de los agentes invocados, 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 de 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:

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

Transmite eventos desde un thread específico:

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

Lista eventos pasados para un 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

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

Permisos de herramientas y herramientas personalizadas en threads

Cuando un thread 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 manejador de confirmación de herramientas para enrutar respuestas. El mismo patrón 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])