Azure AI Foundry で Assistants API や classic agents を使っている場合、今回の「Migrate to the new Foundry Agent Service」で最も重要なのは、Thread / Run / Assistant 前提の実装を、Conversation / Response / Agent Version 前提へ移行する必要があるという点です。単なる SDK の差し替えではなく、会話状態、実行管理、エージェント定義、権限、リージョン、運用監視まで見直す移行になります。
特に注意すべき期限は、Azure OpenAI Assistants API が 2026年8月26日 に廃止予定であること、Foundry Agent Service の classic agents が 2027年3月31日 に廃止予定であることです。Microsoft Learn では、Assistants API の移行先として一般提供済みの Microsoft Foundry Agents Service を使うよう案内されています。(Microsoft Learn)
Azure AI Foundry の「Migrate to the new Foundry Agent Service」とは何か
「Migrate to the new Foundry Agent Service」は、Azure AI Foundry で従来使われてきた Assistants API や classic agents から、新しい Foundry Agent Service へ移行するための Microsoft 公式ガイドです。
新しい Foundry Agent Service は、従来の Assistants API ではなく Responses API を土台にしたエージェント実行基盤です。Microsoft Learn では、新しい API により、SDK の近代化、エンタープライズ向け機能、ID・ガバナンス・可観測性の継承が提供されると説明されています。(Microsoft Learn)
今回の更新ポイントは、次の3つに集約できます。
| 変更前 | 変更後 | 実務上の意味 |
|---|---|---|
| Threads | Conversations | 会話履歴は「スレッド」ではなく、メッセージ・ツール呼び出し・ツール出力などを含む「アイテム」として管理する |
| Runs | Responses | 非同期 Run を作成してポーリングする実装から、responses.create() を中心にした応答生成へ変える |
| Assistants / classic agents | New agents / Agent versions | エージェント定義をバージョン管理し、create_agent() ではなく create_version() 系の API を使う |
この変更は、アプリケーションの表面だけを直す作業ではありません。チャット履歴、ツール呼び出し、状態管理、エージェント定義、SDK バージョン、リソースリージョンまで含めて棚卸しする必要があります。
影響を受ける環境
影響を受けるのは、主に次のような環境です。
| 利用状況 | 影響 | 優先度 |
|---|---|---|
| Azure OpenAI Assistants API を利用している | 2026年8月26日までに移行が必要 | 高 |
| Foundry classic agents を利用している | 2027年3月31日までに移行が必要 | 高 |
threads / messages / runs を前提にしたコードがある | API 設計の変更が必要 | 高 |
create_agent() を使っている | create_version() 系への置き換えが必要 | 高 |
azure-ai-projects 1.x のサンプルを使っている | 2.x SDK への見直しが必要 | 中〜高 |
| Azure Functions ツールを classic agents で使っている | 新 Foundry Agent Service では同等の扱いにならないため代替設計が必要 | 高 |
| Foundry リソースが Responses API 非対応リージョンにある | 新ポータルでエージェントを作成・実行できない可能性がある | 高 |
Microsoft Learn では、Responses API と Foundry Agent Service はすべての Azure リージョンで利用できるわけではなく、サポートされていないリージョンでは現在の Foundry ポータルでエージェントを作成または実行できないと説明されています。移行前にリージョン対応を確認することが重要です。(Microsoft Learn)
まず確認すべき移行期限
Azure AI Foundry の移行計画では、期限の違いを正しく分けて考える必要があります。
| 対象 | 期限 | 管理者が取るべき対応 |
|---|---|---|
azure-ai-inference パッケージ | 2026年5月30日 | openai パッケージへの移行状況を確認する |
| Azure OpenAI Assistants API | 2026年8月26日 | Foundry Agent Service または Responses API へ移行する |
| Foundry classic agents | 2027年3月31日 | 新しい Microsoft Foundry Agents Service へ移行する |
Microsoft のクラシックポータル移行ガイドでは、Assistants API は 2026年8月26日に sunset とされ、一般提供済みの Microsoft Foundry Agents Service を使うよう案内されています。また、azure-ai-inference パッケージの廃止日も 2026年5月30日として示されています。(Microsoft Learn)
ここで混同しやすいのは、Assistants API の期限と classic agents の期限が同じではないことです。Assistants API を直接使っているアプリは、2027年まで待てるとは考えない方が安全です。
API 設計の最大の変更は「Thread から Conversation」への移行
従来の Assistants API や classic agents では、会話状態は Thread と Message を中心に扱っていました。新しい Foundry Agent Service では、Thread ではなく Conversation を使います。
Microsoft Learn では、従来の Thread はサーバー側にメッセージを格納していた一方、新しい Conversation はメッセージだけでなく、ツール呼び出し、ツール出力、その他のデータを含むアイテムを格納できると説明されています。(Microsoft Learn)
実務で見直すべきポイント
移行時は、次の観点でコードを確認してください。
| 確認項目 | 旧実装でありがちな例 | 新実装での考え方 |
|---|---|---|
| 会話 ID | thread_id を DB に保存 | conversation_id を保存 |
| メッセージ追加 | messages.create(thread_id=...) | conversations.items.create(conversation_id=...) |
| 会話履歴 | Thread に紐づく Message 一覧を取得 | Conversation 内の item と Response 出力を扱う |
| ツール結果 | Run step や Message の一部として確認 | Response の output item と tool call を確認 |
| 監査ログ | Thread / Run ID をログに出す | Conversation ID / Response ID をログに出す |
単純に変数名を thread_id から conversation_id に変えるだけでは不十分です。新しい Conversation は「メッセージの入れ物」ではなく、エージェント実行に関係する複数種類の item を扱う構造です。ログ設計やデバッグ画面も合わせて見直す必要があります。
Run から Response へ：ポーリング前提の処理を見直す
従来の Runs は、Thread に対して非同期で処理を開始し、queued や in_progress の状態をポーリングして完了を待つ設計でした。新しい Foundry Agent Service では、responses.create() を中心に入力を渡し、出力 item を受け取る設計に変わります。Microsoft Learn でも、従来はポーリングを伴う非同期 Run だった一方、現在は OpenAI クライアントで responses.create() を呼び出す形になると説明されています。(Microsoft Learn)
移行で削れる処理と、残すべき処理
| 処理 | 移行後の扱い |
|---|---|
| Run 作成 | responses.create() へ置き換える |
| Run status のポーリング | 多くのケースで不要になる |
| Run step の確認 | Response の output item / tool call の確認へ変更 |
| タイムアウト制御 | アプリ側の HTTP タイムアウト、バックグラウンド処理、再試行設計として再定義 |
| 長時間処理 | background mode や durable stream の利用可否を検討 |
注意したいのは、「Run がなくなるから非同期処理が不要になる」と短絡しないことです。画像生成、外部ツール呼び出し、社内 API 連携など、処理時間が長くなる用途では、アプリケーション側のタイムアウト、ジョブ管理、再試行、ユーザー通知を再設計する必要があります。
エージェント定義は create_agent() から create_version() へ
classic agents では、create_agent() のようなメソッドでエージェントを作成する実装が使われていました。新しい Foundry Agent Service では、エージェント定義をバージョンとして作成する設計になります。
Microsoft Learn では、以前の SDK の client.agents.create_agent() を使っている場合は client.agents.create_version() に移行し、明示的な kind、model、instructions フィールドを含む構造化されたエージェント定義を使うと説明されています。(Microsoft Learn)
移行時の見直し例
| 見直す項目 | 旧設計 | 新設計での確認ポイント |
|---|---|---|
| エージェント名 | name を直接指定 | agent_name と version の管理ルールを決める |
| モデル | model="gpt-4.1" など | 対象リージョンで利用可能か確認する |
| 指示文 | instructions に直接指定 | バージョン管理し、変更履歴を残す |
| ツール | tools=[...] | 新サービスで利用可能なツールか確認する |
| デプロイ | アプリ内で agent ID を参照 | agent name / version をどう固定・更新するか決める |
本番運用では、エージェント定義を「コードの一部」として扱うか、「運用設定」として扱うかを決めておくことが重要です。たとえば、プロンプトやツール構成を頻繁に変更する場合は、Git 管理、レビュー、承認、ロールバック手順を用意しておくと事故を減らせます。
ツールの互換性は必ず確認する
新しい Foundry Agent Service では、利用できるツールが classic agents と完全には一致しません。
Microsoft Learn の比較では、Azure AI Search、Code Interpreter、File Search、Function、Bing Search grounding、OpenAPI などは classic と new の両方で利用可能とされています。一方で、Azure Functions は classic 側では GA ですが new 側では「No」となっており、Connected Agents は A2A tool 推奨、Deep Research は Web Search tool を使った Deep Research model 推奨とされています。(Microsoft Learn)
| ツール / 機能 | 新 Foundry Agent Service での扱い | 移行時の判断 |
|---|---|---|
| Azure AI Search | GA | RAG 系用途は比較的移行しやすい |
| File Search | GA | ファイル管理とインデックス移行を確認 |
| Code Interpreter | GA | 出力ファイルや実行時間の扱いを確認 |
| Function | GA | ツール呼び出しの入出力スキーマを確認 |
| MCP | GA | 外部ツール接続の標準化候補 |
| Web Search | GA | classic で未使用でも新規活用を検討可能 |
| Image Generation | Public Preview | 本番利用はプレビュー条件を確認 |
| Azure Functions | 新側では非対応 | Function tool や OpenAPI、MCP など代替設計を検討 |
| Connected Agents | 新側では非対応 | A2A tool への置き換えを検討 |
| Deep Research | 新側では非対応 | Deep Research model + Web Search tool を検討 |
既存のエージェントがどのツールを使っているかを最初に一覧化してください。特に Azure Functions、Connected Agents、Deep Research を classic 側で使っている場合、API の置き換えだけでは移行できない可能性があります。
SDK とクライアントの設定変更
移行では SDK のバージョン合わせが重要です。Microsoft Learn では、Python では azure-ai-projects>=2.0.0、JavaScript では @azure/[email protected]、Java では azure-ai-agents 2.0.0 などが例示されています。(Microsoft Learn)
また、新しい API では、エージェントの作成とバージョン管理には project client を使い、会話と応答には OpenAI クライアントまたは言語ごとの同等クライアントを使います。Microsoft Learn では、Python では project.get_openai_client()、JavaScript では projectClient.getOpenAIClient()、C# では agent 向けの Project Responses Client を使う形が案内されています。(Microsoft Learn)
SDK 移行のチェック表
| 項目 | 確認内容 |
|---|---|
| SDK バージョン | azure-ai-projects 1.x と 2.x を混在させていないか |
| クライアント | Conversation / Response を project client で直接呼んでいないか |
| 認証 | DefaultAzureCredential や Azure CLI ログインが使えるか |
| エンドポイント | project endpoint 形式になっているか |
| API バージョン | 古い月次 api-version 前提の実装が残っていないか |
| CI/CD | ビルド環境に新しい SDK が入っているか |
| サンプルコード | classic 向けサンプルを new 向け環境で使っていないか |
クラシックポータル移行ガイドでも、2.x SDK サンプルを 1.x セットアップで使う、またはその逆を行うとエラーになると警告されています。(Microsoft Learn)
移行ツールでできること、できないこと
Microsoft は、Assistants API から Agents への移行を支援する migration tool を用意しています。公式ガイドでは、このツールがエージェント定義、スレッド作成、メッセージ作成、実行作成などのコード構造の移行を支援する一方、過去の実行、スレッド、メッセージなどの状態データは移行しないと説明されています。(Microsoft Learn)
GitHub 上の移行ツール README では、Docker Desktop と Azure CLI を使った実行方法、--list による読み取り専用の事前確認、特定 item だけの移行、ツール付き assistant のみの移行、クロスプロジェクト移行などが案内されています。(AKA.ms)
移行ツール利用時の現実的な進め方
| フェーズ | 実施内容 | 失敗しやすい点 |
|---|---|---|
| 棚卸し | --list で移行対象を確認 | 表示されない item を「影響なし」と誤判断する |
| 権限確認 | Foundry User など必要ロールを確認 | 401 / 403 を SDK エラーと誤解する |
| テスト移行 | 開発用プロジェクトへ移行 | 本番 project に直接実行して差分管理できなくなる |
| コード確認 | 生成・変更されたコードをレビュー | 状態データまで移行されたと勘違いする |
| 動作検証 | Conversation / Response / tool call をテスト | 旧 Thread の履歴が使える前提でテストしてしまう |
| 本番移行 | リリース手順とロールバック手順を用意 | 旧 API と新 API のログが追えなくなる |
移行ツールは便利ですが、完全自動移行の仕組みではありません。特に、会話履歴をどこまで保持するか、既存ユーザーのセッションをどう切り替えるか、ログや監査証跡をどう残すかは、アプリケーション側で設計が必要です。
管理者が確認すべきポイント
移行は開発チームだけで完結しません。Azure 管理者、セキュリティ管理者、運用担当者も次の項目を確認してください。
| 確認項目 | なぜ重要か | 具体的な確認内容 |
|---|---|---|
| リージョン | Responses API 非対応リージョンでは新エージェントが動かない可能性がある | 対象 Foundry リソースのリージョンとサポート状況 |
| RBAC | 新 Foundry ではロール名・管理場所が変わる | Foundry User、Foundry Project Manager、Foundry Owner など |
| エンドポイント | 旧 Azure OpenAI endpoint から project endpoint へ変わる | 環境変数、Key Vault、アプリ設定 |
| 認証方式 | API キー依存から Entra ID 認証へ寄せるケースがある | DefaultAzureCredential、Managed Identity、条件付きアクセス |
| ネットワーク | 社内制限や private endpoint 利用時に影響が出る | DNS、Firewall、Private Link、送信許可 |
| クォータ | モデル・リージョン・ツール利用で制限が異なる | Operate > Quota の確認 |
| 監視 | Thread / Run 前提のログが使えなくなる | Conversation ID、Response ID、tool call の記録 |
| データ保持 | 移行ツールは過去状態データを移行しない | 旧履歴の参照期間、削除方針、監査要件 |
| ツール権限 | Web Search や MCP など外部接続の扱いが変わる | 外部通信、データ持ち出し、承認フロー |
Microsoft Learn では、現在の Foundry ポータルでは「ホーム」「発見」「ビルド」「動作」「ドキュメント」のようにナビゲーションが再構成され、クォータ管理、ユーザーとアクセス許可、トレースなどの場所も classic から変わっています。(Microsoft Learn)
よくある移行トラブルと対処法
| 症状 | 主な原因 | 対処 |
|---|---|---|
AIProjectClient に conversations がない | project client で Conversation API を呼んでいる | project.get_openai_client() などで OpenAI クライアントを取得する |
getOpenAIClient is not a function | @azure/ai-projects が古い | @azure/[email protected] 以降へ更新 |
create_agent() が使えない | SDK v2.0.0 で削除済み | create_version() 系に置き換える |
| 古い Thread の履歴が見えない | 移行ツールは状態データを移行しない | 新しい Conversation を開始し、必要なら旧履歴参照を別設計にする |
responses.create() でモデルエラー | モデル名またはリージョン非対応 | Foundry project のモデル名とリージョン対応を確認 |
| 404 / MethodNotAllowed | Assistants API 呼び出しを Responses API エンドポイントへ送っている | API パスとクライアントを Responses API 前提に修正 |
| 新ポータルに project がない | hub-based project が現在のポータルに表示されない | classic portal に戻るか、Foundry project へ移行する |
公式ガイドでも、AIProjectClient で conversations.create() を呼んだ場合のエラー、古い SDK、create_agent() の削除、旧 Thread データが移行されない点などがトラブルシューティングとして示されています。(Microsoft Learn)
移行を進める実務手順
Azure AI Foundry の移行は、次の順序で進めると手戻りを減らせます。
| 手順 | 作業 | 成果物 |
| -: | ——————————————- | —————————————— |
| 1 | Assistants API / classic agents の利用箇所を棚卸しする | 対象アプリ、対象 API、利用ツール一覧 |
| 2 | 期限を分類する | 2026年8月26日対応分、2027年3月31日対応分 |
| 3 | リージョンとモデル対応を確認する | 移行可否、必要な新リソース |
| 4 | SDK と依存パッケージを更新する | azure-ai-projects 2.x、OpenAI クライアント構成 |
| 5 | Thread / Run / Assistant の設計を置き換える | Conversation / Response / Agent Version 設計 |
| 6 | ツール互換性を確認する | 継続利用、代替設計、廃止対象 |
| 7 | 移行ツールを --list で試す | 移行対象リスト、権限確認 |
| 8 | 開発環境で新エージェントを作成する | agent version、conversation、response の動作確認 |
| 9 | 監視・ログ・権限・ネットワークを検証する | 運用チェックリスト |
| 10 | 段階的に本番切り替えする | リリース手順、ロールバック手順 |
最初から本番コードを一括置換するのではなく、まずは代表的なエージェントを1つ選び、Conversation と Response の新しい流れを小さく検証するのがおすすめです。その後、ツール付きエージェント、長時間実行、外部 API 連携、監査ログが必要なユースケースへ広げると、移行リスクを抑えられます。
新しい Foundry Agent Service へ移行するメリット
今回の移行は廃止対応だけではありません。新しい Foundry Agent Service には、今後のエージェント開発を見据えたメリットがあります。
Microsoft Learn では、新しいエージェントの利点として、より多くの Foundry モデル、Web Search、File Search、Code Interpreter、MCP tool calling、画像生成、reasoning summaries、background mode、シングルテナントストレージ、権限制御、エージェントのエンドポイント公開などが挙げられています。(Microsoft Learn)
特に企業利用では、次の観点が重要です。
| 観点 | メリット |
|---|---|
| 開発 | Responses API ベースになり、今後の新機能を取り込みやすい |
| 運用 | Conversation / Response 単位で実行結果を追いやすい |
| ガバナンス | エージェント定義の実行・変更権限を制御しやすい |
| 拡張性 | MCP、Web Search、A2A など新しい連携パターンを検討できる |
| 本番化 | Hosted agents や deployable agents を使った運用設計に進みやすい |
つまり、移行を「仕方なくやる廃止対応」と捉えるより、エージェント基盤を本番運用向けに作り直す機会として扱う方が効果的です。
まとめ：最初にやるべきこと
Azure AI Foundry の「Migrate to the new Foundry Agent Service」で最初にやるべきことは、自社環境が Assistants API の期限に該当するのか、classic agents の期限に該当するのかを切り分けることです。
Assistants API を使っている場合は、2026年8月26日までの移行が必要です。classic agents を使っている場合も、2027年3月31日の廃止を見据えて、新しい Foundry Agent Service への移行計画を始めるべきです。
次に、コード内の threads、messages、runs、create_agent()、旧 SDK、旧 endpoint を検索し、Conversation、Response、Agent Version、project endpoint、OpenAI クライアントへ置き換える範囲を確認してください。あわせて、リージョン、RBAC、ツール互換性、ログ、データ保持を管理者と一緒に確認することが重要です。
移行の成否は、API の置き換えだけでなく、運用設計まで見直せるかで決まります。まずは移行対象の棚卸しと期限分類から始め、開発環境で新しい Conversation / Response の流れを検証するところから進めましょう。
コメント