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

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

Delegar trabajo a otros agentes

El agente que ejecuta una sesión puede delegar trabajo a otros agentes de dos maneras. Con los subagents (subagentes), delega tareas por sí mismo y lee lo que informa cada subagente. Con los dynamic workflows (flujos de trabajo dinámicos), escribe un flujo de trabajo: un programa que ejecuta muchos agentes en segundo plano y combina sus resultados. También puede consultar a un modelo advisor (asesor) para obtener orientación mientras hace el trabajo por sí mismo.

Tú decides cuáles de estos puede usar el agente, y el agente determina cuándo usarlos. Para orientar esa elección, indícale al agente en su indicación del sistema cuándo usar una ejecución de flujo de trabajo. Consulta Indicarle al agente cuándo usar una ejecución. También puedes limitar al agente a los agentes que enumeres.

Con los subagentes, el propio agente determina qué sucede a continuación. El hilo de un subagente permanece disponible hasta que lo archives, por lo que el agente puede enviarle mensajes de seguimiento. Con los flujos de trabajo dinámicos, Claude escribe un programa para orquestar agentes sin la participación directa de Claude. El contexto y los resultados se pasan programáticamente de un agente a otro, lo que libera el hilo principal de la sesión para comunicarse con el usuario y revisar uno o varios flujos de trabajo en ejecución para informar sobre su progreso. El agente no puede enviar mensajes de seguimiento a los hilos de una ejecución, y el servidor archiva cada uno al final de su ejecución.

Configuras esto en el bloque multiagent de la definición del agente, que tiene un type. Con el tipo multiagent_20261001, un agente puede usar los tres a la vez, y puedes activar o desactivar cada uno. De forma predeterminada, subagents y workflows están habilitados. subagents y workflows tienen cada uno inline_agents habilitado, la configuración para agentes que el propio agente o un flujo de trabajo define:

{
  "multiagent": { "type": "multiagent_20261001" }
}

Para establecer a qué agentes puede llamar el agente, consulta Agentes predefinidos e inline. Para desactivar una configuración, consulta Activar los flujos de trabajo dinámicos.

Agentes predefinidos e inline

Cada subagente, y cada agente de una ejecución de flujo de trabajo, es de uno de dos tipos:

• Agente predefinido: Un agente que ya has creado y que enumeras en el bloque multiagent. Usa su propia configuración: modelo, indicación del sistema, herramientas, servidores MCP y skills.
• Agente inline: Un agente que no está guardado. El agente que ejecuta la sesión, o un flujo de trabajo, lo define cuando reparte el trabajo. Usa el modelo, las herramientas, los servidores MCP y las skills de ese agente.

Ambos tipos funcionan bajo subagents y bajo workflows:

subagents.predefined_agents y workflows.predefined_agents son dos listas separadas. Un agente de una lista no se agrega a la otra. Ambas listas están vacías de forma predeterminada. Una entrada de cualquiera de las listas adopta una de estas formas:

• {"type": "agent", "id": agent.id} hace referencia a un agent creado previamente por su ID. Si no se especifica version, la referencia se fija a la versión más reciente del agente cuando se crea el agente que lo enumera, o cuando una actualización envía la lista.
• {"type": "agent", "id": agent.id, "version": agent.version} fija una versión específica del agente.
• agent.id por sí solo, como cadena, es una forma abreviada de {"type": "agent", "id": agent.id}.
• {"type": "self"} enumera al propio agente, para que copias de él puedan hacer el trabajo. Si la sesión se creó con anulaciones de configuración del agente, esas anulaciones también se aplican a estas copias. Las entradas referenciadas por ID no se ven afectadas.

Las reglas para estas entradas, y para los agentes que nombran, se aplican a ambas listas. Consulta Enumerar los subagentes.

Los agentes inline están activados de forma predeterminada en ambas configuraciones. Para permitir solo los agentes que enumeras, establece inline_agents en {"type": "disabled"} bajo subagents, bajo workflows o bajo ambos. Una configuración con los agentes inline desactivados necesita al menos un agente en su lista predefined_agents. Con una lista vacía, la solicitud falla con un error 400. En una actualización, el servidor verifica la configuración tal como queda después de la actualización.

El siguiente agente permite solo los agentes que enumera. Puede delegar a un agente y a copias de sí mismo, y un flujo de trabajo puede usar la versión 2 de otro agente:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
    },
    "workflows": {
      "type": "enabled",
      "inline_agents": { "type": "disabled" },
      "predefined_agents": [
        { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
      ]
    }
  }
}

Delegar a subagentes

Qué delegar

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

Patrones que funcionan bien:

• Paralelización: Distribuye subtareas independientes simultáneamente (buscar en varias fuentes, analizar archivos separados) y haz que el agente 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 a un solo agente con todas las capacidades.
• Escalamiento: Consulta a un agente o modelo más capaz para un subconjunto de subtareas complejas. Para consultar a un modelo, dale un asesor a la sesió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 hilo de sesión, un flujo de eventos con contexto aislado y su propio historial de conversación. El agente que ejecuta la sesión informa su actividad en el hilo principal, que es el flujo de eventos a nivel de sesión. Se generan hilos adicionales en tiempo de ejecución cuando delega trabajo. Una ejecución de flujo de trabajo también crea hilos.

El hilo de un subagente es persistente. El agente puede enviar un seguimiento a un subagente al que llamó antes, y ese subagente conserva todo lo de sus turnos anteriores.

La configuración que usa un subagente depende de si es un agente predefinido o inline. Las anulaciones de configuración del agente a nivel de sesión se aplican al agente que ejecuta la sesión y a sus copias self. Cada agente conserva su propio historial de conversación.

Enumerar los subagentes

Al definir tu agente, establece la lista predefined_agents de subagents en el bloque multiagent para enumerar los agentes a los que puede delegar:

ant apply engineering-lead.md reviewer.md test-writer.md

---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./reviewer.md
      - ./test-writer.md
---

You coordinate engineering work. Delegate code review to the reviewer agent
and test writing to the test agent.

---
name: reviewer
model: claude-haiku-5-5
---

You are a code reviewer.

---
name: test-writer
model: claude-haiku-5-5
---

You write unit tests.

El agente también puede delegar a agentes inline a menos que los desactives. Para esa configuración, y para las formas que adopta una entrada de la lista predefined_agents de subagents, consulta Agentes predefinidos e inline.

"advisor": {"type": "enabled", "model": "<model id>"} le da al hilo principal de la sesión un asesor que puede consultar a mitad de turno. El asesor es una configuración del bloque multiagent, no una entrada de esta lista. Consulta Darle un asesor a la sesión.

Los flujos de trabajo dinámicos también están habilitados de forma predeterminada con este tipo, por lo que este agente puede planificar trabajo de gran tamaño que ejecuta muchos agentes en segundo plano. Para desactivarlos, o para enumerar agentes que un flujo de trabajo puede usar, consulta Activar los flujos de trabajo dinámicos.

Las siguientes reglas se aplican a los agentes que enumeras en la lista predefined_agents de subagents, y también a los agentes que enumeras en la lista predefined_agents de workflows:

• Fijación: La configuración del agente, incluida la lista predefined_agents de subagents, se captura como instantánea cuando el agente se crea o se actualiza. Los agentes referenciados permanecen fijados a las versiones resueltas en ese momento y no adoptan actualizaciones posteriores de sus definiciones. Una actualización que no envía la lista conserva las versiones que ya están fijadas. Para delegar a una versión más reciente de un agente referenciado, actualiza el agente para que la lista predefined_agents de subagents haga referencia a esa versión.
• Un nivel: El agente puede delegar solo a un nivel de agentes. Hacer referencia a otro agente que tenga multiagent configurado hace que la solicitud de creación o actualización falle con un error de validación 400.
• Hasta 20 agentes: La lista predefined_agents de subagents puede enumerar hasta 20 agentes únicos. El límite es por lista: la lista predefined_agents de workflows también puede enumerar hasta 20. El agente puede llamar a varias copias de cada subagente, dentro del límite de hilos de la sesión.
• Geografía de inferencia: El agente y cada agente que enumeras, en la lista predefined_agents de subagents o de workflows, deben fijar la misma geografía de inferencia (inference_geo en el model de la definición del agente), o ninguno de ellos puede fijar una. Una discrepancia en cualquiera de las listas se rechaza con un error de validación 400. Esa verificación se ejecuta tanto cuando se guarda el agente como cuando una anulación al crear la sesión cambia cualquiera de las fijaciones.

Crear la sesión

Crea una sesión que haga referencia al agente. El agente delega a los agentes que enumeras en la lista predefined_agents de subagents según sea necesario. También puede delegar a agentes inline a menos que los desactives.

session = client.beta.sessions.create(
    agent=lead_agent.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. Un agente inline no tiene definición de agente, por lo que usa los servidores MCP y las herramientas del agente que ejecuta la sesión. 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 los servidores MCP, incluye una credencial de vault para cada servidor MCP que use cualquiera de tus agentes.
• Para limitar el acceso de un agente, declara solo los servidores que necesita en su definición de agente. No puedes limitar un agente inline de esta manera. Para permitir solo los agentes que enumeras, deshabilita inline_agents tanto en subagents como en workflows, y enumera al menos un agente en cada uno. Consulta Agentes predefinidos e inline.

Las anulaciones de configuración del agente al crear la sesión pueden reemplazar los servidores MCP del agente que ejecuta la sesión y los de sus copias self.

Con un entorno limited, la creación de la sesión falla con un error 400 cuando el agente, o un agente que enumeras en la lista predefined_agents de subagents o workflows, declara un servidor MCP cuyo host no está en allowed_hosts. Establecer allow_mcp_servers en true en la configuración de red del entorno desactiva esta verificación.

Crea el investigador, que declara el servidor MCP de GitHub, y el agente que delega al investigador:

ant apply lead.md researcher.md

---
name: lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  subagents:
    type: enabled
    predefined_agents: # ant apply replaces each path with {type: agent, id, version}
      - ./researcher.md
---

---
name: researcher
model: claude-haiku-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: mcp_toolset
    mcp_server_name: github
---

Luego crea la sesión con el vault que contiene la credencial de GitHub:

session = client.beta.sessions.create(
    agent=lead_agent.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 agente que ejecuta la sesión no tiene acceso. Los vault_ids de la sesión proporcionan la credencial de GitHub al hilo del investigador.

Hilos

El hilo de sesión de cada agente tiene su propio flujo de eventos. Para listar, interrumpir o archivar hilos, leer sus eventos y gestionar los permisos de herramientas entre ellos, consulta Hilos de sesión.

Flujos de trabajo dinámicos

Con los flujos de trabajo dinámicos, un agente puede asumir trabajo con muchas partes, como revisar cientos de documentos o verificar de forma cruzada muchas fuentes. El agente escribe un workflow (flujo de trabajo): un programa que ejecuta muchos agentes en fases y combina lo que devuelven. El servidor lo ejecuta en segundo plano como una workflow run (ejecución de flujo de trabajo), mientras el agente sigue trabajando o termina su turno. Activas o desactivas los flujos de trabajo dinámicos con la configuración workflows en el bloque multiagent del agente. Los agentes de una ejecución pueden trabajar al mismo tiempo, por lo que una tarea larga puede terminar antes que si un solo agente hiciera cada parte una tras otra.

• Cómo comienza una ejecución: Describes el trabajo en un user.message. A partir de eso, el agente determina si iniciar una ejecución y cuándo, por lo que no hay ninguna llamada adicional a la API. En cambio, influyes en la determinación del agente describiendo cuándo usar una ejecución en user.message o en la indicación del sistema del agente. (Las políticas de permisos se aplican a las herramientas que llaman los agentes de una ejecución, no al inicio de la ejecución).
• Qué agentes usa: Agentes inline que define el flujo de trabajo, agentes predefinidos que enumeras en la lista predefined_agents de workflows, o ambos. Si no enumeras ninguno, el flujo de trabajo los define todos. Un agente inline usa el modelo del agente que ejecuta la sesión. Para permitir que una ejecución use otro modelo para algunos de sus agentes, créalos como agentes y enuméralos en la lista predefined_agents de workflows.
• Cómo la sigues: Los eventos de la ejecución llegan al flujo de eventos de la sesión, y cada agente de la ejecución trabaja en un hilo de sesión que puedes listar, leer y transmitir por streaming. Consulta Ejecuciones de flujos de trabajo para conocer los eventos, las interrupciones, los límites y lo que muestran los hilos de una ejecución.

Activar los flujos de trabajo dinámicos

Al definir tu agente, establece multiagent.type en "multiagent_20261001" y habilita workflows. Los flujos de trabajo dinámicos y la delegación (subagents) están activados de forma predeterminada con este tipo. Para usar solo flujos de trabajo dinámicos, agrega "subagents": {"type": "disabled"}.

Antes de cambiar el multiagent.type de un agente existente, consulta cómo mover un agente a este tipo.

ant apply contract-reviewer.md

---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: multiagent_20261001
  workflows:
    type: enabled
---

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Para permitir que un flujo de trabajo use agentes que ya creaste, enuméralos en workflows.predefined_agents. Las configuraciones subagents y advisor van en el mismo bloque multiagent. Para enumerar subagentes, consulta Delegar a subagentes. Para configurar un asesor, consulta Darle un asesor a la sesión. Este agente permite que un flujo de trabajo use un agente que creaste, enumera dos subagentes y tiene un asesor:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": {
      "type": "enabled",
      "predefined_agents": [{ "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h" }]
    },
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Cada configuración se habilita o deshabilita por separado:

Para saber qué va en cada lista y cómo permitir solo los agentes que enumeras, consulta Agentes predefinidos e inline.

Ten en cuenta lo siguiente:

• Actualización: Una actualización que mantiene el tipo multiagent_20261001 cambia solo lo que envía:
  • Una configuración o un campo que omites conserva su valor almacenado.
  • Una configuración o un campo que envías como null toma su valor predeterminado, al igual que todo lo que contiene, sin importar lo que tuvieras almacenado.
  • Una lista predefined_agents que envías reemplaza la lista almacenada.
  • Una configuración que envías con un type diferente reemplaza la configuración almacenada, y los campos que omites en ella toman sus valores predeterminados.
  • Cada objeto que envías necesita su type, y un advisor habilitado necesita su model.
• Desactivación: Establece workflows en {"type": "disabled"}. Permanece desactivado hasta que una actualización lo vuelva a activar. Enviar null lo activa, porque su valor predeterminado es habilitado. Lo mismo aplica a subagents.
• Sesiones existentes: Una sesión copia la configuración cuando se crea, por lo que cambiar el agente después no cambia una sesión que ya existe.
• Agentes que puedes enumerar: Un agente que tiene multiagent configurado no puede enumerarse como subagente de otro agente, ni en la lista predefined_agents de workflows en otro agente. Un agente puede enumerarse a sí mismo en cualquiera de las dos listas con {"type": "self"}, que se devuelve como su propio id y version.
• Nombres de herramientas: El prefijo ant__ está reservado. Si tu agente ya tiene una herramienta personalizada cuyo nombre comienza con ant__, una actualización falla con un error 400 hasta que envíes tools sin ese nombre. Una nueva sesión también se rechaza con un error 400 si su agente, o un agente en cualquiera de las listas, tiene una herramienta así. Cambia el nombre de la herramienta o elimínala en la misma actualización que activa los flujos de trabajo dinámicos. Consulta Herramientas personalizadas.
• Presupuesto: Establece un presupuesto de sesión al crear la sesión para limitar el gasto de la sesión, incluidas las ejecuciones; no puedes agregar uno a una sesión existente. Las ejecuciones se pausan cuando la sesión alcanza el presupuesto, y las ejecuciones que el presupuesto pausó se reanudan cuando lo aumentas o lo eliminas, a menos que una interrupción también las haya pausado. Consulta Costo y presupuestos.

Indicarle al agente cuándo usar una ejecución

Activar los flujos de trabajo dinámicos le da al agente la capacidad de iniciar ejecuciones de flujos de trabajo. El agente determina cuándo iniciar una. Para orientar esa decisión, agrega una instrucción como la siguiente a la indicación del sistema del agente. El agente de revisión de contratos de Activar los flujos de trabajo dinámicos usa esta indicación del sistema:

You review contracts. When you're asked to review more than a few contracts, start a workflow run that reads them in parallel and combines the findings. Review one or two contracts yourself, without a run.

Para adaptarla, nombra las tareas del dominio de tu agente que requieren una ejecución y las tareas pequeñas que el agente debe hacer por sí mismo. También puedes orientar cómo una ejecución realiza el trabajo, como en estos ejemplos:

• Cómo dividir el trabajo: "En una ejecución, usa un agente por contrato. Luego haz que un segundo agente revise cada contrato, no solo aquellos en los que el primer agente encontró algo, y busque lo que el primer agente pasó por alto. Todo lo que no pase la revisión se rehace y se revisa de nuevo."
• Qué hacer cuando un agente falla: "Que un agente falle no debe hacer fallar la ejecución. Si un agente no logra leer un contrato, marca ese contrato como no cubierto. Cuando termine la ejecución, dime qué contratos no se cubrieron."
• Un límite de tiempo: "Dale a la ejecución un límite de tiempo de una hora."
• Planifica primero: "Antes de iniciar una ejecución, describe sus fases y cuántos agentes ejecuta cada una. Luego espera mi aprobación." No hay un paso de aprobación antes de que comience una ejecución, así que nada hace cumplir esto.

Limita las ejecuciones a las tareas que las necesitan, porque cada agente en una ejecución usa tokens.

Luego crea una sesión con el agente, como lo harías con cualquier agente, y describe el trabajo en un user.message. También puedes pedir una ejecución en ese mensaje.

Para conocer los eventos de una ejecución, cómo interrumpir una sesión con ejecuciones abiertas, qué cambia mientras una ejecución está abierta, y los presupuestos y límites, consulta Ejecuciones de flujos de trabajo.

Darle un asesor a la sesión

Una configuración advisor habilitada en el bloque multiagent del agente le da al hilo principal de la sesión un asesor: un modelo que puede consultar a mitad de turno para obtener orientación estratégica, como planificar un enfoque, desatascarse o revisar el trabajo antes de terminar. La configuración está deshabilitada de forma predeterminada. Para habilitarla, establece advisor en {"type": "enabled", "model": "..."}, que tiene exactamente dos campos, type y model:

ant apply backend-engineer.md

---
name: Backend engineer
model: claude-sonnet-5
multiagent:
  type: multiagent_20261001
  advisor:
    type: enabled
    model: claude-opus-5-5
---

You implement backend features end to end. Consult the advisor before major backend design decisions.

Este ejemplo establece solo advisor. Las otras dos configuraciones, subagents y workflows, conservan sus valores predeterminados, por lo que ambas están habilitadas, y el agente también puede delegar a agentes inline e iniciar ejecuciones de flujos de trabajo. Para un agente que consulta a un asesor y hace todo el trabajo por sí mismo, establece ambas en {"type": "disabled"}.

No puedes enumerar al asesor en la lista predefined_agents de subagents o workflows. Un advisor habilitado reserva el nombre anthropic.advisor. Mientras esté habilitado, ninguna de las listas puede contener un agente llamado literalmente anthropic.advisor: la solicitud se rechaza con un error de validación 400.

El modelo asesor debe cumplir un nivel mínimo de capacidad, y el modelo propio del agente no debe ser más capaz que su asesor; los modelos de igual capacidad pueden emparejarse. Un emparejamiento no válido se rechaza con un error de validación 400 cuando se guarda el agente, y de nuevo cuando se crea una sesión. El emparejamiento también se verifica cuando comienza cada consulta: si ya no es válido, esa consulta falla y la sesión continúa. Los emparejamientos válidos siguen la tabla de compatibilidad de modelos de la herramienta de asesor.

El asesor también está disponible como una herramienta de servidor en la Messages API. La superficie de Managed Agents difiere en configuración y entrega: la configuración advisor no tiene campos max_uses, max_tokens ni caching, y los consejos llegan a través de eventos de hilo en lugar de bloques advisor_tool_result.

Cómo funcionan las consultas

Cada consulta se ejecuta como un hilo generado por la plataforma llamado anthropic.advisor que se termina a sí mismo cuando la consulta se completa, y el consejo se entrega al hilo principal como un evento agent.thread_message_received. Una consulta emite los eventos de hilo estándar, identificados por el nombre reservado anthropic.advisor (los eventos del ciclo de vida del hilo lo llevan como agent_name, y la entrega del consejo lo lleva como from_agent_name), normalmente en este orden:

1. session.thread_created
2. session.thread_status_running
3. agent.thread_message_received (el consejo)
4. session.thread_status_idle (stop_reason: end_turn)
5. session.thread_status_terminated

No se emiten eventos agent.tool_use para una consulta, y no aparece ningún evento agent.thread_message_sent en el flujo de eventos de la sesión, porque la entrada de la consulta la compone la plataforma en lugar de enviarla el agente. Si listas los eventos del propio hilo del asesor, el consejo también aparece allí como un evento agent.thread_message_sent. No se garantiza que la entrega del consejo (evento 3) llegue antes de los eventos de inactividad y terminación del hilo del asesor, así que no los trates como una señal de que el consejo ya se entregó.

Si tu cliente puede leer el consejo depende de la política del modelo asesor. Refleja la división de variantes de resultado de la herramienta de asesor de la Messages API. Un modelo asesor que devuelve resultados en texto plano allí entrega texto legible aquí. Uno que devuelve resultados redactados entrega un marcador de posición [{"type": "redacted"}] en todas las superficies del cliente, mientras que el agente sigue leyendo el consejo completo del lado del servidor. El ejemplo anterior usa como asesor el modelo Opus más reciente disponible para ti. Claude Opus 5.5 devuelve resultados redactados, por lo que tu cliente solo ve el marcador de posición. Para leer el consejo en el flujo de eventos, usa un asesor que devuelva texto plano, como Claude Opus 4.8. La política de un modelo puede cambiar sin ningún cambio en la API, así que maneja tanto los bloques text como los redacted. Algunos modelos de agente solo se emparejan con asesores de resultados redactados; consulta la tabla de compatibilidad de la herramienta de asesor. El pensamiento del asesor nunca se expone. Los clientes no pueden enviar bloques redacted por sí mismos; un evento que contenga uno se rechaza con un error de validación 400.

Una consulta fallida o interrumpida nunca hace fallar el turno del agente: el agente continúa después de un aviso genérico de que la consulta falló. Un user.interrupt a nivel de sesión durante una consulta termina el hilo del asesor sin entregar ningún consejo; un user.interrupt con el session_thread_id del hilo del asesor abandona solo esa consulta.

Hilos del asesor

El asesor no es un subagente. La herramienta list_agents del agente no lo muestra, y send_to_agent, que envía a un subagente un mensaje de seguimiento, no puede alcanzarlo. Solo el hilo principal de la sesión puede consultarlo; los subagentes no pueden.

Los hilos del asesor están exentos del límite de 25 hilos hijos. Aparecen en la lista de hilos de la sesión. Su agent es la forma de asesor, {"type": "advisor", "model": ...}, con el modelo que configuraste, y su parent_thread_id es el hilo principal.

El almacenamiento en caché de prompts del lado del asesor es automático; no hay nada que configurar. Las consultas se facturan según las tarifas del modelo asesor, y sus tokens aparecen en el uso del hilo del asesor y en los totales de uso de la sesión. También cuentan para un presupuesto de sesión, al precio de lista del modelo asesor. Cada consulta envía al asesor la conversación del hilo principal hasta ese momento, por lo que las consultas tardías en una sesión larga usan más tokens de entrada.

Eliminar el asesor

Para eliminar el asesor, actualiza el agente con advisor establecido en {"type": "disabled"}. En un agente que ya tiene el tipo multiagent_20261001, una configuración que la actualización omite conserva su valor almacenado, por lo que no necesitas enviar subagents ni workflows de nuevo. Por la misma razón, una actualización que omite advisor conserva el asesor. Antes de cambiar el multiagent.type de un agente existente, consulta cómo mover un agente a este tipo.

Migrar desde el tipo coordinator

Al igual que multiagent_20261001, el tipo coordinator permite que un agente delegue a subagentes que enumeras y consulte a un modelo asesor. Con el tipo coordinator, el agente no puede iniciar ejecuciones de flujos de trabajo ni definir subagentes por sí mismo. La API acepta ambos tipos.

Para mover un agente a multiagent_20261001, actualiza el agente con un bloque multiagent de ese tipo:

1. Establece type en "multiagent_20261001".
2. Enumera los agentes que el agente puede llamar en subagents.predefined_agents. Las entradas conservan la forma que tienen ahora.
3. Si el agente tiene un asesor, establece advisor en {"type": "enabled", "model": "..."} con el modelo del asesor.
4. Envía el bloque completo en una sola actualización.

Por ejemplo, este bloque le da a un agente dos subagentes y un asesor:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "subagents": {
      "type": "enabled",
      "predefined_agents": [
        { "type": "agent", "id": "agent_01J8XkN5uT3vHpLqRfWdY2" },
        { "type": "agent", "id": "agent_01HqR2k7vXbZ9mNpL3wYcT" }
      ]
    },
    "advisor": { "type": "enabled", "model": "claude-opus-5-5" }
  }
}

Ese bloque omite workflows y subagents.inline_agents, por lo que ambos toman su valor predeterminado y están habilitados. El agente migrado también puede iniciar ejecuciones de flujos de trabajo y definir subagentes por sí mismo. Para mantener cualquiera de los dos desactivado, establécelo en {"type": "disabled"} en la misma actualización. Consulta Activar los flujos de trabajo dinámicos y Agentes predefinidos e inline.

Si el agente tiene un asesor y no tiene subagentes, establece subagents en {"type": "disabled"} para mantener la delegación desactivada. Una solicitud que deshabilita subagents.inline_agents y no enumera ningún agente falla con un error 400.

La actualización reemplaza el bloque multiagent completo, así que envía de nuevo la lista de agentes y el asesor, como hace el ejemplo. Lo que omites toma su valor predeterminado:

• subagents.predefined_agents: La lista queda vacía, por lo que el agente pierde los subagentes que enumeraste.
• advisor: El asesor se deshabilita.

Una vez que el agente tiene el tipo multiagent_20261001, una configuración que una actualización posterior omite conserva su valor almacenado.

La actualización no cambia las sesiones que ya existen. Para usar el nuevo bloque, crea una sesión después de la actualización.