MENU

Microsoft Foundry Agent Serviceの専用エンドポイント移行手順｜agent_reference失敗を解決

Azure

Microsoft Foundry Agent ServiceのHosted Agentを呼び出すコードで、agent_referenceを指定してもエラーになる場合、原因は単なるリクエスト本文の仕様変更ではありません。共有のproject endpointにagent_referenceを渡してルーティングする旧方式から、各エージェントの専用endpointを直接呼び出す方式へ変わったことが主な原因です。

Python SDKでは、project.get_openai_client(agent_name="エージェント名")で専用endpointにバインドします。REST APIでは、Responsesなら/agents/{name}/endpoint/protocols/openai/responses、Invocationsなら/agents/{name}/endpoint/protocols/invocationsを使用します。リクエスト本文からagent_referenceを削除するだけでなく、プロトコルライブラリの更新、Hosted Agentの再デプロイ、プロトコル宣言、専用Entra IDへのRBAC付与まで確認する必要があります。(Microsoft Learn)

初期パブリックプレビューのホスティングバックエンド上にある既存デプロイは自動移行されません。Microsoftの公式資料では、旧バックエンドのサポート期限は2026年8月20日とされているため、該当環境は早めの対応が必要です。(Microsoft Learn)

目次

結論：agent_referenceではなく専用エンドポイントで呼び出す

旧方式と新方式の違いを整理すると、次のようになります。

項目Initial previewの旧方式最新バージョン
ルーティング方法共有project endpointへ送信し、body内のagent_referenceで対象を指定エージェントごとの専用endpointへ直接送信
Python SDKproject.get_openai_client()project.get_openai_client(agent_name="my-agent")
リクエスト本文extra_bodyにagent_referenceを追加agent_referenceは不要
Responses URL共有endpoint経由/agents/{name}/endpoint/protocols/openai/responses
Invocations URL初期プレビュー用の呼び出し経路/agents/{name}/endpoint/protocols/invocations
プロトコルの指定"v1""1.0.0"
ランタイムIDproject managed identityを共有エージェントごとの専用Entra ID
既存デプロイそのまま利用新バックエンドへ再デプロイが必要

重要なのは、エージェント名によるルーティング情報がrequest bodyからURLまたはSDKクライアントの設定へ移ったことです。新しい専用endpointに対して、古いagent_reference付きbodyを送り続ける設計にはしないでください。(Microsoft Learn)

今回の移行対象になる環境

次のいずれかに該当する場合は、初期プレビューからの移行対象である可能性が高いと考えられます。

  • 2026年4月より前にHosted Agentをデプロイした
  • azure-ai-agentserver-agentframeworkを使用している
  • azure-ai-agentserver-langgraphを使用している
  • 初期プレビューのHosting APIを利用した独自コードがある
  • extra_body内にagent_referenceを指定している
  • az cognitiveservices agent startやstopをCI/CDで実行している
  • protocol versionに"v1"を指定している
  • capability hostを作成するプロビジョニング処理が残っている

Microsoftの移行ガイドは、初期プレビュー用パッケージやカスタムHosting APIを使ってデプロイしたHosted Agentを対象としています。Foundry Agent Service内のすべてのエージェントコードを機械的に置き換えるのではなく、まずエージェント種別とデプロイ時期を確認してください。(Microsoft Learn)

旧コードが新バージョンで動かない理由

ルーティング先がrequest bodyからURLへ移った

旧方式では、共有project endpointにリクエストを送り、次のような情報をbodyへ追加して呼び出し先を決めていました。

extra_body={
    "agent_reference": {
        "name": "my-agent",
        "type": "agent_reference",
    }
}

最新バージョンでは、対象エージェントは専用endpointによって識別されます。SDKを使用する場合はagent_nameでクライアントを専用endpointへバインドし、REST APIの場合はURL内にエージェント名を含めます。

つまり、修正の本質は次の2点です。

  • agent_referenceをrequest bodyから取り除く
  • 呼び出し先をエージェント専用のprotocol URLへ変更する

旧デプロイは自動変換されない

呼び出し側のコードだけを変更しても、Hosted Agent自体が初期プレビューのバックエンド上に残っている場合は移行が完了しません。

最新バージョンでは、ホスティングバックエンド、プロトコルライブラリ、IDモデル、管理APIが変更されています。旧デプロイをそのまま新endpointへ接続するのではなく、対応するライブラリとプロトコル設定へ更新したうえで、新しいエージェントバージョンを再デプロイする必要があります。(Microsoft Learn)

専用エンドポイントへの移行手順

SDKと開発ツールを更新する

現在の公式デプロイ資料では、Python SDKとしてazure-ai-projects 2.3.0以降が案内されています。

python -m pip install --upgrade "azure-ai-projects>=2.3.0" azure-identity

Azure Developer CLIを利用している場合は、Foundry agents拡張機能も更新します。

azd ext install azure.ai.agents

古いSDKのままでは、get_openai_client(agent_name=...)や最新Hosted Agent管理APIを利用できない可能性があります。CI/CDでバージョンを固定している場合は、開発端末だけでなく、ビルド環境や実行環境の依存関係も確認してください。(Microsoft Learn)

エージェント側のプロトコルライブラリを更新する

最新バージョンでは、フレームワーク固有の旧アダプターから、次のプロトコル別ライブラリへ移行します。

用途最新ライブラリ
OpenAI互換の会話、ストリーミング、履歴管理azure-ai-agentserver-responses
任意JSON、Webhook、独自HTTP処理azure-ai-agentserver-invocations
Microsoft Agent Frameworkとの統合agent-framework-foundry-hostingとResponsesHostServer

Microsoft Agent Frameworkを使用している場合は、旧from_agent_framework(agent).run()からResponsesHostServer(agent).run()への変更が必要です。

LangGraphや独自コードでは、ResponsesAgentServerHostまたはInvocationAgentServerHostを使って、受信プロトコルに対応するハンドラーを実装します。(Microsoft Learn)

公開するプロトコルを宣言する

エージェント専用endpointが存在していても、エージェントバージョンで対象プロトコルを宣言していなければ、そのURLは利用できません。

Python SDKでは、HostedAgentDefinitionのprotocol_versionsへ公開するプロトコルを指定します。

from azure.ai.projects.models import (
    AgentEndpointProtocol,
    ProtocolVersionRecord,
)

protocol_versions = [
    ProtocolVersionRecord(
        protocol=AgentEndpointProtocol.RESPONSES,
        version="1.0.0",
    ),
]

ResponsesとInvocationsの両方を公開する場合は、次のように追加します。

protocol_versions = [
    ProtocolVersionRecord(
        protocol=AgentEndpointProtocol.RESPONSES,
        version="1.0.0",
    ),
    ProtocolVersionRecord(
        protocol=AgentEndpointProtocol.INVOCATIONS,
        version="1.0.0",
    ),
]

azure.yamlを利用している場合も、初期プレビューで指定していたversion: "v1"をversion: "1.0.0"へ変更します。設定変更後はazd up、azd deploy、またはSDKのcreate_versionで再デプロイし、ステータスがactiveになるまで待ってください。(Microsoft Learn)

Python SDKの呼び出しコードを修正する

変更前：agent_referenceで呼び出し先を指定

初期プレビューでは、共有project endpointから取得したOpenAIクライアントに、agent_referenceを追加していました。

openai_client = project.get_openai_client()

response = openai_client.responses.create(
    input=[{"role": "user", "content": "こんにちは"}],
    extra_body={
        "agent_reference": {
            "name": "my-agent",
            "type": "agent_reference",
        }
    },
)

変更後：agent_nameで専用endpointにバインド

最新バージョンでは、get_openai_client()へagent_nameを渡します。

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

openai_client = project.get_openai_client(
    agent_name=os.environ["FOUNDRY_AGENT_NAME"],
)

response = openai_client.responses.create(
    input="専用エンドポイントの疎通確認です",
)

print(response.output_text)

agent_nameを渡すと、SDKが対象エージェントの専用Responses endpointへクライアントをバインドします。extra_bodyのagent_referenceは不要です。

なお、inputを文字列で渡すか、OpenAI Responses互換の入力形式で渡すかはアプリケーションの設計によって変わります。移行時の重要点は、入力を必ず文字列にすることではなく、ルーティング目的のagent_referenceを削除することです。(Microsoft Learn)

REST APIを新しいプロトコルURLへ移行する

REST APIから呼び出す場合は、project endpointの末尾にエージェント名とプロトコルURLを追加します。

project endpointは、通常次の形式です。

https://<account>.services.ai.azure.com/api/projects/<project>

Responsesプロトコルを呼び出す

Responsesの専用URLは次の形式です。

{project_endpoint}/agents/{name}/endpoint/protocols/openai/responses

Azure CLIでアクセストークンを取得し、curlで呼び出す例は次のとおりです。

PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
AGENT_NAME="<agent-name>"
API_VERSION="v1"

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

curl -X POST \
  "${PROJECT_ENDPOINT}/agents/${AGENT_NAME}/endpoint/protocols/openai/responses?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "REST APIからの疎通確認です",
    "store": true
  }'

ストリーミングを利用する場合は、Responses APIの仕様に合わせてstreamを指定し、Server-Sent Eventsを処理するクライアントを使用します。

Invocationsプロトコルを呼び出す

Invocationsの専用URLは次の形式です。

{project_endpoint}/agents/{name}/endpoint/protocols/invocations
curl -X POST \
  "${PROJECT_ENDPOINT}/agents/${AGENT_NAME}/endpoint/protocols/invocations?api-version=${API_VERSION}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "この処理を実行してください"
  }'

Invocationsのrequest bodyはOpenAI Responses形式ではありません。エージェント側のInvocationAgentServerHostで定義した任意のJSONスキーマに合わせます。

専用endpointでは、URLとプロトコルの組み合わせが重要です。Responses用のbodyをInvocations URLへ送ったり、独自Webhook形式のbodyをResponses URLへ送ったりしないようにしてください。(Microsoft Learn)

ResponsesとInvocationsのどちらへ移行すべきか

一般的なチャット型エージェントでは、Responsesが第一候補です。Webhook受信や独自のJSON処理ではInvocationsが適しています。

判断項目ResponsesInvocations
主な用途チャット、RAG、ツール利用、マルチターン会話Webhook、分類、抽出、バッチ処理、独自API
request bodyOpenAI互換のResponses形式任意のJSON
会話履歴プラットフォームがconversation IDで管理アプリケーション側で管理
クライアントOpenAI互換SDKを利用可能独自HTTPクライアント
ストリーミングプラットフォーム管理のSSE独自SSEを実装可能
バックグラウンド処理標準機能あり独自の状態管理やポーリングを実装
向いている例社内FAQ、アシスタント、RAGチャットGitHub Webhook、帳票分類、独自ワークフロー

迷う場合はResponsesから始めるのが基本です。1つのHosted Agentで複数のプロトコルを公開することもできますが、利用するすべてのプロトコルをエージェントバージョンで宣言する必要があります。(Microsoft Learn)

3種類のバージョン番号を混同しない

移行時には、v1、1.0.0、2.0.0という似た値が登場します。それぞれ意味が異なります。

設定箇所現在の例意味
REST APIのクエリapi-version=v1FoundryデータプレーンAPIのバージョン
エージェントのプロトコル宣言version="1.0.0"ResponsesやInvocations endpointのプロトコルバージョン
Hosted Agentのコンテナープロトコル2.0.0リクエストごとのID伝達など、コンテナーと基盤間の契約

初期プレビューのProtocolVersionRecord(..., version="v1")は、最新バージョンでは"1.0.0"へ変更します。一方、REST URLのapi-version=v1は別の値なので、api-version=1.0.0へ書き換えるものではありません。

また、コンテナープロトコル2.0.0では、リクエストごとのx-agent-foundry-call-idが利用されます。公式SDKアダプターは必要な転送を処理しますが、コンテナーからFoundryサービスへ生のHTTPリクエストを送る独自実装では、受信したヘッダーを変更せず転送する必要があります。(Microsoft Learn)

専用Entra IDへのRBAC設定も確認する

最新バージョンでは、各Hosted Agentに専用のMicrosoft Entra IDがデプロイ時に作成されます。

初期プレビューでproject managed identityへ付与していたAzure Storage、Key Vault、Azure AI Searchなどの権限が、新しいエージェントIDへ自動的に引き継がれるとは限りません。

特に次のような症状では、endpointよりもRBACを疑う必要があります。

  • Hosted Agent自体の呼び出しは成功する
  • モデルからの単純な応答は返る
  • Azure Storageや社内APIへのアクセスだけ403になる
  • ToolboxやダウンストリームAzureサービスの呼び出しで失敗する
  • ローカルでは動くが、Foundry上のコンテナーでは権限エラーになる

最新モデルでは、project managed identityは主にコンテナーイメージの取得など、プラットフォーム側のインフラストラクチャ処理に使用されます。実行中のエージェントが外部Azureリソースへアクセスする場合は、そのエージェント専用Entra IDへ必要最小限のRBACロールを付与してください。(Microsoft Learn)

よくあるエラーと確認ポイント

症状主な原因対処
agent_reference関連の400エラー新endpointへ旧bodyを送っているextra_bodyからagent_referenceを削除する
専用URLが404になるagent名、project endpoint、protocol URLが誤っている/agents/{name}/endpoint/protocols/...の構造を確認する
Responses URLだけ404になるエージェントバージョンでResponsesを宣言していないprotocol_versionsへResponses 1.0.0を追加して再デプロイする
Invocations URLだけ404になるInvocationsを宣言していないInvocations 1.0.0を追加して新バージョンを作成する
401になるアクセストークンのaudienceが不正https://ai.azure.com/.default向けトークンを使用する
エージェント内部のAzureアクセスが403になるproject managed identityにしか権限がない専用エージェントIDへRBACを付与する
呼び出しても準備中になる新バージョンがcreatingのままactiveになるまで待ち、failedならerror内容を確認する
旧startコマンドが失敗する手動start／stop APIが削除された自動コンピューティングライフサイクルへ移行する
デプロイがfailedになるACR権限、イメージ名、CPUアーキテクチャなどの問題ACRのpull権限とlinux/amd64イメージを確認する
古いプレビュー用ヘッダーが残っている旧サンプルを流用しているFoundry-Features: HostedAgents=V1Previewへの依存を削除する

Hosted Agentは、リクエスト到着時にコンピューティングが自動的に用意され、一定時間使用されない場合は自動的にプロビジョニング解除されます。初期プレビューのように、呼び出し前にstartを実行する必要はありません。(Microsoft Learn)

安全に切り替えるための移行チェックリスト

本番環境を移行する際は、次の順番で確認すると切り分けしやすくなります。

  • リポジトリ全体からagent_referenceを検索する
  • 引数なしのproject.get_openai_client()を使用している箇所を確認する
  • azure-ai-projectsを2.3.0以降へ更新する
  • 旧Agent Serverアダプターパッケージを新プロトコルライブラリへ置き換える
  • protocol versionを"v1"から"1.0.0"へ変更する
  • ResponsesまたはInvocationsをエージェントバージョンで宣言する
  • Hosted Agentを新バックエンドへ再デプロイする
  • バージョンがactiveになったことを確認する
  • SDKではget_openai_client(agent_name=...)へ変更する
  • RESTでは専用protocol URLへ変更する
  • request bodyからagent_referenceを削除する
  • 専用エージェントEntra IDのRBACを確認する
  • 旧start、stop、capability host作成処理を削除する
  • 非ストリーミング、ストリーミング、ツール呼び出しを個別にテストする
  • 本番切り替え前に旧endpointへ依存する設定値や環境変数が残っていないか確認する

実務上は、既存コードを直接上書きするより、専用endpointを新しい環境変数として追加し、疎通確認後に参照先を切り替える方が安全です。問題が起きたときに、旧ルーティング、新endpoint、RBAC、エージェント内部処理のどこで失敗したかを分離できます。

まとめ：最初にagent_referenceと呼び出しURLを検索する

agent_referenceを使ったHosted Agent呼び出しが失敗する場合は、次の3点を優先して修正します。

  1. project.get_openai_client(agent_name="...")または専用protocol URLへ切り替える
  2. request bodyからルーティング用のagent_referenceを削除する
  3. 新プロトコルを宣言したHosted Agentを再デプロイし、専用Entra IDのRBACを確認する

最初にコードベースとCI/CDから、agent_reference、旧Agent Serverパッケージ、version: "v1"、az cognitiveservices agent start、プレビュー用ヘッダーを検索してください。その結果を基に、呼び出し側だけでなく、デプロイ定義とID設定を含めて移行することが、最短の解決方法です。

Azure
Responses API Microsoft Foundry Foundry Agent Service Azure AI Projects SDK Hosted Agent

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次