MENU

旧Foundry Hosted Agentを停止せず移行する方法｜2026年8月20日までの再デプロイ手順

Azure

2026年4月より前に、初期パブリックプレビュー版でデプロイしたMicrosoft Foundry Agent ServiceのHosted Agentは、2026年8月20日で旧ホスティングバックエンドのサポートが終了します。既存デプロイは自動移行されません。

サービスを停止させずに移行するには、旧Hosted Agentを稼働させたまま、新しいプロトコルライブラリ、API、専用Entra ID、azure.yamlを使って新バックエンドへ並行デプロイします。その後、新バージョンがactiveになり、機能テストに合格したことを確認してから、アプリケーションの接続先を切り替えるのが安全です。SDKだけを更新しても移行は完了しません。(Microsoft Learn)

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

まず結論：旧Hosted Agentは自動移行されない

今回の対応は、既存環境に対するインプレース更新ではありません。

必要なのは、次の流れです。

  1. 現在のHosted Agent、呼び出し元、権限、ツール構成を棚卸しする
  2. 新しいプロトコルライブラリに合わせてコードを変更する
  3. API呼び出しを専用エージェントエンドポイント方式へ変更する
  4. azure.yamlを新形式へ更新する
  5. 新バックエンドへHosted Agentを再デプロイする
  6. 新しいエージェント専用Entra IDへRBACを付与する
  7. ステータスがactiveになったことを確認する
  8. 機能テスト後に呼び出し先を切り替える
  9. 問題がなければ旧デプロイを廃止する

停止時間を避けたい場合は、旧環境を先に削除したり、同じ本番エージェントへいきなりazd deployしたりしてはいけません。新旧を一時的に並行稼働させるブルーグリーン方式が最も安全です。

なお、2026年8月20日はサポート期限です。その時刻に必ず即時停止するとは限りませんが、旧バックエンドが継続稼働することを前提に運用計画を立てるべきではありません。

移行対象かを判定する

Microsoftの移行ガイドは、主に次のHosted Agentを対象としています。

  • 2026年4月より前にデプロイした
  • azure-ai-agentserver-agentframeworkを使用している
  • azure-ai-agentserver-langgraphを使用している
  • 初期プレビュー版のホスティングAPIをカスタムコードから呼び出している
  • 共有プロジェクトエンドポイントへagent_referenceを渡している
  • az cognitiveservices agent startやstopを実行している
  • agent.manifest.yamlまたは単独のagent.yamlを使用している
  • Capability Hostを明示的に作成している

一つでも該当する場合は、今回の移行対象として調査を進める必要があります。Microsoftは、旧バックエンド上のエージェントを自動では新バックエンドへ移行しないと明記しています。(Microsoft Learn)

注意

ここでいうHosted Agentは、Microsoft Foundry Agent ServiceのHosted Agentです。Azure DevOpsやAzure PipelinesのMicrosoft-hosted agentとは別のサービスです。

2026年4月以降にデプロイしたエージェントでも、コンテナープロトコル1.0.0を使用している場合は確認が必要です。現在のランタイム契約では2.0.0が現行で、1.0.0は非推奨とされています。(Microsoft Learn)

新バックエンドで変わるポイント

旧Hosted Agentと新しい仕組みでは、単に実行基盤が変わるだけではありません。エンドポイント、ID、プロトコル、セッション、管理APIも変更されます。

項目初期プレビュー版新しいバックエンド
コンピュート管理手動で開始・停止・レプリカ管理リクエスト時に自動起動し、アイドル後に自動解放
実行分離従来のホスティング方式セッション単位のサンドボックス
ライブラリフレームワーク別アダプタープロトコル別ライブラリ
エンドポイント共有プロジェクトエンドポイントエージェントごとの専用エンドポイント
呼び出し方法agent_referenceを本文に指定agent_nameにバインドしたクライアント
実行IDプロジェクトのマネージドIDを共有エージェントごとの専用Entra ID
構成ファイルagent.manifest.yaml、agent.yaml単一のazure.yaml
ツール定義create_versionのtoolsFoundry ToolboxをMCP経由で使用
ステータスStopped、Startedなどcreating、active、failedなど
CLIaz cognitiveservices agentazd ai agentまたはREST API

新バックエンドでは、コンピュートはリクエスト到着時に自動で用意され、15分間使用されないと自動的に解放されます。そのため、従来のstart、stop、最小・最大レプリカ設定を移植する必要はありません。(Microsoft Learn)

「v1」「1.0.0」「2.0.0」を混同しない

今回の移行では、複数種類の「バージョン」が登場します。ここを混同すると、正しい設定を書き換えてしまうことがあります。

表記例意味
api-version=v1Foundry Agent ServiceのREST APIバージョン
protocols[].version: "2.0.0"Hosted Agentコンテナーのランタイムプロトコル
agent_version="3"デプロイしたエージェントのバージョン番号
旧ProtocolVersionRecord(..., version="v1")初期プレビューで使われていた古いプロトコル表記

REST APIのクエリに指定するapi-version=v1は、コンテナープロトコルの旧"v1"とは別物です。REST API側のv1を2.0.0に置き換えてはいけません。(Microsoft Learn)

また、Microsoftの移行ページには、旧"v1"をセマンティックバージョン形式の"1.0.0"へ変更する例が残っています。一方、同じページではコンテナープロトコル1.0.0を非推奨とし、現行の2.0.0への移行を案内しています。最新のazure.yamlリファレンスも2.0.0を使用しています。

したがって、これから新バックエンドへ再デプロイする場合は、最新のazd ai agent initが生成する設定を基準に、コンテナープロトコル2.0.0を採用するのが安全です。古い記事やサンプルの1.0.0をそのままコピーしないようにしてください。(Microsoft Learn)

停止させないための推奨構成

停止時間を避けるには、旧Hosted Agentを残したまま、新Hosted Agentを別名でデプロイします。

利用アプリケーション
        |
        | 接続先を設定値で切り替え
        |
        +-- 旧Hosted Agent
        |     旧バックエンド
        |     現在の本番処理を継続
        |
        +-- 新Hosted Agent
              新バックエンド
              active確認・移行テスト

新しいエージェント名の例は次のとおりです。

旧：customer-support-agent
新：customer-support-agent-vnext

アプリケーション側では、エージェント名やエンドポイントをコードへ直接埋め込まず、Azure App Configuration、Key Vault、環境変数などで切り替えられるようにします。

別名で再デプロイするメリット

別名でデプロイすると、次のリスクを抑えられます。

  • 新デプロイが失敗しても旧環境へ影響しない
  • RBACを本番切り替え前に検証できる
  • 新旧APIの呼び出し方法を並行してテストできる
  • 切り替え後も設定を戻すだけでロールバックできる
  • azd deployによる意図しないバージョン切り替えを避けられる
  • 旧セッションと新セッションを分けて管理できる

特に、azd deployは新しいエージェントバージョンを作成し、最新バージョンを既定でアクティブにします。同一エージェント名で安全に切り替えたい場合は、SDKまたはREST APIでバージョンを作成し、active確認後に明示的にルーティングを変更する方法が適しています。(Microsoft Learn)

Foundry側では段階的なトラフィック分割ができない

Foundry Agent Serviceのエンドポイントは、一つのエージェントバージョンへ100％のトラフィックをルーティングします。バージョン間の10％、50％といった重み付き分割はサポートされていません。(Microsoft Learn)

段階移行を行う場合は、次のいずれかで制御します。

  • 呼び出し元アプリケーションの機能フラグ
  • Azure API Management
  • 独自のバックエンドルーター
  • ユーザー、テナント、部署単位の設定
  • 新規セッションだけを新エージェントへ送るセッションルーティング

ツールがデータ更新、メール送信、チケット作成などの副作用を伴う場合、同じリクエストを新旧両方へ送るシャドーテストは避けてください。二重登録や二重通知が発生する可能性があります。

停止ゼロとセッション継続は別に考える

ブルーグリーン移行により、サービスそのものの停止は避けられます。ただし、既存の会話履歴やセッションファイルが新バックエンドへ自動的に引き継がれるとは限りません。

新バックエンドは、セッション単位のサンドボックスと、ターンやアイドル期間をまたいで維持される$HOMEおよび/filesを採用しています。一方、旧デプロイは自動移行されないため、既存セッションを新エージェントでそのまま再開できる前提にはしない方が安全です。(Microsoft Learn)

実務上は、次のどちらかを選びます。

  • 既存セッションは旧エージェントで終了させ、新規セッションから新エージェントへ送る
  • 切り替え日時を区切り、それ以降は新しい会話セッションとして開始する

長時間継続する業務セッションがある場合は、セッションIDとバックエンドの対応を呼び出し元で保持する設計が必要です。

移行前に棚卸しする項目

コード修正を始める前に、現在の構成を記録します。

確認対象記録する内容移行で必要になる理由
エージェント名前、バージョン、作成日移行対象の判定とロールバック
呼び出し先プロジェクトエンドポイント、APIパス専用エンドポイントへの変更
SDKパッケージ名、バージョン、ロックファイル削除されたアダプターの特定
エントリーポイントmain.py、起動コマンド新しいHostServerへの変更
構成ファイルazure.yaml、agent.yaml、マニフェスト単一azure.yamlへの統合
コンテナーDockerfile、イメージタグ、CPU、メモリlinux/amd64での再ビルド
IDプロジェクトのマネージドID専用エージェントIDへの権限移行
RBACStorage、Cosmos DB、Key Vaultなど新IDへの再付与
ツールMCP、検索、独自APIToolbox経由への変更確認
状態管理会話履歴、セッション、ファイルセッション継続方法の判断
CI/CDstart、stop、updateなどのコマンド削除済みCLIの置換
監視Application Insights、ログ、アラート新旧比較と切り替え判断
ネットワークACR、Private Endpoint、Firewallイメージ取得失敗の防止
呼び出し元Webアプリ、バッチ、Teams Botなど接続先切り替え対象の把握

コンテナーイメージについては、現在稼働しているイメージのタグだけでなく、可能であればダイジェストも記録します。latestのような可変タグだけでは、問題発生時に同じイメージへ戻せません。

旧Foundry Hosted Agentを新バックエンドへ再デプロイする手順

移行用ブランチとベースラインを作成する

本番ブランチへ直接変更を加えず、移行専用ブランチを作成します。

git switch -c migrate-foundry-hosted-agent

移行前に、次の結果を保存しておきます。

  • 正常系の代表的な質問と応答
  • ツール呼び出し結果
  • 主要なエラー応答
  • 会話履歴を利用する複数ターンの応答
  • 現在の応答時間
  • 現在のエラー率
  • 外部リソースへの読み書き結果

生成AIの応答文を一字一句一致させる必要はありません。業務要件、ツール選択、出力形式、データ更新結果が同等かを比較します。

SDK、Azure Developer CLI、Azure CLIを更新する

現行ドキュメントでは、次のバージョンが前提です。

  • Azure AI Projects SDK：2.3.0以上
  • Azure Developer CLI：1.23.0以上
  • Azure CLI：2.80以上
  • Foundry agents拡張：最新のazure.ai.agents
python -m pip install -U "azure-ai-projects>=2.3.0" azure-identity

azd ext install azure.ai.agents

azd version
az version

Microsoftの移行ページ末尾のチェックリストにはazure-ai-projects 2.1.0以上という表記もありますが、同じページの前提条件と現行のデプロイ・管理ドキュメントは2.3.0以上を要求しています。実務では、より新しい要件である2.3.0以上にそろえるのが安全です。(Microsoft Learn)

更新後は、requirements.txt、pyproject.toml、poetry.lockなどの依存関係ファイルも更新し、開発端末だけが新しい状態にならないようにします。

プロトコルライブラリとエントリーポイントを変更する

フレームワークによって変更方法が異なります。

利用形態旧構成新構成
Microsoft Agent Frameworkazure-ai-agentserver-agentframework更新版Agent Frameworkとagent-framework-foundry-hosting
LangGraphazure-ai-agentserver-langgraphazure-ai-agentserver-responses
独自チャットエージェントフレームワーク固有アダプターazure-ai-agentserver-responses
Webhook・任意JSON処理独自HTTP実装azure-ai-agentserver-invocations
.NET ResponsesAzure.AI.AgentServer.AgentFrameworkAzure.AI.AgentServer.Responses
.NET InvocationsAzure.AI.AgentServer.AgentFrameworkAzure.AI.AgentServer.Invocations

(Microsoft Learn)

Microsoft Agent Frameworkの場合

主な変更点は次のとおりです。

  • AzureAIAgentClientをFoundryChatClientへ変更
  • ChatAgentをAgentへ変更
  • @ai_functionを@toolへ変更
  • from_agent_framework(agent).run()をResponsesHostServer(agent).run()へ変更
  • プラットフォーム側で履歴を管理するためstore=False相当を設定

概念的には、次のようにエントリーポイントを変更します。

from agent_framework_foundry_hosting import ResponsesHostServer

agent = Agent(
    client=client,
    instructions="You are a helpful assistant.",
    tools=tools,
    default_options={"store": False},
)

ResponsesHostServer(agent).run()

LangGraphの場合

LangGraphのグラフ定義やツールロジックは基本的に維持できますが、ホスティング部分を変更します。

  • azure-ai-agentserver-langgraphを削除
  • azure-ai-agentserver-responsesを追加
  • from_langgraph(graph).run()を廃止
  • ResponsesAgentServerHostへハンドラーを登録
  • context.get_history()で会話履歴を取得
  • 必要に応じてLangChainのメッセージ形式へ変換

履歴を変換せずに現在のユーザー入力だけをグラフへ渡すと、移行後に複数ターン会話が成立しなくなるため注意が必要です。

独自コードの場合

通常の会話型エージェントは、Responsesプロトコルを選びます。

from azure.ai.agentserver.responses import (
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()

@app.response_handler
async def handle(request, context, cancellation_signal):
    text = await context.get_input_text()
    return TextResponse(context, request, text=f"Echo: {text}")

app.run()

Webhookや独自JSONをそのまま受け渡す処理では、InvocationAgentServerHostを使用します。Responsesプロトコルは会話履歴を管理しますが、Invocationsプロトコルでは状態管理をアプリケーション側で実装します。(Microsoft Learn)

azure.yamlを新形式へ統合する

旧構成で使われていたagent.manifest.yamlと単独のagent.yamlは非推奨です。新しい構成では、プロジェクト、モデル、接続、Toolbox、Hosted Agentの定義をルートのazure.yamlへ統合します。(Microsoft Learn)

移行時は、旧ファイルを手作業で継ぎ足すよりも、最新の拡張機能でひな型を生成し、現在の設定を移植する方が安全です。

azd ai agent init

Hosted Agent部分の最小構成例は次のとおりです。

services:
  my-agent-vnext:
    host: azure.ai.agent
    project: src/my-agent
    language: docker
    uses:
      - ai-project
    kind: hosted
    name: my-agent-vnext

    protocols:
      - protocol: responses
        version: "2.0.0"

    startupCommand: python main.py

    env:
      MODEL_DEPLOYMENT_NAME: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}

    container:
      resources:
        cpu: "1.0"
        memory: 2Gi

ai-projectは、同じazure.yaml内で定義したazure.ai.projectサービス名です。既存のFoundryプロジェクトを再利用する場合は、そのプロジェクトへ接続する構成にします。

FOUNDRY_PROJECT_ENDPOINTはホスティングプラットフォームが自動注入するため、envで上書きしないでください。誤ったエンドポイントを設定すると、ローカルでは動作してもHosted Agent上でモデルへ接続できなくなる可能性があります。(Microsoft Learn)

コンテナープロトコル2.0.0へ対応する

コンテナープロトコル2.0.0では、リクエストごとのユーザー情報とFoundry呼び出し情報がヘッダーで渡されます。

ヘッダー用途
x-agent-user-idユーザーごとの保存データを分離するための識別子
x-agent-foundry-call-idFoundryサービスへの下流呼び出しで転送する識別子

公式SDKアダプターを通じてStorage、Toolbox、他のエージェントなどを呼び出す場合、x-agent-foundry-call-idは自動的に処理されます。独自のHTTPクライアントでFoundryサービスを呼び出す場合は、受信した値を解析せず、そのまま下流リクエストへ転送します。(Microsoft Learn)

複数ユーザーが一つのセッションを共有する可能性がある場合、保存データのキーにはセッションIDだけでなくx-agent-user-idも含めます。

悪い例：
session_id/notes.json

推奨例：
user_id/session_id/notes.json

ローカル実行時には、これらのヘッダーが存在しない場合があります。ヘッダーがないと例外になる実装ではなく、ローカル用の代替値を扱えるようにします。

独自の追加ヘッダーをコンテナーへ渡したい場合は、x-client-で始まる名前を使用します。許可リスト外の任意ヘッダーやAuthorizationヘッダーは、そのままコンテナーへ転送されません。(Microsoft Learn)

呼び出しAPIを専用エンドポイント方式へ変更する

旧方式では、共有プロジェクトエンドポイントを使用し、リクエスト本文へagent_referenceを追加していました。

openai_client = project.get_openai_client()

response = openai_client.responses.create(
    input="Hello",
    extra_body={
        "agent_reference": {
            "name": "my-agent",
            "type": "agent_reference",
        }
    },
)

新方式では、クライアント作成時にエージェント名を指定します。

openai_client = project.get_openai_client(
    agent_name="my-agent-vnext"
)

response = openai_client.responses.create(
    input="Hello"
)

print(response.output_text)

SDKがエージェント専用エンドポイントへバインドするため、extra_bodyのagent_referenceは不要です。(Microsoft Learn)

REST APIからResponsesプロトコルを呼び出す場合は、次の形式の専用ルートを使用します。

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

Invocationsプロトコルの場合は、次のルートです。

{project_endpoint}/agents/{agent_name}/endpoint/protocols/invocations

初期プレビューで使われていたFoundry-Features: HostedAgents=V1Previewヘッダーは、現行のv1 APIとazure-ai-projects 2.3.0以降では通常不要です。古いヘッダーを付けたままにする場合も、削除後の動作をテストしてから整理します。(Microsoft Learn)

削除された管理処理を取り除く

次のCLIやAPIをCI/CDへ残してはいけません。

旧処理新バックエンドでの対応
az cognitiveservices agent start不要。リクエスト時に自動起動
az cognitiveservices agent stop不要。アイドル後に自動解放
agent update --min-replicas削除。セッションベースで自動スケール
agent update --max-replicas削除。セッションベースで自動スケール
delete-deployment対象バージョンを削除
list-versionsaz restまたはSDKを使用
Capability Host作成削除。プラットフォームが自動管理
create_versionのtoolsFoundry ToolboxをMCP経由で使用

(Microsoft Learn)

旧スクリプトのstartが失敗するからといって、新エージェントのデプロイに失敗したとは限りません。新バックエンドでは、そもそも開始コマンドを実行しない設計です。

専用Entra IDへRBACを付け直す

IDモデルの変更は、移行で最も401、403エラーが起きやすい部分です。

初期プレビューでは、プロジェクトのマネージドIDが実行時IDとして使用されていました。新バックエンドでは、Hosted Agentごとに専用のMicrosoft Entra IDサービスプリンシパルがデプロイ時に作成されます。

したがって、プロジェクトのマネージドIDに付けた権限は、新しいエージェントIDへ自動的には移りません。Azure Storage、Cosmos DB、Key Vault、Azure AI Searchなどへアクセスする場合は、新エージェントIDへ必要なRBACを付与します。(Microsoft Learn)

一方、プロジェクトのマネージドIDは、引き続きAzure Container Registryからコンテナーイメージを取得するためのインフラストラクチャIDとして使用されます。

整理すると、次のようになります。

ID主な役割
プロジェクトのマネージドIDACRからのコンテナーイメージ取得など
エージェント専用Entra IDモデル、Storage、Cosmos DB、Toolboxなどの実行時アクセス
デプロイ実行者Hosted Agentの作成・更新

Hosted Agentをデプロイするユーザーまたはサービスプリンシパルには、プロジェクトスコープのFoundry Project Managerロールが必要です。旧名称のAzure AI Project Managerが画面に残っている場合がありますが、ロール名称変更中の表示差です。(Microsoft Learn)

エージェントIDを取得する

新Hosted Agentの初回デプロイ後、REST APIからinstance_identity.principal_idを取得できます。

ACCOUNT_NAME="<foundry-account-name>"
PROJECT_NAME="<project-name>"
AGENT_NAME="my-agent-vnext"

BASE_URL="https://${ACCOUNT_NAME}.services.ai.azure.com/api/projects/${PROJECT_NAME}"

AGENT_IDENTITY=$(az rest \
  --method GET \
  --url "${BASE_URL}/agents/${AGENT_NAME}?api-version=v1" \
  --resource "https://ai.azure.com" \
  --query "instance_identity.principal_id" \
  --output tsv)

echo "${AGENT_IDENTITY}"

Foundry Agent Serviceのデータプレーンをaz restで呼び出す場合は、--resource "https://ai.azure.com"が必要です。省略すると、正しいトークンの対象リソースを判定できず、認証エラーになることがあります。 (Microsoft Learn)

外部リソースへRBACを付与する

たとえば、Storage Blobの読み書きを許可する場合は次のようにします。

az role assignment create \
  --assignee-object-id "${AGENT_IDENTITY}" \
  --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Data Contributor" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>"

エージェントIDはサービスプリンシパルであるため、--assignee-principal-type ServicePrincipalを指定すると、Microsoft Graphによる名前解決に依存せず割り当てられます。(Microsoft Learn)

すべての外部リソースへ広い権限を付けるのではなく、必要なリソーススコープと操作に限定してください。

新バックエンドへ並行デプロイする

構成変更が完了したら、新しいエージェント名でデプロイします。

azd auth login
azd up

Azureリソースがすでに用意され、コード変更だけをデプロイする場合は、次のコマンドを使用します。

azd deploy

azd deployはコンテナーをビルドしてレジストリへ登録し、新しいHosted Agentバージョンを作成します。以前のバージョンは保持されます。(Microsoft Learn)

ローカルでイメージを作成する場合は、必ずlinux/amd64を指定します。

docker build \
  --platform linux/amd64 \
  -t myregistry.azurecr.io/my-agent:vnext-20260723 \
  .

Hosted Agentのホスティング基盤はx86_64イメージを要求します。Apple SiliconやARM環境でプラットフォーム指定を省略すると、ローカルではビルドできてもHosted Agent上で起動できないことがあります。また、ロールバックを可能にするため、:latestではなく一意のタグまたはダイジェストを使用します。(Microsoft Learn)

古いプロジェクトとプライベートACRの組み合わせに注意する

2026年6月25日より前に作成されたFoundryプロジェクトでは、Hosted Agentが利用するAzure Container Registryを、プライベートエンドポイントだけで到達させる構成に制約があります。

同じ旧プロジェクトを再利用する場合、ACRのパブリックネットワークアクセスを完全に無効化していると、プラットフォームがイメージを取得できない可能性があります。対象プロジェクトの作成日、ACRの公開設定、Firewall、Private Endpointをデプロイ前に確認してください。(Microsoft Learn)

active状態とログを確認する

デプロイ後は、エージェントバージョンがactiveになるまでステータスを確認します。

azd ai agent show --output table

主な状態は次のとおりです。

ステータス意味
creatingインフラストラクチャを準備中
activeリクエストを処理できる状態
failedデプロイまたは起動に失敗
deletingバージョンを削除中
deleted削除済み

(Microsoft Learn)

failedになった場合は、ログを確認します。

azd ai agent monitor

スモークテストも実行します。

azd ai agent invoke \
  --input "移行確認です。利用可能な機能を簡潔に回答してください。"

activeは、バージョンがリクエストを処理できる状態であることを示します。ただし、新バックエンドはコンピュートを常時稼働させる方式ではありません。アイドル状態からの最初のリクエストでは、後続リクエストより応答に時間がかかる可能性があります。

切り替え直前にスモークテストを実行し、コールドスタート時と連続呼び出し時の両方を確認してください。

本番切り替え前に実施するテスト

単に一度回答が返ればよいわけではありません。次のテストを実施します。

テスト確認内容
単一ターン基本的な質問に回答できる
複数ターン過去の発言を参照できる
ストリーミング途中応答が正しく配信される
ツール呼び出し正しいツールと引数が選択される
MCPToolboxや外部MCPへ接続できる
Storage読み書きとユーザー分離が正しい
Cosmos DB専用IDでアクセスできる
Key Vault必要なシークレットだけ取得できる
ファイルセッションファイルを保存・取得できる
認証正常ユーザーと未許可ユーザーを区別できる
同時実行複数ユーザーの情報が混ざらない
エラー処理タイムアウトや外部API障害を処理できる
副作用二重登録や二重送信が起きない
ログApplication Insightsへ記録される
応答性能旧環境から許容できない悪化がない

特にx-agent-user-idを利用するエージェントでは、ユーザーAの保存データをユーザーBが取得できないことを明示的に検証します。

Agent FrameworkやResponses APIでモデル側のstoreも有効にすると、プラットフォームの履歴管理と二重になる可能性があります。新しいサンプルに合わせてstore=Falseを基本とし、会話履歴の管理場所を一つに統一します。(Microsoft Learn)

本番トラフィックを切り替える

新Hosted Agentがactiveになり、テストに合格したら、呼び出し元の設定を変更します。

たとえば、環境変数で切り替える場合は次のようにします。

移行前：
FOUNDRY_AGENT_NAME=customer-support-agent

移行後：
FOUNDRY_AGENT_NAME=customer-support-agent-vnext

エンドポイントを直接管理している場合は、専用エージェントエンドポイントへ変更します。

安全な切り替え順序は次のとおりです。

  1. 新エージェントへスモークテストを送る
  2. 社内ユーザーや検証テナントだけを新エージェントへ送る
  3. 401、403、404、5xx、ツール失敗率を確認する
  4. 新規セッションを新エージェントへ送る
  5. 全トラフィックを新エージェントへ切り替える
  6. 旧エージェントへの新規リクエストがないことを確認する
  7. 一定期間、旧環境をロールバック先として保持する
  8. 問題がなければ旧デプロイを廃止する

旧方式と新方式ではリクエスト形式が異なるため、複数の呼び出し元がある場合は、各アプリを直接変更するより、共通の呼び出しアダプターを用意した方が安全です。

def get_agent_client(project, use_vnext: bool):
    agent_name = (
        "customer-support-agent-vnext"
        if use_vnext
        else "customer-support-agent"
    )

    return project.get_openai_client(agent_name=agent_name)

実際には旧方式がagent_referenceを必要とするため、旧用と新用の実装を分け、機能フラグで選択します。

ロールバック条件を事前に決める

切り替え後に問題が見つかってから判断を始めると、復旧が遅れます。事前にロールバック条件を決めてください。

代表的な条件は次のとおりです。

  • 旧環境より5xxエラー率が明確に悪化した
  • StorageやCosmos DBで403が継続する
  • 重要なMCPツールが呼び出せない
  • 複数ターンの会話履歴が失われる
  • ユーザー間で保存データが混在する
  • 二重登録や二重通知が発生した
  • 応答時間が業務上の許容値を超えた
  • Application Insightsへ必要なログが記録されない

ロールバックは、新Hosted Agentを削除する操作ではありません。まず呼び出し元の設定を旧エージェントへ戻します。新エージェントは原因調査のため残し、修正後に再テストします。

ただし、旧バックエンドを2026年8月20日以降の恒久的なロールバック先にすることはできません。期限前に修正、再切り替え、安定確認まで終えられる日程を組む必要があります。

CI/CDで修正するポイント

CI/CDパイプラインでは、次のような変更が必要です。

旧パイプライン新パイプライン
古いアダプターパッケージをインストールResponsesまたはInvocationsライブラリをインストール
agent.manifest.yamlを参照azure.yamlを参照
Capability Hostを作成処理を削除
az cognitiveservices agent start処理を削除
az cognitiveservices agent stop処理を削除
レプリカ数を更新処理を削除
agent_referenceで疎通確認agent_nameにバインドして呼び出す
プロジェクトIDへ外部権限を付与エージェント専用IDへ権限を付与
プロトコル"v1"コンテナープロトコル"2.0.0"
ARM向けイメージをビルドlinux/amd64でビルド
latestタグ一意のタグまたはダイジェスト
デプロイ成功だけ確認activeと機能テストを確認

パイプラインでは、デプロイコマンドが成功しただけで本番切り替えを行わないようにします。

最低でも、次のゲートを設けます。

ビルド成功
  ↓
新バージョン作成
  ↓
status == active
  ↓
スモークテスト成功
  ↓
RBACテスト成功
  ↓
承認または自動判定
  ↓
接続先切り替え

同じエージェント名に対してazd deployすると、最新バージョンが既定でアクティブになるため、厳密な承認ゲートが必要な環境では、別名デプロイまたはSDK・REST APIによる明示的なルーティングを使用します。(Microsoft Learn)

よくある移行失敗と対処方法

症状主な原因対処
az restが401になるトークン対象リソースが違う--resource "https://ai.azure.com"を指定
ツール呼び出しが403になるプロジェクトIDにしかRBACがない新エージェントのprincipal_idへ付与
ステータスがfailedになるARMイメージ、起動コマンド、依存関係linux/amd64、startupCommand、ログを確認
/readinessで失敗する独自サーバーがランタイム契約を満たさない公式プロトコルライブラリを使用
呼び出しが404になる共有エンドポイントを呼んでいる専用エージェントエンドポイントへ変更
会話履歴が消えるcontext.get_history()を処理していない履歴をフレームワークのメッセージへ変換
応答や履歴が重複するモデルとプラットフォームの双方で保存store=Falseを基本に管理場所を統一
Foundryの下流APIが403になるx-agent-foundry-call-idを転送していない独自HTTP呼び出しで値をそのまま転送
ユーザーの保存データが混ざるセッションIDだけでデータを分割x-agent-user-idもキーへ含める
ACRからイメージを取得できない旧プロジェクトとプライベートACRの制約ACRのネットワーク到達性を確認
新版へ勝手に切り替わった同一名でazd deployした別名デプロイまたは明示的ルーティング
ツールが見つからないcreate_versionのtoolsを使用Foundry ToolboxとMCPへ移行

公式のResponsesまたはInvocationsライブラリを使うと、HTTPポート8088、/readiness、SSE、終了処理、テレメトリなどのランタイム契約をライブラリ側で処理できます。独自Webサーバーを一から実装するより、移行時の失敗箇所を減らせます。(Microsoft Learn)

2026年8月20日までの移行計画例

2026年7月下旬から対応を始める場合は、期限直前に本番切り替えを行わないよう、次の日程を目安にします。

期間実施内容完了条件
7月23日～7月29日対象判定、構成棚卸し、移行ブランチ作成依存関係、ID、呼び出し元を一覧化
7月30日～8月5日ライブラリ、API、azure.yamlの更新ローカルテスト成功
8月6日～8月9日新バックエンドへ並行デプロイステータスがactive
8月10日～8月12日RBAC、ツール、履歴、同時実行テスト重要テストがすべて成功
8月13日～8月15日限定ユーザーで段階移行エラー率と応答性能が許容範囲
8月16日～8月17日全トラフィックを切り替え旧環境への新規呼び出しがない
8月18日～8月19日安定確認、残課題対応ロールバック不要と判断
8月20日旧環境を本番経路から完全に除外新バックエンドのみで運用

8月20日を本番切り替え日にすると、問題発生時の修正時間がありません。遅くとも数日前までに全トラフィックを新環境へ切り替え、期限前に安定確認を完了させます。

最終チェックリスト

  • [ ] 対象エージェントが2026年4月より前のデプロイか確認した
  • [ ] 古いアダプターパッケージを特定した
  • [ ] azure-ai-projectsを2.3.0以上へ更新した
  • [ ] azdを1.23.0以上へ更新した
  • [ ] azure.ai.agents拡張を更新した
  • [ ] Agent Framework、LangGraph、独自コードのエントリーポイントを変更した
  • [ ] agent.manifest.yamlと旧agent.yamlをazure.yamlへ統合した
  • [ ] コンテナープロトコルを2.0.0へ更新した
  • [ ] agent_reference方式を廃止した
  • [ ] 専用エージェントエンドポイントへ変更した
  • [ ] start、stop、レプリカ管理処理を削除した
  • [ ] Capability Host作成処理を削除した
  • [ ] ToolboxとMCPの動作を確認した
  • [ ] linux/amd64イメージを作成した
  • [ ] 一意のイメージタグまたはダイジェストを使用した
  • [ ] 新しいエージェント専用Entra IDを取得した
  • [ ] 外部Azureリソースへ必要なRBACを付与した
  • [ ] 新バージョンがactiveになった
  • [ ] 単一ターンと複数ターンをテストした
  • [ ] ユーザー間のデータ分離をテストした
  • [ ] コールドスタートと連続呼び出しを確認した
  • [ ] ロールバック方法と判断条件を決めた
  • [ ] 呼び出し元の設定で新旧を切り替えられる
  • [ ] 2026年8月20日より前に全トラフィックを移行した
  • [ ] 旧バックエンドを本番経路から除外した

まとめ：active確認後に接続先を切り替える

旧Foundry Hosted Agentの移行は、既存デプロイを更新する作業ではなく、新しいバックエンドへ再デプロイする作業です。

停止を避けるための重要なポイントは、次の5点です。

  • 旧Hosted Agentを残したまま、新しい名前で並行デプロイする
  • プロトコルライブラリ、API、azure.yamlをまとめて更新する
  • コンテナープロトコル2.0.0へ対応する
  • 新しいエージェント専用Entra IDへRBACを付け直す
  • activeと機能テストを確認してから接続先を切り替える

Foundry側ではエージェントバージョン間の段階的なトラフィック分割ができません。段階移行が必要な場合は、アプリケーション設定、機能フラグ、API Managementなど、Foundryの外側で新旧を切り替えます。

2026年8月20日の直前に作業を始めるのではなく、旧環境へ戻せる期間を確保したうえで、再デプロイ、RBAC設定、テスト、本番切り替えまで完了させてください。(Microsoft Learn)

Azure
Microsoft Foundry Azure Developer CLI Foundry Agent Service Hosted Agent

この記事を書いた人

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

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

関連記事

コメント

コメントする

目次