Usare l'orchestrazione multi-agente con l'API Risposte OpenAI Azure

Usando l'orchestrazione multi-agente, un modello può creare e coordinare subagenti in parallelo, quindi combinare il lavoro in una risposta finale. Usarlo per attività complesse che traggono vantaggio da flussi di lavoro indipendenti, ad esempio la revisione del codice, la ricerca, la documentazione e l'implementazione. Questa funzionalità è disponibile in anteprima ed è disponibile con i modelli GPT-5.6.

Prerequisiti

• Una Azure risorsa OpenAI in un'area che supporta l'API Risposte.

• Distribuzione di modelli GPT-5.6. Controllare la disponibilità del modello prima di creare la distribuzione.

• Python 3.10 o versione successiva.

• Per Microsoft Entra ID'autenticazione, il ruolo assegnato all'identitàCognitive Services OpenAI User.

• Per le richieste REST, cURL e le interfaccia della riga di comando di Azure hanno eseguito l'accesso alla sottoscrizione Azure.

• I pacchetti OpenAI e identity Azure più recenti:

  pip install --upgrade openai azure-identity
  

Scegliere quando usare l'orchestrazione multi-agente

Usare l'orchestrazione multi-agente quando un'attività può essere divisa in flussi di lavoro concreti e indipendenti.

L'aggiunta di subagenti può aumentare l'utilizzo dei token. Potrebbe non migliorare le attività che richiedono una catena ordinata di ragionamenti, scritture frequenti in stato condiviso o un'operazione esterna lenta.

Creare una risposta multi-agente

Usare il client delle risposte beta con api-version=preview. Impostare multi_agent.enabled su true per consentire all'agente radice di creare subagenti. In Azure richieste model OpenAI contiene il nome della distribuzione, che non deve corrispondere al nome del modello sottostante.

L'esempio seguente chiede a tre subagenti di valutare proposte di ripristino di emergenza separate. Ogni proposta include informazioni sufficienti per il funzionamento indipendente di un subagente e l'agente radice riconcilia i risultati in base ai requisiti condivisi.

1. Sostituire YOUR-RESOURCE-NAME con il nome della risorsa OpenAI di Azure.
2. Se il nome della distribuzione non gpt-5.6-solè , sostituire il valore di con il nome della model distribuzione.
3. Eseguire il codice e verificare che l'output contenga una revisione consolidata da /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)

Riferimento: Azure'autenticazione API OpenAI v1Usare l'API Risposte OpenAI Azure |

L'output contiene il confronto e la raccomandazione dell'agente radice. La formulazione delle risposte può variare, ma il risultato deve identificare Beta come l'unica proposta che soddisfi tutti i requisiti di recupero e budget dichiarati.

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

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

Per usare una chiave API OpenAI Azure, impostare AZURE_OPENAI_API_KEYe creare il client come indicato di seguito:

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

Riferimento: autenticazione API OpenAI v1 Azure

Inviare una richiesta REST

Per le richieste REST, usare l'endpoint Azure OpenAI v1 e aggiungere api-version=preview.

Microsoft Entra ID

Impostare AZURE_OPENAI_AUTH_TOKEN su un token di accesso per il gruppo di destinatari di intelligenza artificiale Azure:

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

Riferimento: autenticazione API 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
    }
  }'

Riferimento: Use the Azure OpenAI Responses API

API key

Impostare AZURE_OPENAI_API_KEY su una chiave dalla risorsa OpenAI 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
    }
  }'

Riferimento: Use the Azure OpenAI Responses API

max_concurrent_subagents limita il numero di subagenti che possono essere attivi contemporaneamente nell'intero albero dell'agente. Il limite include figli, nipoti e discendenti più profondi, ma esclude l'agente radice. Il valore predefinito è 3, consigliato per la maggior parte dei carichi di lavoro.

Delega del controllo

Il modello decide se la delega è utile. Rendere espliciti i flussi di lavoro nell'input quando l'attività richiede il lavoro parallelo.

Aggiungere istruzioni per gli sviluppatori per controllare quando i delegati del modello radice. Per esempio:

• 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.

Queste istruzioni integrano le istruzioni di orchestrazione fornite dal servizio all'agente radice e ai subagenti.

Informazioni sul coordinamento degli agenti

L'agente che riceve la richiesta originale è l'agente radice e è denominato /root. I subagenti usano nomi gerarchici che mostrano la loro posizione nell'albero dell'agente:

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

I delegati dell'agente radice lavorano, attendono i risultati, riconciliano i risultati e producono la risposta finale. I subagenti usano lo stesso modello e hanno accesso agli strumenti configurati nella richiesta originale.

Il servizio fornisce azioni di collaborazione ospitate. Vengono visualizzati in una risposta come multi_agent_call elementi. L'applicazione non deve eseguire queste azioni o inviare output per tali azioni.

Gestire le chiamate di funzione

Qualsiasi agente può chiamare funzioni definite dallo sviluppatore incluse nella richiesta. Eseguire ogni oggetto restituito function_calle inviare un oggetto corrispondente function_call_output. Non gestire gli elementi ospitati multi_agent_call come funzioni definite dallo sviluppatore perché li gestisce.

Con HTTP, una risposta viene completata al termine di ogni agente attivo o viene sospesa per una chiamata di funzione eseguita dal client. Eseguire tutte le chiamate di funzione in sospeso, mantenere gli elementi di output e inviare gli output nella richiesta successiva in modo che gli agenti sospesi possano continuare. Per il modello di esecuzione dello strumento di base, vedere Chiamata di funzioni.

Esaminare l'output multi-agente

Le risposte multi-agente possono includere questi tipi di elemento di output aggiuntivi:

• multi_agent_call: azione di collaborazione ospitata, ad esempio spawn_agent.
• multi_agent_call_output: risultato di un'azione di collaborazione ospitata.
• agent_message: messaggio crittografato inviato da un agente a un altro.

Il call_id campo collega ogni multi_agent_call oggetto al corrispondente multi_agent_call_outputoggetto . Ogni elemento ha anche una agent proprietà . Per un agent_messageoggetto , usare author e recipient per tracciare la direzione del messaggio.

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

Conservare questi elementi quando si riproduce manualmente lo stato della conversazione o si raccolgono tracce di orchestrazione. Non esporre i messaggi dell'agente crittografati come contenuto visibile all'utente.

Scegliere la modalità HTTP o WebSocket

I trasporti HTTP e WebSocket supportano le stesse funzionalità di orchestrazione multi-agente, ma il comportamento della chiamata di funzione è diverso.

In modalità WebSocket inviare un response.inject evento per ogni output della funzione:

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

Continuare a leggere gli eventi fino al completamento della risposta e ogni inserimento restituisce response.inject.created o response.inject.failed. Se un'operazione di inserimento non riesce con response_already_completed, inviare l'input restituito in una nuova risposta che continua dalla risposta completata. Per indicazioni sulla connessione e sul ripristino, vedere Usare l'API Risposte in modalità WebSocket.

Applicare i controlli di sicurezza

Ogni agente nell'albero ha accesso agli strumenti configurati nella richiesta originale. Applicare gli stessi controlli alle chiamate dai subagenti applicati alle chiamate dall'agente radice.

• Concedere strumenti e chiamare le identità solo le autorizzazioni necessarie per l'attività.
• Convalidare gli argomenti della funzione e autorizzare ogni azione nel codice dell'applicazione.
• Richiedere l'approvazione dell'utente prima di scrivere, distruttivo, finanziario o altre azioni ad alto impatto.
• Considerare il contenuto restituito da strumenti esterni come input non attendibile e proteggersi dall'inserimento di richieste.
• Registrare il nome dell'agente, il nome dello strumento, gli argomenti, la decisione di approvazione e il risultato per il controllo.
• Lavoro delegato associato e monitorare l'utilizzo dei token perché i subagenti possono aumentare il consumo.

Esaminare le limitazioni

• L'endpoint /responses/compact non è supportato quando è abilitata l'orchestrazione multi-agente.
• La compattazione lato server automatica è abilitata quando multi_agent.enabled è true, anche se la richiesta non definisce context_management. La compattazione viene eseguita in modo indipendente per l'agente radice e ogni subagente.
• È possibile eseguire l'override della soglia di compattazione impostando context_management.compact_threshold.
• reasoning.summary non è supportato quando l'orchestrazione multi-agente è abilitata.
• max_tool_calls non è supportato quando l'orchestrazione multi-agente è abilitata.
• max_concurrent_subagents il 3valore predefinito è , consigliato per la maggior parte dei carichi di lavoro.
• L'orchestrazione multi-agente non prevede limiti fissi sulla profondità dell'albero o sul numero totale di subagenti creati durante un'esecuzione. Controllare la concorrenza e il lavoro delegato associato per gestire l'utilizzo di latenza e token.

Risolvere i problemi relativi alle richieste multi-agente

Contenuti correlati

• Usare l'API Risposte OpenAI di Azure
• Usare la chiamata di funzione
• Usare l'API Risposte in modalità WebSocket