Azure OpenAI Responses API でマルチエージェント オーケストレーションを使用する

マルチエージェント オーケストレーションを使用することで、モデルはサブエージェントを並列で作成して調整し、その作業を最終的な応答に結合できます。 コード レビュー、調査、ドキュメント、実装など、独立したワークストリームの恩恵を受ける複雑なタスクに使用します。 この機能はプレビュー段階であり、GPT-5.6 モデルで利用できます。

前提条件

• Responses API をサポートするリージョン内の Azure OpenAI リソース。

• GPT-5.6 モデルのデプロイ。 デプロイを作成する前に 、モデルの可用性 を確認します。

• Python 3.10 以降。

• Microsoft Entra ID認証の場合、ID に割り当てられたCognitive Services OpenAI User ロール。

• REST 要求の場合、cURL とAzure CLIはAzure サブスクリプションにサインインします。

• 最新の OpenAI およびAzure ID パッケージ:

  pip install --upgrade openai azure-identity
  

マルチエージェント オーケストレーションを使用するタイミングを選択する

タスクを具体的な独立したワークストリームに分割できる場合は、マルチエージェント オーケストレーションを使用します。

サブエージェントを追加すると、トークンの使用量が増加する可能性があります。 順序付けされた推論チェーン、共有状態への頻繁な書き込み、または 1 つの低速な外部操作を必要とするタスクは改善されない場合があります。

マルチエージェント応答を作成する

api-version=previewでベータ版応答クライアントを使用します。 ルート エージェントでサブエージェントを作成できるようにするには、 multi_agent.enabled を true に設定します。 Azure OpenAI 要求では、modelには、基になるモデル名と一致する必要のないデプロイ名が含まれています。

次の例では、3 つのサブエージェントに個別のディザスター リカバリーの提案を評価するよう求めます。 各提案には、サブエージェントが独立して機能するのに十分な情報が含まれており、ルート エージェントは共有要件に対して結果を調整します。

1. YOUR-RESOURCE-NAMEを Azure OpenAI リソース名に置き換えます。
2. デプロイ名が gpt-5.6-solされていない場合は、 model の値を実際のデプロイ名に置き換えます。
3. コードを実行し、出力に /rootからの 1 つの統合レビューが含まれていることを確認します。

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)

リファレンス: OpenAI v1 API 認証Azure | OpenAI 応答 API Azure使用する

出力には、ルート エージェントの比較と推奨事項が含まれています。 応答の文言は異なる場合がありますが、結果は、記載されているすべての復旧と予算の要件を満たす唯一の提案としてベータ版を識別する必要があります。

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

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

代わりに Azure OpenAI API キーを使用するには、AZURE_OPENAI_API_KEYを設定し、次のようにクライアントを作成します。

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

リファレンス: OpenAI v1 API 認証Azure

REST 要求を送信する

REST 要求の場合は、Azure OpenAI v1 エンドポイントを使用し、api-version=previewを追加します。

Microsoft Entra ID

Azure AI 対象ユーザーのアクセス トークンにAZURE_OPENAI_AUTH_TOKENを設定します。

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

リファレンス: OpenAI v1 API 認証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
    }
  }'

リファレンス: Azure OpenAI Responses API

API キー

Azure OpenAI リソースのキーにAZURE_OPENAI_API_KEYを設定します。

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

リファレンス: Azure OpenAI Responses API

max_concurrent_subagents では、エージェント ツリー全体で同時にアクティブにできるサブエージェントの数が制限されます。 制限には、子、孫、およびより深い子孫が含まれますが、ルート エージェントは除外されます。 既定値は 3 であり、ほとんどのワークロードに推奨されます。

コントロールの委任

このモデルは、委任が役に立つかどうかを決定します。 タスクで並列作業が必要な場合は、入力でワークストリームを明示的にします。

ルート モデルが委任されるタイミングを制御する開発者命令を追加します。 例えば次が挙げられます。

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

これらの手順は、サービスがルート エージェントとサブエージェントに提供するオーケストレーション命令を補完します。

エージェントの調整について

元の要求を受け取るエージェントはルート エージェントであり、 /rootという名前です。 サブエージェントは、エージェント ツリー内での位置を示す階層名を使用します。

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

ルート エージェントは作業を委任し、結果を待機し、結果を調整して、最終的な回答を生成します。 サブエージェントは同じモデルを使用し、元の要求で構成されたツールにアクセスできます。

このサービスは、ホステッド コラボレーション アクションを提供します。 これらは、 multi_agent_call 項目として応答に表示されます。 アプリケーションでこれらのアクションを実行したり、それらのアクションの出力を送信したりしてはなりません。

関数呼び出しを処理する

どのエージェントでも、要求に含まれる開発者定義関数を呼び出すことができます。 返されるすべての function_callを実行し、一致する function_call_outputを送信します。 ホストされている multi_agent_call 項目は、サービスによって管理されるため、開発者定義関数として処理しないでください。

HTTP では、アクティブなエージェントがクライアント実行関数呼び出しの完了後または一時停止するたびに応答が完了します。 保留中のすべての関数呼び出しを実行し、出力項目を保持し、次の要求で出力を送信して、一時停止したエージェントが続行できるようにします。 基本ツールの実行パターンについては、「 関数呼び出し」を参照してください。

マルチエージェントの出力を検査する

マルチエージェント応答には、次の追加の出力項目の種類を含めることができます。

• multi_agent_call: spawn_agentなどのホステッド コラボレーション アクション。
• multi_agent_call_output: ホストされたコラボレーション アクションの結果。
• agent_message: エージェント間で送信される暗号化されたメッセージ。

call_id フィールドは、各multi_agent_callを対応するmulti_agent_call_outputにリンクします。 各項目には、 agent プロパティもあります。 agent_messageの場合は、authorとrecipientを使用してメッセージの方向をトレースします。

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

会話状態を手動で再生したり、オーケストレーション トレースを収集したりするときに、これらの項目を保持します。 暗号化されたエージェント メッセージをユーザーに表示されるコンテンツとして公開しないでください。

HTTP または WebSocket モードを選択する

HTTP トランスポートと WebSocket トランスポートは、同じマルチエージェント オーケストレーション機能をサポートしますが、関数呼び出しの動作は異なります。

WebSocket モードでは、関数の出力ごとに response.inject イベントを送信します。

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

応答が完了し、各インジェクションが response.inject.created または response.inject.failed返されるまで、イベントの読み取りを続けます。 挿入が response_already_completedで失敗した場合は、完了した応答から継続する新しい応答で返された入力を送信します。 接続と復旧のガイダンスについては、 WebSocket モードでの Responses API の使用に関するページを参照してください。

セキュリティコントロールを適用する

ツリー内のすべてのエージェントは、元の要求で構成されたツールにアクセスできます。 ルート エージェントからの呼び出しに適用するサブエージェントからの呼び出しにも同じコントロールを適用します。

• ツールと呼び出し元の ID に、タスクに必要なアクセス許可のみを付与します。
• 関数の引数を検証し、アプリケーション コード内の各アクションを承認します。
• 書き込み、破壊的、財務的、またはその他の影響の大きいアクションの前に、ユーザーの承認を要求します。
• 外部ツールから返されたコンテンツを信頼できない入力として扱い、プロンプト挿入から保護します。
• 監査のために、エージェント名、ツール名、引数、承認決定、結果をログに記録します。
• サブエージェントによって使用量が増加する可能性があるため、委任された作業をバインドし、トークンの使用状況を監視します。

制限事項を確認する

• マルチエージェント オーケストレーションが有効になっている場合、 /responses/compact エンドポイントはサポートされません。
• 要求でcontext_managementが定義されていない場合でも、multi_agent.enabledがtrueされると、サーバー側の自動圧縮が有効になります。 圧縮は、ルート エージェントと各サブエージェントに対して個別に実行されます。
• 圧縮のしきい値は、 context_management.compact_threshold設定することでオーバーライドできます。
• reasoning.summary は、マルチエージェント オーケストレーションが有効になっている場合はサポートされません。
• max_tool_calls は、マルチエージェント オーケストレーションが有効になっている場合はサポートされません。
• max_concurrent_subagents は既定で 3 に設定されます。これは、ほとんどのワークロードに推奨されます。
• マルチエージェント オーケストレーションには、ツリーの深さまたは実行中に作成されたサブエージェントの合計数に固定制限はありません。 待機時間とトークンの使用を管理するために、コンカレンシーとバインドされた委任された作業を制御します。

マルチエージェント要求のトラブルシューティング

関連するコンテンツ

• Azure OpenAI Responses API を使用する
• 関数呼び出しを使用する
• WebSocket モードで Responses API を使用する