Uso de la orquestación multiagente con la API de respuestas de OpenAI de Azure

Mediante la orquestación multiagente, un modelo puede crear y coordinar subagentes en paralelo y, a continuación, combinar su trabajo en una respuesta final. Úselo para tareas complejas que se benefician de secuencias de trabajo independientes, como revisión de código, investigación, documentación e implementación. Esta característica está en versión preliminar y está disponible con modelos GPT-5.6.

Prerequisites

• Un Azure recurso de OpenAI en una región que admita la API de respuestas.

• Implementación de modelos GPT-5.6. Compruebe la disponibilidad del modelo antes de crear la implementación.

• Python 3.10 o posterior.

• Para Microsoft Entra ID autenticación, el Cognitive Services OpenAI User rol asignado a la identidad.

• En el caso de las solicitudes REST, cURL y el CLI de Azure iniciaron sesión en la suscripción de Azure.

• Los paquetes OpenAI y Azure Identity más recientes:

  pip install --upgrade openai azure-identity
  

Elegir cuándo usar la orquestación multiagente

Use la orquestación multiagente cuando una tarea se pueda dividir en secuencias de trabajo concretas e independientes.

Agregar subagentes puede aumentar el uso de tokens. Es posible que no mejore las tareas que requieren una cadena ordenada de razonamiento, escrituras frecuentes en estado compartido o una operación externa lenta.

Creación de una respuesta multiagente

Use el cliente de respuestas beta con api-version=preview. Establézcalo multi_agent.enabled en true para permitir que el agente raíz cree subagentes. En Azure solicitudes de OpenAI, model contiene el nombre de la implementación, que no tiene que coincidir con el nombre del modelo subyacente.

En el ejemplo siguiente se pide a tres subagentes que evalúen propuestas de recuperación ante desastres independientes. Cada propuesta incluye suficiente información para que un subagente funcione de forma independiente y el agente raíz reconcilia sus hallazgos con respecto a los requisitos compartidos.

1. Reemplace por YOUR-RESOURCE-NAME el nombre del recurso de Azure OpenAI.
2. Si el nombre de la implementación no gpt-5.6-soles , reemplace el valor de por el nombre de model la implementación.
3. Ejecute el código y confirme que la salida contiene una revisión consolidada de /root.

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI

# Configure Microsoft Entra ID credentials.
endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
scope = "https://ai.azure.com/.default"
token_provider = get_bearer_token_provider(DefaultAzureCredential(), scope)
openai = OpenAI(
    base_url=endpoint,
    api_key=token_provider,
    default_query={"api-version": "preview"},
)

# Delegate each proposal to a separate subagent.
prompt = """
Evaluate three disaster-recovery proposals. Create one subagent per proposal.
Each subagent must assess recovery targets, monthly cost, and operational risk.

Alpha: Active-active across two regions; RTO under 5 minutes; near-zero RPO;
$42,000/month; quarterly failover tests.
Beta: Warm standby; 30-minute RTO; 5-minute RPO; $18,000/month;
monthly failover tests.
Gamma: Backup and restore; 8-hour RTO; 24-hour RPO; $6,000/month;
annual restore test.

The checkout system requires RTO <= 30 minutes, RPO <= 5 minutes, and a
monthly budget <= $20,000. After the subagents finish, compare their evidence
in a table and recommend one proposal. Explain any residual risk.
"""

response = openai.beta.responses.create(
    model="gpt-5.6-sol",
  input=prompt,
    multi_agent={"enabled": True, "max_concurrent_subagents": 3},
)

# Print only the root agent's final answer.
for item in response.output:
    if (
        item.type == "message"
        and item.phase == "final_answer"
        and item.agent
        and item.agent.agent_name == "/root"
    ):
        for part in item.content:
            if part.type == "output_text":
                print(part.text)

Referencia: Azure autenticación | de api de OpenAI v1Use the Azure OpenAI Responses API

La salida contiene la comparación y recomendación del agente raíz. La redacción de respuesta puede variar, pero el resultado debe identificar Beta como la única propuesta que cumpla todos los requisitos de recuperación y presupuesto indicados.

| Proposal | Recovery targets | Monthly cost | Operational risk |
| ... | ... | ... | ... |

Recommendation: Beta meets the stated RTO, RPO, and budget requirements.

Para usar una clave de API de OpenAI Azure en su lugar, establezca AZURE_OPENAI_API_KEYy cree el cliente de la siguiente manera:

import os

from openai import OpenAI

# Authenticate with an Azure OpenAI API key.
endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
openai = OpenAI(
    base_url=endpoint,
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    default_query={"api-version": "preview"},
)

Referencia: autenticación de api de OpenAI v1 Azure

Envío de una solicitud REST

En el caso de las solicitudes REST, use el punto de conexión de Azure OpenAI v1 y agregue api-version=preview.

Microsoft Entra ID

Establézcalo AZURE_OPENAI_AUTH_TOKEN en un token de acceso para la audiencia de ia de Azure:

export AZURE_OPENAI_AUTH_TOKEN=$(
  az account get-access-token \
    --resource https://ai.azure.com \
    --query accessToken \
    --output tsv
)

Referencia: autenticación de api de OpenAI v1 Azure

curl -X POST "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses?api-version=preview" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Evaluate three disaster-recovery proposals with one subagent per proposal. Alpha: active-active, RTO under 5 minutes, near-zero RPO, $42,000/month. Beta: warm standby, 30-minute RTO, 5-minute RPO, $18,000/month. Gamma: backup and restore, 8-hour RTO, 24-hour RPO, $6,000/month. The checkout system requires RTO at most 30 minutes, RPO at most 5 minutes, and a monthly budget at most $20,000. Compare the evidence and recommend one proposal.",
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 3
    }
  }'

Referencia: Uso de la API Responses de Azure OpenAI

Clave de API

Establézcalo AZURE_OPENAI_API_KEY en una clave del recurso de openAI de Azure:

export AZURE_OPENAI_API_KEY="<your-api-key>"

curl -X POST "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses?api-version=preview" \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Evaluate three disaster-recovery proposals with one subagent per proposal. Alpha: active-active, RTO under 5 minutes, near-zero RPO, $42,000/month. Beta: warm standby, 30-minute RTO, 5-minute RPO, $18,000/month. Gamma: backup and restore, 8-hour RTO, 24-hour RPO, $6,000/month. The checkout system requires RTO at most 30 minutes, RPO at most 5 minutes, and a monthly budget at most $20,000. Compare the evidence and recommend one proposal.",
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 3
    }
  }'

Referencia: Uso de la API Responses de Azure OpenAI

max_concurrent_subagents limita el número de subagentes que pueden estar activos al mismo tiempo en todo el árbol del agente. El límite incluye hijos, nietos y descendientes más profundos, pero excluye el agente raíz. El valor predeterminado es 3, que se recomienda para la mayoría de las cargas de trabajo.

Delegación de controles

El modelo decide si la delegación es útil. Haga que las secuencias de trabajo sean explícitas en la entrada cuando la tarea requiera trabajo paralelo.

Agregue instrucciones para desarrolladores para controlar cuándo se delega el modelo raíz. Por ejemplo:

• Do not create subagents unless the user explicitly asks for delegation or parallel work.
• Use subagents when parallel work would materially improve speed or quality.

Estas instrucciones complementan las instrucciones de orquestación que proporciona el servicio al agente raíz y a los subagentes.

Descripción de la coordinación del agente

El agente que recibe la solicitud original es el agente raíz y se denomina /root. Los subagentes usan nombres jerárquicos que muestran su posición en el árbol del agente:

/root
|-- /root/researcher
|-- /root/reviewer
|   `-- /root/reviewer/tester
`-- /root/writer

Los delegados del agente raíz funcionan, espera resultados, reconcilia los resultados y genera la respuesta final. Los subagentes usan el mismo modelo y tienen acceso a las herramientas configuradas en la solicitud original.

El servicio proporciona acciones de colaboración hospedadas. Aparecen en una respuesta como multi_agent_call elementos. La aplicación no debe ejecutar estas acciones ni enviar salidas para ellas.

Controlar llamadas de función

Cualquier agente puede llamar a funciones definidas por el desarrollador incluidas en la solicitud. Ejecute todos los devueltos function_cally envíe un objeto coincidente function_call_output. No controle los elementos hospedados multi_agent_call como funciones definidas por el desarrollador porque el servicio los administra.

Con HTTP, una respuesta se completa después de que cada agente activo finalice o se detenga para una llamada de función ejecutada por el cliente. Ejecute todas las llamadas de función pendientes, conserve los elementos de salida y envíe sus salidas en la siguiente solicitud para que los agentes en pausa puedan continuar. Para obtener el patrón de ejecución de la herramienta base, consulte Llamada a funciones.

Inspección de la salida de varios agentes

Las respuestas de varios agentes pueden incluir estos tipos de elementos de salida adicionales:

• multi_agent_call: una acción de colaboración hospedada, como spawn_agent.
• multi_agent_call_output: resultado de una acción de colaboración hospedada.
• agent_message: mensaje cifrado enviado de un agente a otro.

El call_id campo vincula cada uno multi_agent_call a su correspondiente multi_agent_call_output. Cada elemento también tiene una agent propiedad . Para , agent_messageuse author y recipient para realizar un seguimiento de la dirección del mensaje.

[
  {
    "type": "multi_agent_call",
    "call_id": "call_spawn_a",
    "action": "spawn_agent",
    "agent": { "agent_name": "/root" }
  },
  {
    "type": "multi_agent_call_output",
    "call_id": "call_spawn_a",
    "action": "spawn_agent",
    "agent": { "agent_name": "/root" }
  },
  {
    "type": "agent_message",
    "author": "/root/researcher",
    "recipient": "/root",
    "content": [{ "type": "encrypted_content", "encrypted_content": "<encrypted-content>" }]
  }
]

Conserve estos elementos al reproducir manualmente el estado de conversación o recopile seguimientos de orquestación. No exponga mensajes cifrados del agente como contenido visible para el usuario.

Elegir el modo HTTP o WebSocket

Los transportes HTTP y WebSocket admiten las mismas funcionalidades de orquestación multiagente, pero su comportamiento de llamada a función difiere.

En el modo WebSocket, envíe un response.inject evento para cada salida de función:

{
  "type": "response.inject",
  "response_id": "resp_123",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": "{\"temperature\":72}"
    }
  ]
}

Continúe leyendo eventos hasta que se complete la respuesta y cada inyección devuelva response.inject.created o response.inject.failed. Si se produce un error en una inyección con response_already_completed, envíe la entrada devuelta en una nueva respuesta que continúe desde la respuesta completada. Para obtener instrucciones de conexión y recuperación, consulte Uso de la API de respuestas en modo WebSocket.

Aplicación de controles de seguridad

Cada agente del árbol tiene acceso a las herramientas configuradas en la solicitud original. Aplique los mismos controles a las llamadas desde subagentes que se aplican a las llamadas del agente raíz.

• Conceda herramientas y llamadas a identidades solo los permisos necesarios para la tarea.
• Valide los argumentos de función y autorice cada acción en el código de la aplicación.
• Requerir aprobación del usuario antes de escribir, destructiva, financiera u otras acciones de alto impacto.
• Trate el contenido devuelto por herramientas externas como entrada que no es de confianza y proteja contra la inyección de mensajes.
• Registre el nombre del agente, el nombre de la herramienta, los argumentos, la decisión de aprobación y el resultado de la auditoría.
• Trabajo delegado enlazado y supervisión del uso de tokens porque los subagentes pueden aumentar el consumo.

Revisar las limitaciones

• El /responses/compact punto de conexión no se admite cuando está habilitada la orquestación multiagente.
• La compactación automática del lado servidor está habilitada cuando multi_agent.enabled es true, incluso si la solicitud no define context_management. La compactación se ejecuta de forma independiente para el agente raíz y cada subagente.
• Puede invalidar el umbral de compactación estableciendo context_management.compact_threshold.
• reasoning.summary no se admite cuando la orquestación multiagente está habilitada.
• max_tool_calls no se admite cuando la orquestación multiagente está habilitada.
• max_concurrent_subagents 3el valor predeterminado es , que se recomienda para la mayoría de las cargas de trabajo.
• La orquestación multiagente no tiene ningún límite fijo en la profundidad del árbol o el número total de subagentes creados durante una ejecución. Controlar la simultaneidad y el trabajo delegado enlazado para administrar la latencia y el uso de tokens.

Solución de problemas de solicitudes de varios agentes

Contenido relacionado

• Utilice la API de respuestas de Azure OpenAI
• Uso de llamadas a funciones
• Uso de la API de respuestas en modo WebSocket