Orquestación 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 también puede mejorar el tiempo de finalización.

¿No estás seguro de que una configuración multiagente se ajuste a tu problema? Consulta cuándo usar sistemas multiagente (y cuándo no).



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 hilo de sesión (session thread), un flujo de eventos con contexto aislado y su propio historial de conversación. El coordinador reporta la actividad en el hilo principal (primary thread), 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 seguimiento a un agente al que llamó anteriormente, y ese agente conserva todo de sus turnos anteriores.

Cada agente usa su propia configuración: modelo, indicación del sistema, herramientas, servidores MCP y habilidades. Las anulaciones de configuración de 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 simultáneamente (buscar en múltiples fuentes, analizar archivos separados) y haz que el coordinador sintetice los resultados.
• Especialización: Dirige 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.



Configura 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 ID. Si no se especifica una version, la referencia se fija a la última versión 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 anulaciones de configuración de agente, esas anulaciones 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; hacer referencia a un agente que tiene su propia lista multiagent.agents hace que la solicitud de creación o actualización falle con un error de validación. 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.



Crea 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,
)



Conecta 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 anulaciones de configuración de 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/{session_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.

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



Eventos del hilo principal

Estos eventos muestran la actividad multiagente en el hilo principal en /v1/sessions/{session_id}/events/stream. Los eventos de dirección de mensaje se nombran en relación con el hilo en cuyo flujo aparecen: agent.thread_message_received significa que un mensaje llegó a este hilo desde otro hilo, y agent.thread_message_sent significa que este hilo envió uno. La tarea que delega el coordinador, por ejemplo, llega al flujo propio del hijo como un evento agent.thread_message_received.



Eventos de hilo de sesión

Los eventos críticos se transmiten 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 o lista los eventos del hilo de sesión asociado.

Cada hilo de sesión tiene su propio flujo de eventos en /v1/sessions/{session_id}/threads/{thread_id}/stream, y acepta el mismo parámetro event_deltas[] que el flujo a nivel de sesión, por lo que puedes previsualizar el texto de un subagente a medida que el modelo lo genera. Una conexión previsualiza solo el hilo que está leyendo: las previsualizaciones de un hilo hijo nunca aparecen en el flujo a nivel de sesión, así que para observar un subagente en vivo, abre su propio flujo de hilo. Consulta Previsualizar eventos de hilo de sesión para habilitar, acumular y reconciliar previsualizaciones.

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



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 de forma cruzada 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..."]
  }
}

Publica 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 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",
            }
        ],
    )