Verwenden der Multi-Agent-Orchestrierung mit der Azure OpenAI-Antwort-API

Mithilfe der Multi-Agent-Orchestrierung kann ein Modell Subagenten parallel erstellen und koordinieren und dann ihre Arbeit in einer endgültigen Antwort kombinieren. Verwenden Sie sie für komplexe Aufgaben, die von unabhängigen Arbeitsabläufen profitieren, z. B. Codeüberprüfung, Forschung, Dokumentation und Implementierung. Dieses Feature befindet sich in der Vorschau und ist mit GPT-5.6-Modellen verfügbar.

Voraussetzungen

• Eine Azure OpenAI-Ressource in einer Region, die die Antwort-API unterstützt.

• Eine GPT-5.6-Modellbereitstellung. Überprüfen Sie die Modellverfügbarkeit , bevor Sie die Bereitstellung erstellen.

• Python 3.10 oder höher.

• Bei Microsoft Entra ID Authentifizierung wird die Cognitive Services OpenAI User Ihrer Identität zugewiesene Rolle zugewiesen.

• Für REST-Anforderungen, cURL und die Azure CLI bei Ihrem Azure-Abonnement angemeldet.

• Die neuesten OpenAI- und Azure Identity-Pakete:

  pip install --upgrade openai azure-identity
  

Wählen Sie aus, wann die Multi-Agent-Orchestrierung verwendet werden soll.

Verwenden Sie die Multi-Agent-Orchestrierung, wenn eine Aufgabe in konkrete, unabhängige Arbeitsabläufe unterteilt werden kann.

Das Hinzufügen von Subagenten kann die Tokennutzung erhöhen. Es kann keine Aufgaben verbessern, die eine geordnete Kette von Gründen erfordern, häufige Schreibvorgänge in den freigegebenen Zustand oder einen langsamen externen Vorgang.

Erstellen einer Multi-Agent-Antwort

Verwenden Sie den Betaantwort-Client mit api-version=preview. Legen Sie fest multi_agent.enabled , true dass der Stamm-Agent Subagenten erstellt. Enthält in Azure OpenAI-Anforderungen model Ihren Bereitstellungsnamen, der nicht mit dem zugrunde liegenden Modellnamen übereinstimmen muss.

Im folgenden Beispiel werden drei Subagenten aufgefordert, separate Vorschläge zur Notfallwiederherstellung auszuwerten. Jeder Vorschlag enthält genügend Informationen, damit ein Subagent unabhängig arbeiten kann und der Stammagent seine Ergebnisse mit gemeinsamen Anforderungen abgleicht.

1. Ersetzen Sie YOUR-RESOURCE-NAME durch den Namen Ihrer Azure OpenAI-Ressource.
2. Wenn der Bereitstellungsname nicht gpt-5.6-solangegeben ist, ersetzen Sie den Wert durch model ihren Bereitstellungsnamen.
3. Führen Sie den Code aus, und vergewissern Sie sich, dass die Ausgabe eine konsolidierte Überprüfung enthält /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)

Referenz: Azure OpenAI v1-API-Authentifizierung | Verwenden der Azure OpenAI-Antwort-API

Die Ausgabe enthält den Vergleich und die Empfehlung des Stamm-Agents. Antwortworte können variieren, aber das Ergebnis sollte Beta als einziger Vorschlag identifizieren, der alle angegebenen Wiederherstellungs- und Budgetanforderungen erfüllt.

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

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

Um stattdessen einen Azure OpenAI-API-Schlüssel zu verwenden, legen Sie den Client wie folgt festAZURE_OPENAI_API_KEY, und erstellen Sie den Client wie folgt:

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

Referenz: Azure OpenAI v1 API-Authentifizierung

Senden einer REST-Anforderung

Verwenden Sie für REST-Anforderungen den Azure OpenAI v1-Endpunkt, und fügen Sie hinzuapi-version=preview.

Microsoft Entra ID

Festlegen AZURE_OPENAI_AUTH_TOKEN auf ein Zugriffstoken für die Azure KI-Zielgruppe:

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

Referenz: Azure OpenAI v1 API-Authentifizierung

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
    }
  }'

Referenz: Use the Azure OpenAI Responses API

API-Schlüssel

Legen Sie AZURE_OPENAI_API_KEY einen Schlüssel aus Ihrer Azure OpenAI-Ressource fest:

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
    }
  }'

Referenz: Use the Azure OpenAI Responses API

max_concurrent_subagents begrenzt, wie viele Subagenten gleichzeitig über die gesamte Agentstruktur aktiv werden können. Der Grenzwert umfasst Kinder, Enkel und tiefere Nachfolger, schließt jedoch den Stamm-Agent aus. Der Standardwert ist 3, was für die meisten Workloads empfohlen wird.

Steuerungsdelegierung

Das Modell entscheidet, ob die Delegierung nützlich ist. Legen Sie die Arbeitsströme in der Eingabe explizit fest, wenn für die Aufgabe parallele Arbeit erforderlich ist.

Fügen Sie Entwickleranweisungen hinzu, um zu steuern, wann das Stammmodell delegiert wird. Beispiel:

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

Diese Anweisungen ergänzen die Orchestrierungsanweisungen, die der Dienst für den Stamm-Agent und Subagenten bereitstellt.

Grundlegendes zur Agentkoordination

Der Agent, der die ursprüngliche Anforderung empfängt, ist der Stamm-Agent und heißt ./root Subagenten verwenden hierarchische Namen, die ihre Position in der Agentstruktur anzeigen:

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

Der Stamm-Agent delegiert Arbeit, wartet auf Ergebnisse, versöhnt Ergebnisse und erzeugt die endgültige Antwort. Subagenten verwenden dasselbe Modell und haben Zugriff auf die in der ursprünglichen Anforderung konfigurierten Tools.

Der Dienst stellt gehostete Aktionen für die Zusammenarbeit bereit. Sie werden in einer Antwort als multi_agent_call Elemente angezeigt. Ihre Anwendung darf diese Aktionen nicht ausführen oder Ausgaben für sie übermitteln.

Behandeln von Funktionsaufrufen

Jeder Agent kann entwicklerdefinierte Funktionen aufrufen, die in der Anforderung enthalten sind. Führen Sie alle zurückgegebenen Vorgänge aus function_call, und übermitteln Sie einen übereinstimmenden Wert function_call_output. Behandeln Sie gehostete Elemente nicht als entwicklerdefinierte multi_agent_call Funktionen, da der Dienst sie verwaltet.

Bei HTTP wird eine Antwort abgeschlossen, nachdem jeder aktive Agent abgeschlossen oder angehalten wurde, für einen clientgesteuerten Funktionsaufruf. Führen Sie alle ausstehenden Funktionsaufrufe aus, bewahren Sie die Ausgabeelemente auf, und übermitteln Sie ihre Ausgaben in der nächsten Anforderung, damit die angehaltenen Agents fortfahren können. Informationen zum Ausführungsmuster des Basistools finden Sie unter Funktionsaufrufe.

Überprüfen der Multi-Agent-Ausgabe

Multi-Agent-Antworten können diese zusätzlichen Ausgabeelementtypen enthalten:

• multi_agent_call: Eine aktion für die gehostete Zusammenarbeit, z spawn_agent. B. .
• multi_agent_call_output: Das Ergebnis einer gehosteten Zusammenarbeitsaktion.
• agent_message: Eine verschlüsselte Nachricht, die von einem Agent an einen anderen gesendet wird.

Das call_id Feld verknüpft jedes multi_agent_call mit dem entsprechenden multi_agent_call_outputFeld. Jedes Element verfügt auch über eine agent Eigenschaft. Verwenden Sie recipient für einen agent_message, und author um die Nachrichtenrichtung zu verfolgen.

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

Bewahren Sie diese Elemente auf, wenn Sie den Unterhaltungszustand manuell wiedergeben oder Orchestrierungsablaufverfolgungen sammeln. Machen Sie verschlüsselte Agent-Nachrichten nicht als vom Benutzer sichtbaren Inhalt verfügbar.

Http- oder WebSocket-Modus auswählen

HTTP- und WebSocket-Transporte unterstützen dieselben Multi-Agent-Orchestrierungsfunktionen, aber ihr Funktionsaufrufverhalten unterscheidet sich.

Senden Sie im WebSocket-Modus ein response.inject Ereignis für jede Funktionsausgabe:

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

Fahren Sie mit dem Lesen von Ereignissen fort, bis die Antwort abgeschlossen ist, und jede Einfügung gibt entweder response.inject.created oder response.inject.failed. Wenn eine Einfügung fehlschlägt response_already_completed, senden Sie die zurückgegebene Eingabe in einer neuen Antwort, die von der abgeschlossenen Antwort fortgesetzt wird. Anleitungen zur Verbindung und Wiederherstellung finden Sie unter Verwenden der Antwort-API im WebSocket-Modus.

Anwenden von Sicherheitssteuerelementen

Jeder Agent in der Struktur hat Zugriff auf die in der ursprünglichen Anforderung konfigurierten Tools. Wenden Sie dieselben Steuerelemente auf Anrufe von Subagenten an, die Sie auf Aufrufe vom Stamm-Agent anwenden.

• Gewähren Sie Tools und Aufrufen von Identitäten nur die Berechtigungen, die für die Aufgabe erforderlich sind.
• Überprüfen Sie Funktionsargumente, und autorisieren Sie jede Aktion im Anwendungscode.
• Benutzergenehmigung vor dem Schreiben, Destruktivieren, Finanziellen oder anderen aktionen mit hoher Auswirkung anfordern.
• Behandeln Sie Inhalte, die von externen Tools zurückgegeben werden, als nicht vertrauenswürdige Eingaben, und schützen Sie sich vor der Eingabeaufforderungseinfügung.
• Protokollieren Sie den Agentnamen, den Toolnamen, argumente, die Genehmigungsentscheidung und das Ergebnis für die Überwachung.
• Gebundene delegierte Arbeit und Überwachen der Tokennutzung, da Subagenten den Verbrauch erhöhen können.

Überprüfen von Einschränkungen

• Der /responses/compact Endpunkt wird nicht unterstützt, wenn die Multi-Agent-Orchestrierung aktiviert ist.
• Die automatische serverseitige Komprimierung ist aktiviert, auch wenn multi_agent.enabledtruedie Anforderung nicht definiert context_managementwird. Komprimierung wird unabhängig für den Stammagenten und jeden Subagenten ausgeführt.
• Sie können den Komprimierungsschwellenwert überschreiben, indem Sie die Einstellung festlegen context_management.compact_threshold.
• reasoning.summary wird nicht unterstützt, wenn die Multi-Agent-Orchestrierung aktiviert ist.
• max_tool_calls wird nicht unterstützt, wenn die Multi-Agent-Orchestrierung aktiviert ist.
• max_concurrent_subagents Standardmäßig wird dies 3für die meisten Workloads empfohlen.
• Die Multi-Agent-Orchestrierung hat keinen festen Grenzwert für die Strukturtiefe oder die Gesamtanzahl der subagenten, die während einer Ausführung erstellt wurden. Steuern der Parallelität und gebundenen delegierten Arbeit zum Verwalten von Latenz und Tokenverwendung.

Behandeln von Problemen mit mehreren Agent-Anforderungen

Verwandte Inhalte

• Verwenden der Azure OpenAI-Antwort-API
• Verwenden von Funktionsaufrufen
• Verwenden der Antwort-API im WebSocket-Modus