Orquestación multiagente

La “multiagent orchestration” (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 hasta completar el trabajo.

¿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).

Entregar trabajo a otros agentes

El agente que una sesión ejecuta puede entregar trabajo a otros agentes de dos maneras. Con subagents (subagentes), delega tareas él mismo y lee lo que informa cada subagente. Con 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 él mismo.

Tú decides cuáles de estas opciones puede usar el agente, y el agente determina cuándo usarlas. Para guiar esa elección, indícale al agente en su indicación del sistema cuándo usar una ejecución de flujo de trabajo. Consulta Indícale 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, de modo 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 de forma programática de un agente a otro, lo que libera el hilo principal de la sesión para comunicarse con el usuario y consultar uno o varios flujos de trabajo en ejecución para informar sobre el progreso. El agente no puede enviar mensajes de seguimiento a los hilos de una ejecución, y el servidor archiva cada uno a más tardar al final de su ejecución.

Configuras estas opciones en el bloque multiagent de la definición del agente, que tiene un type. Con el tipo multiagent_20261001, un agente puede usar las tres juntas, y puedes activar o desactivar cada una. 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 Activa 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 la sesión ejecuta, 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 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, de modo 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 que consisten en varias tareas bien delimitadas que 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 del 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 agente que la sesión ejecuta informa su actividad en el primary thread (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 la sesión ejecuta 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 del 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 grande que ejecute muchos agentes en segundo plano. Para desactivarlos, o para enumerar los agentes que puede usar un flujo de trabajo, consulta Activa 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 ya 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 solo puede delegar a un nivel de agentes. Hacer referencia a otro agente que tenga multiagent establecido 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 alguna de las fijaciones.

Crear la sesión

Crea una sesión que haga referencia al agente. El agente delega según sea necesario a los agentes que enumeras en la lista predefined_agents de subagents. 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 la sesión ejecuta. Las credenciales del vault tienen alcance de sesión: los vault_ids que se pasan al crear la sesión se aplican a cada hilo. Dos implicaciones para tu integración:

• Para autenticar los servidores MCP, incluye una credencial del 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, desactiva 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 la sesión ejecuta 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 de 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 la sesión ejecuta 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 piezas, 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 un 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 del bloque multiagent del agente. Los agentes de una ejecución pueden trabajar al mismo tiempo, por lo que una tarea larga puede completarse antes que si un solo agente hiciera cada pieza por turnos.

• Cómo comienza una ejecución: Describes el trabajo en un user.message. A partir de eso, el agente determina si debe iniciar una ejecución y cuándo, por lo que no hay ninguna llamada adicional a la API. En su lugar, influyes en la decisió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 la sesión ejecuta. 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 le das seguimiento: 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.

Activa 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, establece también subagents en {"type": "disabled"}.

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

Este ejemplo también deshabilita la búsqueda web y la obtención web, porque revisar contratos no usa la web:

ant apply contract-reviewer.md

---
name: Contract Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_search
        enabled: false
      - name: web_fetch
        enabled: false
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 Dale 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 campo que omites conserva su valor almacenado.
  • Una configuración o 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 se puede enumerar como subagente de otro agente, ni en la lista predefined_agents de workflows de otro agente. Un agente puede enumerarse a sí mismo en cualquiera de las listas con {"type": "self"}, que al leerse devuelve su propio id y version.
• Nombres de herramientas: El prefijo ant__ está reservado. Si tu agente ya tiene una herramienta personalizada cuyo nombre empieza 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 de 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.

Indícale 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 guiar 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 Activa 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 guiar 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, enumera 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 de 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.

Dale 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 (“advisor”): un modelo al que puede consultar a mitad de turno para obtener orientación estratégica, como planificar un enfoque, superar un obstáculo 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 ni de 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 propio modelo 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 al iniciar 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 API de Messages. La superficie de Managed Agents difiere en configuración y entrega: la configuración advisor no tiene los campos max_uses, max_tokens ni caching, y los consejos llegan mediante eventos de hilo en lugar de bloques advisor_tool_result.

Cómo funcionan las consultas

Cada consulta se ejecuta como un hilo creado 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 enumeras los eventos propios del 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 API de Messages. Un modelo asesor que allí devuelve resultados en texto plano entrega aquí texto legible. 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. Este 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 bloques text como redacted. Algunos modelos de agente solo se emparejan con asesores de resultados redactados; consulta la sección Compatibilidad de modelos 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 un mensaje de seguimiento a un subagente, 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 secundarios. 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 contra 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, así que no necesitas enviar de nuevo subagents ni workflows. 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 a los 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, así que ambos toman su valor predeterminado y quedan habilitados. El agente migrado también puede iniciar ejecuciones de flujos de trabajo y definir subagentes por sí mismo. Para mantener cualquiera de ellos desactivado, establécelo en {"type": "disabled"} en la misma actualización. Consulta Activa los flujos de trabajo dinámicos y Agentes predefinidos e inline.

Si el agente tiene un asesor y ningún subagente, 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 omitas 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.

Disponibilidad