Azure AI Foundryの開発環境準備でまず押さえるべき結論は、SDKを入れる前に、実行環境・Azure CLI認証・RBAC・VS Code拡張・Gitをそろえることです。2026年5月19日時点で公式情報を確認するなら、「Prepare your development environment」は単なるインストール手順ではなく、Microsoft Foundry開発を始める前の共通チェックリストとして読むべき内容です。
特に注意したいのは、Azure AI Foundryが現在のドキュメント上ではMicrosoft Foundryとして扱われている点、RBACロール名が変更されている点、そしてSDKやポータルの新旧バージョンを混在させると認証エラーやエンドポイント不一致が起きやすい点です。この記事では、管理者・開発者・CI/CD担当者が確認すべき設定と、移行・展開時に失敗しやすいポイントを実務目線で整理します。
Azure AI Foundryの「Prepare your development environment」は何をする手順か
「Prepare your development environment – Microsoft Foundry」は、Microsoft Foundry SDKを使うための開発環境を整える公式手順です。対象は、ローカルPCや開発用VMでAzure AI Foundry、現在の名称ではMicrosoft Foundryを使ってモデル・エージェント・AIアプリを開発する人です。
公式手順では、言語ランタイム、Azure CLI、Azure Developer CLI、Foundry VS Code拡張機能、Gitをインストールします。また、コードからAzureサービスにアクセスできるように、Azure CLIによる認証も前提になります。ただし、このページは共通前提条件の準備に絞られており、SDKパッケージのインストールやシナリオ別の認証実装はクイックスタート側で扱う位置付けです。(Microsoft Learn)
つまり、この記事で確認すべきポイントは「どのSDKをどう書くか」より前段階です。次のような状態になっていれば、開発開始前の準備としてはかなり安全です。
| 確認項目 | 目的 | 実務での判断基準 |
|---|---|---|
| Azureアカウントとサブスクリプション | Foundryリソースやプロジェクトを利用する | 対象サブスクリプションでaz account showが通る |
| RBACロール | Foundryリソース・プロジェクトへのアクセス制御 | 開発者は原則Foundry User、管理者は役割に応じてProject Manager以上 |
| 言語ランタイム | SDKサンプルやアプリを実行する | チームでPython、.NET、JavaScript、Javaのどれを使うか決める |
| Azure CLI | ローカル認証とサブスクリプション確認 | az login、az account showが成功する |
| Azure Developer CLI | テンプレートやデプロイを効率化する | azdを使うテンプレートを採用する場合に必須 |
| VS CodeとFoundry拡張 | モデル・エージェント開発をIDEから行う | VS Code上でFoundryの操作を行うチームは導入する |
| Git | サンプルコードやテンプレートを取得する | git cloneできる状態にする |
名称変更を前提に読む：Azure AI FoundryからMicrosoft Foundryへ
日本語圏では「Azure AI Foundry」で検索されることが多いですが、2026年時点の公式ドキュメントでは、Azure AI Studio / Azure AI FoundryからMicrosoft Foundryへと名称・構成が整理されています。Microsoft Learnでは、現在のブランドはMicrosoft Foundry、ポータルはFoundry、リソースモデルは単一のFoundry resourceとprojectsを中心に説明されています。(Microsoft Learn)
移行や運用で重要なのは、名称が変わってもAzure上のリソース種別まで単純に別物になったわけではないことです。公式の移行ガイドでは、Azure AI Studio → Azure AI Foundry → Microsoft Foundryという進化に触れつつ、AzureリソースタイプはMicrosoft.CognitiveServices/accountsのままと説明されています。(Microsoft Learn)
このため、管理者は次のように整理すると混乱を防げます。
| 以前の呼び方・構成 | 現在の考え方 | 確認ポイント |
|---|---|---|
| Azure AI Foundry | Microsoft Foundry | ドキュメント検索では両方の名称が出る可能性がある |
| Azure AI Services | Foundry Tools | Speech、Vision、Languageなどの位置付けを確認する |
| Foundry classic portal | Foundry portal | 新旧ポータルで表示されるプロジェクトや機能が異なる |
| 複数SDK・複数エンドポイント中心 | Project clientとOpenAI互換エンドポイント中心 | サンプルコードのSDKバージョンを確認する |
| Assistants API | Responses API / Agents v2 | 旧APIを使うエージェントは移行計画が必要 |
今回の変更点で実務に影響しやすいポイント
今回の公式情報を「開発環境の準備」として見るだけでは不十分です。実務上の影響は、ローカル環境だけでなく、権限設計、SDKバージョン、認証方式、ポータル移行、CI/CDにも広がります。
RBACロール名が変わっている
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)
この変更は、手動操作よりもIaC、運用スクリプト、社内手順書に影響します。ロール名で条件分岐しているスクリプトや、古い名称で手順書を書いている場合、担当者が「該当ロールがない」と判断してしまう可能性があります。
管理者がスクリプト化する場合は、移行期間中の名称揺れを避けるため、公式が示すロール定義IDを使う方が安全です。
| ロール | 主な用途 | ロール定義ID |
|---|---|---|
| Foundry User | 開発者の最小権限 | 53ca6127-db72-4b80-b1b0-d745d6d5456d |
| Foundry Project Manager | プロジェクト管理と開発 | eadc314b-1a2d-4efa-be10-5d325db5065e |
| Foundry Account Owner | リソースやプロジェクト管理 | e47c6f54-e4a2-4754-9501-8e0985b135e1 |
| Foundry Owner | 広範な管理・開発権限 | c883944f-8b7b-4483-af10-35834be79c4a |
「Ownerを付ければ解決」は避ける
開発が進まないときにサブスクリプションOwnerを付けて解決したくなりますが、本番運用では過剰権限になりやすいです。公式ドキュメントでは、Foundryリソースを作成・管理するにはFoundry Project ManagerやOwnerなどが必要で、既存プロジェクトを使うだけならFoundry Userが最小権限の開発ロールとして説明されています。(Microsoft Learn)
実務では、次のように割り当てると管理しやすくなります。
| 役割 | 推奨される権限設計 |
|---|---|
| 一般開発者 | Foundry Userをプロジェクトスコープに付与 |
| リード開発者 | Foundry Project Managerをリソースまたは必要範囲に付与 |
| プラットフォーム管理者 | Foundry Account Ownerまたは必要に応じてOwner |
| CI/CD実行主体 | サービスプリンシパル、マネージドID、フェデレーションIDに必要最小限のロールを付与 |
| 監査・閲覧担当 | Readerなど、操作権限を持たないロールを検討 |
なお、Cognitive Services系のロールやAzure AI DeveloperロールをFoundryプロジェクト用の代替として使うのは避けるべきです。公式ドキュメントでは、Cognitive Servicesで始まる組み込みロールはAI Servicesリソースへの直接アクセス向けであり、Foundryシナリオには適用されないと注意されています。(Microsoft Learn)
APIキーよりMicrosoft Entra ID認証を基本にする
RBACの効果を生かすには、Microsoft Entra IDによる認証を前提に設計する必要があります。公式のRBAC解説では、RBACロールはEntra ID認証時に適用され、キー認証を使うとロール制限なしのフルアクセスになるため、セキュリティと細かなアクセス制御の観点からEntra ID認証が推奨されています。(Microsoft Learn)
開発者のローカル環境では、az login後にDefaultAzureCredentialで認証する流れが自然です。一方、CI/CDや自動化ではブラウザログインに依存できません。Azure CLI公式情報では、スクリプトではサービスプリンシパル、Azureリソース上の処理ではマネージドIDを使う方式が説明されています。また、Microsoft Entra IDユーザーIDによる自動化はMFA要件の影響を受けるため、ワークロードIDへの移行が必要になるケースがあります。(Microsoft Learn)
開発者が準備すべきローカル環境
公式手順では、Python、Java、JavaScript、.NETの開発環境が扱われています。全員がすべてを入れる必要はありません。チームで採用する言語と、利用するサンプル・テンプレートに合わせて準備します。
Pythonは仮想環境を必ず使う
Pythonで開発する場合、グローバル環境に直接パッケージを入れないことが重要です。公式手順でも、Pythonパッケージはグローバルインストールではなく、仮想環境またはconda環境を使うよう案内されています。Pythonは3.10以降が推奨され、少なくとも3.9以上が必要とされています。(Microsoft Learn)
Windowsでは次のように準備できます。
py -3 -m venv .venv
.venv\Scripts\activate
python --version
pip --versionmacOSまたはLinuxでは次のようにします。
python3 -m venv .venv
source .venv/bin/activate
python --version
pip --versionよくある失敗は、VS Codeで開いているPythonインタープリターと、ターミナルで有効化した仮想環境が違うことです。パッケージを入れたのにModuleNotFoundErrorが出る場合は、VS Code右下のPython環境選択と、ターミナルの.venv有効化状態を確認してください。
Java、Node.js、.NETはサンプルの前提に合わせる
公式手順では、JavaはJDK 17以降、JavaScript/TypeScriptではNode.js 20以降が推奨されています。.NETでは、最新のLTSまたはプロジェクトで必要なバージョンの.NET SDKを入れ、dotnet --versionで確認します。(Microsoft Learn)
実務では、開発者ごとにバージョンがばらつくと、同じサンプルでも動作が変わります。チーム内で次のような標準を決めておくと、オンボーディングが楽になります。
| 言語 | 推奨する管理方法 | チェックコマンド |
|---|---|---|
| Python | .venvをリポジトリ直下に作る | python --version |
| Java | JDKのLTS系を統一する | java --version |
| JavaScript/TypeScript | Node.jsのメジャーバージョンを統一する | node --version |
| .NET | SDKバージョンをプロジェクトで明示する | dotnet --version |
Azure CLIでログイン状態とサブスクリプションを確認する
Azure AI Foundry開発では、Azure CLIの認証状態がそのままSDK実行時の認証に影響します。公式クイックスタートでも、各言語のスクリプトを実行する前にaz loginで認証し、プロジェクトエンドポイントを環境変数として保存する流れが示されています。(Microsoft Learn)
開発開始前に、最低限次のコマンドを確認してください。
az version
az login
az account show複数サブスクリプションを持っている場合は、意図したサブスクリプションを明示します。
az account set --subscription "<subscription ID or name>"
az account showブラウザ認証がうまくいかない場合は、デバイスコード認証を使います。
az login --use-device-code公式のトラブルシューティングでも、インストール後にコマンドが見つからない場合はターミナルやVS Codeの再起動、az loginがブラウザエラーになる場合はaz login --use-device-codeの利用が案内されています。(Microsoft Learn)
SDK、エンドポイント、ポータルの新旧を混在させない
Azure AI FoundryからMicrosoft Foundryへの移行で最も事故が起きやすいのは、SDK、エンドポイント、ポータルの組み合わせです。
Microsoft Foundry SDKs and Endpointsの公式情報では、Foundryリソースはモデル、エージェント、ツールへの統一アクセスを提供し、Foundry SDK、OpenAI SDK、Anthropic SDK、Foundry Tools SDKs、Agent Frameworkを用途別に使い分ける考え方が示されています。Foundry SDKはFoundry固有機能、OpenAI SDKはOpenAI互換性や埋め込みなど、Anthropic SDKはFoundry上のClaudeモデル向けという位置付けです。(Microsoft Learn)
| やりたいこと | 使うもの | 注意点 |
|---|---|---|
| エージェント、評価、トレーシングなどFoundry固有機能を使う | Foundry SDK | Project endpointを使う |
| OpenAI互換のAPIサーフェスを重視する | OpenAI SDK | /openai/v1エンドポイントを使う |
| 埋め込みを使う | OpenAI SDK | Project endpointではなくOpenAI互換エンドポイント側を確認する |
| Claudeモデルを使う | Anthropic SDK | /anthropic系エンドポイントを使う |
| Speech、Vision、Languageなど個別AIサービスを使う | Foundry Tools SDKs | サービスごとにエンドポイントが異なる |
特に、Foundry SDKの2.x系は新しいFoundryポータル向け、1.x系はclassic側の文脈で使われるため、サンプルコードと環境がずれるとエラーの原因になります。公式クイックスタートでも、Azure AI Projects 2.xのコードは1.xと互換性がないと明記されています。(Microsoft Learn)
移行・展開で管理者が確認すべき注意点
移行時は「開発者のPCで動いた」だけでは不十分です。本番展開やチーム展開では、RBAC、認証、ポータル、API、リージョン、CI/CDの確認が必要です。
| リスク | 起きる問題 | 対策 |
|---|---|---|
| 古いロール名のまま手順書を使う | 管理者が正しいロールを見つけられない | 新旧ロール名を併記し、IaCではロール定義IDを使う |
| Ownerを全開発者に付与する | 権限過多で監査・統制が弱くなる | 開発者はFoundry Userを基本にする |
| APIキー前提でサンプルを展開する | RBACによる制御が効きにくい | Entra ID認証とDefaultAzureCredentialを基本にする |
az loginをCI/CDで使う | MFAや対話ログインで自動化が止まる | サービスプリンシパル、マネージドID、フェデレーションIDを使う |
| SDK 1.xと2.xを混在させる | ModuleNotFoundError、404、予期しないAPI挙動が出る | サンプル、ポータル、SDKバージョンを同じ世代にそろえる |
| classicポータルのプロジェクトを新ポータルで探す | プロジェクトが見つからない | classicとcurrentの表示差分を確認する |
| Assistants APIのコードを残す | 将来のAPI移行対応が必要になる | Responses API / Agents v2への移行計画を立てる |
| リージョン確認をしない | Responses APIやAgents機能が使えない場合がある | 移行前に対象リージョンの対応状況を確認する |
公式の移行ガイドでは、azure-ai-inferenceパッケージのリタイア日が2026年5月30日、Assistants APIの終了日が2026年8月26日として示されています。旧パッケージや旧APIを使うチームは、開発環境の準備と同時に移行対象コードを洗い出すべきです。(Microsoft Learn)
VS Code拡張とGitは「任意」ではなく開発効率に直結する
Foundry VS Code拡張は、VS Code上からモデルのデプロイ、AIアプリ開発、Agents操作を行うための拡張機能です。必須ではありませんが、チームでサンプルを試しながら開発する場合、ポータルとローカルIDEを行き来する手間を減らせます。公式手順でも、Foundry VS Code拡張とGitのインストールが開発環境準備に含まれています。(Microsoft Learn)
Gitについては、単にソース管理のためだけではありません。Foundry SDKのサンプルやAI solution templatesを取得する場面で必要になります。開発者の初回セットアップでは、Gitが入っていないためにテンプレート取得で止まるケースがよくあります。
git --versionこのコマンドが通らない場合は、SDKやAzure CLIより先にGitを整備した方が早いです。
開発開始前の実用チェックリスト
チームに展開する前に、管理者と開発者で次の項目を確認してください。
管理者向けチェック
- Azureサブスクリプションが有効で、対象リソースグループが決まっている
- Foundryリソースとプロジェクトの作成方針が決まっている
- 開発者には原則Foundry Userを割り当てる
- プロジェクト管理者にはFoundry Project Managerを割り当てる
- ロール名変更に備えて、手順書に旧称と新称を併記する
- 自動化ではユーザーの
az loginではなく、サービスプリンシパル、マネージドID、フェデレーションIDを使う - 新旧ポータルのどちらを前提にするか決める
- SDK 1.x、2.x、OpenAI SDK、Foundry SDKの採用方針を決める
開発者向けチェック
- VS Codeまたは利用するIDEをインストールしている
- 採用言語のランタイムが入っている
- Pythonでは
.venvなどの仮想環境を使っている - Azure CLIが入り、
az loginとaz account showが成功する - 複数サブスクリプションがある場合、正しいサブスクリプションを選んでいる
- Foundry VS Code拡張を導入している
- Gitが入り、サンプルをcloneできる
PROJECT_ENDPOINTなど、クイックスタートで必要な環境変数を設定できる- 使っているサンプルがAzure AI Projects 2.x向けか1.x向けか確認している
よくあるトラブルと対処法
| 症状 | 主な原因 | 対処 |
|---|---|---|
azコマンドが見つからない | PATHが反映されていない | ターミナルやVS Codeを再起動する |
az loginでブラウザが開かない | ブラウザ認証の問題 | az login --use-device-codeを使う |
| Pythonが見つからない | OSごとのコマンド差異 | macOS/Linuxではpython3を使う |
ModuleNotFoundErrorが出る | 仮想環境が違う、SDK未導入 | .venvを有効化し、VS Codeのインタープリターも確認する |
| 404やエンドポイントエラーが出る | Project endpointとOpenAI互換エンドポイントの混同 | 使うSDKに合わせてエンドポイントを見直す |
| 権限エラーが出る | RBACロール不足 | Foundry User以上が正しいスコープに付いているか確認する |
| CI/CDで認証が止まる | 対話ログインやMFAに依存している | ワークロードIDへ移行する |
| 新ポータルでプロジェクトが見えない | classic側のプロジェクトを探している | classicポータルへの切り替えや移行を確認する |
まず何から対応すべきか
Azure AI Foundryの開発環境準備では、最初にSDKを入れるのではなく、権限・認証・ランタイム・CLI・エンドポイントの前提をそろえることが重要です。
まず管理者は、Foundry Userを中心にした最小権限のRBAC設計、Entra ID認証、CI/CD用のワークロードIDを確認してください。次に開発者は、言語ランタイム、Azure CLI、VS Code拡張、Git、仮想環境を整え、az account showで正しいサブスクリプションにいることを確認します。
そのうえで、クイックスタートに進み、PROJECT_ENDPOINT、SDKバージョン、認証方式をそろえて最初のAPI呼び出しを実行します。旧Azure AI Foundryやclassicポータルの資産がある場合は、SDK 1.xと2.x、Assistants APIとResponses APIの違いを先に棚卸ししてから移行計画を立てると、後工程の手戻りを減らせます。
コメント