Azure AI Foundry（現在の公式名称では Microsoft Foundry）の「Microsoft Foundry Quickstart」を確認するうえで最も重要なのは、単なるチュートリアル更新ではなく、モデル呼び出し・エージェント作成・複数ターン会話を、Foundry projects と Azure AI Projects 2.x／Responses API 前提で始める流れに整理されている点です。
特に管理者や開発者は、既存の Azure AI Projects 1.x、Foundry classic、Assistants API、古いエンドポイント設計をそのまま使い続けていないかを確認する必要があります。新規開発なら Microsoft Foundry Quickstart の流れに沿って始めるのが安全ですが、既存環境がある場合は SDK、認証、RBAC、プロジェクトエンドポイント、モデルデプロイ、エージェントの会話履歴管理まで見直すべきです。
Microsoft Foundry Quickstartは何を始めるための記事か
Microsoft Foundry Quickstart は、Azure AI Foundry／Microsoft Foundry で「モデルを呼び出す」「エージェントを作成する」「エージェントと複数ターンで会話する」までを一通り試すための公式クイックスタートです。対象は Python、C#、TypeScript、Java、REST API、Foundry portal で、コードから使う場合はプロジェクトエンドポイントと認証設定が前提になります。(Microsoft Learn)
このクイックスタートは、単に「AIモデルにプロンプトを投げる」だけの記事ではありません。実務で見るべきポイントは、モデル呼び出しがエージェント機能と同じ Foundry プロジェクトの文脈で扱われることです。つまり、将来的に社内ナレッジ検索、ツール実行、会話履歴、ガバナンス、監視へ広げる前提で、最初のコードを組む位置づけになります。
Microsoft の公式ドキュメントでは、Azure AI Studio／Azure AI Foundry から Microsoft Foundry へ名称と構成が進化し、従来の複数エンドポイントや複数SDK中心の構成から、Foundry resource、Foundry projects、azure-ai-projects 2.x、/openai/v1/ 系の安定ルートへ整理されていることが示されています。(Microsoft Learn)
変更点の要点
Microsoft Foundry Quickstart を読むときは、次の変更を押さえると全体像をつかみやすくなります。
| 観点 | これまでの理解で起きやすい混乱 | 現在の確認ポイント |
|---|---|---|
| サービス名 | Azure AI Foundry、Azure AI Studio、Microsoft Foundry が混在する | 現在の公式ドキュメントでは Microsoft Foundry として整理されている |
| ポータル | classic と新しい Foundry portal の画面差で迷う | New Foundry の体験を前提に確認する |
| SDK | Azure AI Projects 1.x や旧SDKのまま試す | Azure AI Projects 2.x 前提で実装する |
| API | Assistants API の Threads／Runs 前提で考える | Responses API、Conversations、Agent Versions の考え方に寄せる |
| エンドポイント | Azure OpenAI リソース単位の呼び出しだけで考える | Foundry project endpoint を環境変数として扱う |
| 権限 | Owner／Contributor があれば十分と考える | データプレーン操作には Foundry User などのロールを確認する |
特に大きいのは、Azure AI Projects 2.x と 1.x に互換性がない点です。Quickstart では azure-ai-projects>=2.0.0 の利用が案内され、コードは Azure AI Projects 2.x 前提であることが明記されています。(Microsoft Learn)
影響を受けやすい対象者
新しくAzure AI FoundryでAIアプリを作る開発者
これから Azure AI Foundry でアプリやエージェントを作る場合は、Microsoft Foundry Quickstart の流れに沿って始めるのが最短です。最初にモデルをデプロイし、プロジェクトエンドポイントを取得し、DefaultAzureCredential などで認証して、モデル応答とエージェント会話を確認します。
ただし、サンプルコードをそのまま本番に近い環境へ持ち込むのは避けてください。Quickstart の目的は動作確認です。実務では、エンドポイントやエージェント名を環境変数で管理し、モデル名、デプロイ名、リージョン、RBAC、ログ出力を明示的に管理する必要があります。
既存のAzure AI Projects 1.xを使っている開発チーム
既存コードが Azure AI Projects 1.x を使っている場合、2.x への単純な上書きアップデートで動くとは考えないほうが安全です。Quickstart 側では 2.x と 1.x の非互換が示されているため、検証用ブランチを作り、クライアント生成、エンドポイント、エージェント作成、会話処理を個別に確認する必要があります。(Microsoft Learn)
特に、古いコードで「Assistants」「Threads」「Runs」という概念に依存している場合は、Responses API や Conversations を使う設計へ移行するかを検討してください。Microsoft の移行ガイドでは、azure-ai-inference の廃止予定や Assistants API の終了予定にも触れられているため、既存資産の棚卸しは早めに行うべきです。(Microsoft Learn)
管理者・プラットフォーム担当者
管理者が確認すべき中心は、SDKではなく 権限、プロジェクト、デプロイ、運用設計 です。Microsoft Foundry では、ユーザーやサービスプリンシパルが Azure Resource Manager の管理操作を行う権限と、Foundry のデータプレーンでモデルやエージェントを扱う権限を分けて考える必要があります。Owner や Contributor は広い管理権限を持ちますが、エージェント作成や対話などのデータプレーン操作には Foundry User、Foundry Project Manager、Foundry Owner などのロール確認が必要です。(Microsoft Learn)
開発前に確認すべき設定
Quickstart を試す前に、次の項目を確認しておくと、認証エラーやモデル未検出で詰まりにくくなります。
| 確認項目 | 確認内容 | 失敗しやすいポイント |
|---|---|---|
| Foundry project | 対象プロジェクトが作成済みか | classic 側のプロジェクトを見ている |
| モデルデプロイ | 使用するモデルがプロジェクトで利用可能か | モデル名とデプロイ名を混同する |
| プロジェクトエンドポイント | https://.../api/projects/... 形式の値を取得しているか | Azure OpenAI の旧エンドポイントを使う |
| SDKバージョン | azure-ai-projects>=2.0.0 など、Quickstart の前提に合っているか | 1.x と 2.x を同じ仮想環境で混在させる |
| 認証 | az login、DefaultAzureCredential、REST用トークンを確認したか | 別テナントのアカウントでログインしている |
| RBAC | Foundry User などのデータプレーン権限があるか | Owner／Contributor だけで十分と判断する |
| エージェント名 | AGENT_NAME を環境ごとに管理しているか | 同名エージェントを検証環境と本番環境で混同する |
Quickstart の前段にあるリソース作成手順では、Foundry project の作成、モデルデプロイ、プロジェクトエンドポイントの取得、チームメンバーへの Foundry User ロール付与が案内されています。管理者は、開発者にエンドポイントとデプロイ名を渡すだけでなく、プロジェクトスコープで適切なロールが割り当てられているかまで確認する必要があります。(Microsoft Learn)
SDKとREST APIで注意すべきポイント
Pythonでは仮想環境を分けて検証する
Python で試す場合は、グローバル環境に SDK を入れず、プロジェクトごとに仮想環境を作るのが安全です。Microsoft Learn の開発環境準備でも、Python パッケージは仮想環境または conda 環境で扱うことが推奨されています。(Microsoft Learn)
python -m venv .venv
source .venv/bin/activate
pip install "azure-ai-projects>=2.0.0"
az login既存プロジェクトで azure-ai-projects 1.x を使っている場合は、同じ環境で上書きせず、新しい仮想環境で Quickstart を再現してください。依存関係が多いプロジェクトでは、SDK更新よりも先に「最小コードでモデル応答が返るか」を確認したほうが切り分けしやすくなります。
REST APIではトークンの有効期限を前提にする
REST API で試す場合は、az account get-access-token --scope https://ai.azure.com/.default で一時的なアクセストークンを取得し、AZURE_AI_AUTH_TOKEN として扱う流れが示されています。このトークンは 60〜90分で期限切れになるため、長時間の検証やCI/CDで固定値として使うのは避けるべきです。(Microsoft Learn)
実務では、手元検証は az login、アプリケーション実行はマネージドIDやサービスプリンシパル、CI/CDは短命な認証情報を使う構成に分けると安全です。トークンを .env に保存する場合でも、リポジトリにコミットしないよう .gitignore とシークレットスキャンを必ず設定してください。
移行時に見落としやすいポイント
Azure AI Projects 1.xから2.xへの移行は「パッケージ更新」だけではない
Azure AI Projects 2.x は、Foundry projects の新しいAPIを使う前提です。1.x 向けに書いたコードをそのまま 2.x に置き換えると、クライアント初期化、エージェント作成、会話履歴、レスポンス取得の部分で差分が出る可能性があります。
移行時は、次の順番で進めると失敗を減らせます。
| 手順 | 作業内容 | 判断基準 |
|---|---|---|
| 棚卸し | 利用中のSDK、API、エンドポイント、モデル名を一覧化する | 旧SDKや classic 固有の記述が分かる |
| 最小検証 | Quickstart のモデル応答だけを新環境で再現する | 認証・エンドポイント・モデルデプロイが通る |
| エージェント検証 | エージェント作成と複数ターン会話を試す | 会話履歴とエージェント参照が期待通り動く |
| 権限確認 | 開発者、実行ID、管理者のロールを分けて確認する | 最小権限で動作する |
| 本番設計 | ログ、監視、コスト、DR、リージョンを設計する | PoCコードをそのまま本番化しない |
Assistants APIや旧パッケージの利用状況を確認する
既存アプリが Assistants API や azure-ai-inference に依存している場合は、早めに移行計画を作るべきです。Microsoft の移行ガイドでは、azure-ai-inference パッケージの廃止予定日や Assistants API の終了予定日が示され、Responses API と新しい Foundry Agents service への移行が案内されています。(Microsoft Learn)
ここで重要なのは、期限だけを見て慌てて書き換えないことです。エージェント機能は、会話履歴、ツール呼び出し、ファイル検索、社内システム連携、権限管理と結びつきます。まずは「どの機能が Assistants API 固有なのか」「どの部分が単なるモデル呼び出しなのか」を分けてから移行してください。
管理者が確認すべきRBACとガバナンス
Microsoft Foundry では、RBACロール名の変更も見落としやすいポイントです。Foundry User、Foundry Owner、Foundry Account Owner、Foundry Project Manager は、以前 Azure AI User、Azure AI Owner、Azure AI Account Owner、Azure AI Project Manager と呼ばれていたロールで、ロールIDと主要な権限は変更されていないと説明されています。(Microsoft Learn)
ただし、名称変更のロールアウト中は、画面やスクリプト上で古い名前が表示される可能性があります。自動化スクリプトではロール名ではなくロール定義IDを使うと、名称差分による失敗を避けやすくなります。
管理者は、最低限次の観点を確認してください。
| 管理項目 | 確認すること |
|---|---|
| 開発者アクセス | プロジェクト単位で Foundry User 以上が必要か |
| 実行ID | アプリやCI/CDのサービスプリンシパルに必要最小限の権限があるか |
| チーム管理 | 個別ユーザーではなく Microsoft Entra セキュリティグループで管理できるか |
| 権限の分離 | リソース作成者、モデル利用者、エージェント運用者を分けているか |
| 監査 | 誰がモデル、エージェント、接続、ロールを変更できるか確認しているか |
よくある失敗は、「Azure の Contributor を付けたから動くはず」と判断することです。Azure リソースの管理権限と、Foundry のデータプレーンでエージェントを操作する権限は同じではありません。エージェントの作成、推論、対話が失敗する場合は、最初にプロジェクトスコープの Foundry ロールを確認してください。
デプロイ・運用で注意すべきこと
Quickstart の成功は、あくまで「動作確認ができた」という段階です。本番や社内展開では、可用性、監視、コスト、セキュリティ、依存サービスの管理まで設計する必要があります。
Microsoft の高可用性・回復性に関するドキュメントでは、Foundry 自体は自動フェールオーバーやディザスターリカバリーを提供しないこと、Standard agent deployment mode で使う Cosmos DB、Azure AI Search、Azure Storage などの状態を持つ依存サービスの耐久性は利用者側の責任になることが示されています。(Microsoft Learn)
そのため、次のような判断が必要です。
| 利用シーン | 推奨される確認 |
|---|---|
| 個人検証・PoC | リソースグループ単位で削除できる構成にする |
| 部門内アプリ | Entra グループでアクセスを管理し、ログ出力を有効にする |
| 社内業務アプリ | モデルデプロイ、エージェント、接続先API、監視を環境別に分離する |
| 本番利用 | リージョン、可用性ゾーン、バックアップ、フェールオーバー手順を設計する |
| 外部サービス連携 | Key Vault、Managed Identity、接続先の権限を個別に確認する |
特に、エージェントが社内データや外部APIにアクセスする場合は、モデルだけでなく接続先の権限とログも設計対象になります。ストレージ、検索、Key Vault、データベース、API Management などを使う場合は、それぞれのデータプレーン権限を確認してください。
よくあるエラーと対処法
認証は通るのにモデル呼び出しが失敗する
az login が成功していても、対象テナントやサブスクリプションが違うと、Foundry project にアクセスできません。まず az account show でサブスクリプションを確認し、Foundry portal で同じプロジェクトを開けるか確認してください。
また、プロジェクトエンドポイントではなく、別の Azure OpenAI エンドポイントを使っているケースもあります。Quickstart では project endpoint を使うため、環境変数に入れている値を見直してください。
SDKを入れたのにサンプルコードが動かない
最初に確認すべきは SDK のメジャーバージョンです。azure-ai-projects 1.x が残っている環境では、Quickstart の 2.x 前提コードが動かない可能性があります。
pip show azure-ai-projects
pip install --upgrade "azure-ai-projects>=2.0.0"ただし、既存アプリでは不用意なアップグレードが他の依存関係に影響することがあります。新しい仮想環境でQuickstartを再現し、動作を確認してから既存コードへ反映してください。
エージェント作成や会話だけ失敗する
モデル呼び出しは成功するのに、エージェント作成や会話だけ失敗する場合は、RBACとエージェント名を確認してください。データプレーン権限が不足している、エージェント名が違う、作成したエージェントのバージョンを参照していない、といった原因がよくあります。
REST API の場合は、アクセストークンの期限切れも多い原因です。検証が長引いたらトークンを再取得してください。
これから取るべき行動
Azure AI Foundry をこれから使うチームは、まず Microsoft Foundry Quickstart で「モデル応答」「エージェント作成」「複数ターン会話」を最小構成で再現してください。その後、SDKバージョン、プロジェクトエンドポイント、モデルデプロイ名、Foundry RBAC、実行ID、ログ設計をチェックリスト化します。
既存システムがあるチームは、Azure AI Projects 1.x、Assistants API、azure-ai-inference、classic portal 前提の運用が残っていないかを棚卸しすることが先です。Quickstart のコードを丸写しするのではなく、現在の公式構成に合わせて「どのAPIに移すか」「どの権限で動かすか」「どの環境から段階展開するか」を決めてください。
最後に、Quickstart は入口であり、本番設計ではありません。モデルが応答した時点で完了とせず、RBAC、リージョン、監視、コスト、DR、シークレット管理まで確認してから、社内展開や本番導入へ進めることが重要です。
コメント