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 de los resultados y también puede reducir el tiempo de finalización.



Cómo funciona

Todos los agentes comparten el mismo sandbox, sistema de archivos y credenciales de vault, pero cada agente se ejecuta en su propio session thread (hilo de sesión), un flujo de eventos con contexto aislado y su propio historial de conversación. El coordinador reporta la actividad en el hilo principal (que es el mismo que el flujo de eventos a nivel de sesión); los hilos adicionales se generan en tiempo de ejecución cuando el coordinador delega trabajo.

Los hilos son persistentes: el coordinador puede enviar un mensaje de seguimiento a un agente al que llamó anteriormente, y ese agente conserva todo lo de sus turnos previos.

Cada agente usa su propia configuración: modelo, indicación del sistema, herramientas, servidores MCP y skills. Las sobrescrituras de configuración del agente a nivel de sesión son la excepción; se aplican al coordinador y a sus copias self. Las herramientas, los servidores MCP y el contexto no se comparten.



Qué delegar

La coordinación multiagente es más adecuada para tareas complejas que requieren trabajo en una variedad de superficies, o donde múltiples tareas bien delimitadas contribuyen a un objetivo general.

Patrones que funcionan bien:

• Paralelización: Distribuye subtareas independientes de forma simultánea (buscar en múltiples fuentes, analizar archivos separados) y haz que el coordinador sintetice los resultados.
• Especialización: Dirige el trabajo a agentes con indicaciones del sistema y herramientas enfocadas en un dominio, como un agente de seguridad o un agente de documentación, en lugar de cargar un solo agente con todas las capacidades.
• Escalamiento: Consulta a un agente o modelo más capaz para un subconjunto de subtareas complejas.



Configurar el coordinador

Al definir tu agente, establece multiagent para declarar la lista de agentes a los que el coordinador puede 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 puede aceptar cualquiera de los siguientes:

• {"type": "agent", "id": agent.id} hace referencia a un agent creado previamente por su ID. Si no se especifica version, la referencia queda fijada a la versión más reciente de ese agente en el momento en que se crea el coordinador.
• {"type": "agent", "id": agent.id, "version": agent.version} fija una versión específica del agente.
• {"type": "self"} permite que el coordinador genere copias de sí mismo. Si la sesión se creó con sobrescrituras de configuración del agente, esas sobrescrituras también se aplican a estas copias; las entradas de la lista referenciadas por ID no se ven afectadas.

La configuración del coordinador, incluida su lista multiagent.agents, se captura como instantánea cuando el coordinador se crea o actualiza. Los agentes referenciados permanecen fijados a las versiones resueltas en ese momento y no adoptan automáticamente actualizaciones posteriores de sus definiciones. Para delegar a una versión más reciente de un agente referenciado, actualiza el coordinador para que su lista haga referencia a esa versión.

El coordinador solo puede delegar a un nivel de agentes; una profundidad > 1 se ignora. Se puede listar un máximo de 20 agentes únicos en multiagent.agents, pero el coordinador puede llamar a múltiples copias de cada agente.



Crear la sesión

Crea una sesión que haga referencia al coordinador. El coordinador delega a los agentes de su lista según sea necesario.

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



Conectar agentes a servidores MCP

Los servidores MCP tienen alcance de agente (cada definición de agente declara sus propios servidores y herramientas), mientras que las credenciales de vault tienen alcance de sesión (los vault_ids pasados al crear la sesión se aplican a todos los hilos). Dos implicaciones para tu integración:

• Para autenticar servidores MCP, incluye una credencial de vault para cada servidor MCP usado en todos los agentes.
• Para limitar el acceso de un agente, declara solo los servidores que necesita en su definición de agente.

Las sobrescrituras de configuración del agente al crear la sesión pueden reemplazar los servidores MCP del coordinador y los de sus copias 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)

En este ejemplo, solo el investigador declara el servidor MCP de GitHub, por lo que el coordinador no tiene acceso. Los vault_ids de la sesión proporcionan la credencial de GitHub al hilo del investigador.



Hilos

El flujo de eventos a nivel de sesión (/v1/sessions/:id/events/stream) se considera el hilo principal, que contiene una vista condensada de toda la actividad en todos los hilos. No ves la actividad completa de los subagentes, pero sí ves el inicio y el final de su trabajo, y los eventos bloqueantes como las solicitudes de permiso de herramientas.

Los hilos de sesión son donde profundizas en la actividad de un agente específico.

El status de la sesión es una agregación de toda la actividad de los agentes; si al menos un hilo está en running, entonces el estado general de la sesión también es running.



Eventos del hilo principal

Estos eventos muestran la actividad multiagente en el hilo principal en /v1/sessions/:id/events/stream.



Eventos del hilo de sesión

Los eventos críticos se reenvían al hilo principal. Sin embargo, es posible que aún quieras investigar el razonamiento y las llamadas de herramientas de un agente específico. Para hacerlo, transmite por streaming o lista los eventos del hilo de sesión asociado.



Permisos de herramientas y herramientas personalizadas

Si un subagente necesita algo de tu cliente, como permiso para ejecutar una herramienta always_ask, o el resultado de una herramienta personalizada, el evento se publica también en el hilo principal con session_thread_id identificando el hilo de sesión de origen.

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

Envía user.tool_confirmation (con tool_use_id) o user.custom_tool_result (con custom_tool_use_id); el servidor enruta la respuesta al hilo correcto automáticamente.

El siguiente ejemplo extiende el manejador de confirmación de herramientas para enrutar las respuestas. El mismo patrón 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",
            }
        ],
    )