Azure AI FoundryでLangChain／LangGraphアプリを作る場合、今後はlangchain-azure-aiパッケージを入口にし、Foundryプロジェクトのエンドポイント、Microsoft Entra ID認証、Foundry RBACを前提に設計するのが基本です。今回の公式情報は、単なるサンプルコードの追加ではなく、モデル呼び出し、エージェント、RAG、ツール連携、トレーシングをFoundry上でどう組み立てるかを整理した開発者向けガイドと見るべきです。(Microsoft Learn)
特に確認すべき点は、langchain-azure-aiの利用、Foundryの新しい環境とclassic環境の使い分け、RBACロール名の変更、APIキーよりもMicrosoft Entra IDを優先する認証設計、そしてtoolsやopentelemetryなどの追加パッケージの選択です。既存のAzure OpenAI連携やFoundry classic向けコードを流用しているチームは、移行時にエンドポイント、認証、依存関係、監視設定を見直す必要があります。
Azure AI FoundryとLangChain／LangGraph連携で何が変わるのか
今回の公式情報で中心に置かれているのは、langchain-azure-aiパッケージです。これは、Azure AI Foundryの機能をLangChainやLangGraphアプリケーションから利用するための統合パッケージとして案内されています。Microsoft Learnでは、Foundry Agent Service、Content Safety、チャットモデル、埋め込み、ベクトルストア、Retriever、チャット履歴、ツール、コールバック／トレーシングなどの機能が、このパッケージ配下の名前空間で整理されています。(Microsoft Learn)
要点を実務向けに言い換えると、Azure AI Foundry上で生成AIアプリを構築する際に、次のような設計が取りやすくなります。
| 目的 | 使う機能・名前空間の例 | 実務での使いどころ |
|---|---|---|
| モデルを呼び出す | langchain_azure_ai.chat_models | Azure OpenAIやモデルカタログのチャットモデルをアプリから利用する |
| RAGを作る | embeddings、vectorstores、retrievers | 社内文書検索、FAQ、ナレッジボット |
| エージェントを組む | langchain_azure_ai.agents | Foundry Agent ServiceをLangGraphのノードとして組み込む |
| 安全性を高める | langchain_azure_ai.agents.middleware | Content Safetyやモデレーションをワークフローに組み込む |
| ツールを追加する | langchain_azure_ai.tools | Document Intelligence、Vision、Logic Appsなどと連携する |
| 監視する | langchain_azure_ai.callbacks | OpenTelemetryで実行トレースを収集する |
従来の「モデルを呼ぶだけ」のアプリであれば影響は限定的です。一方で、RAG、エージェント、ツール呼び出し、マルチステップ処理、監査ログ、運用監視まで含めた業務アプリでは、今回の整理に合わせて構成を見直す価値があります。
管理者が最初に確認すべきポイント
管理者がまず見るべきなのは、ライブラリの使い方そのものではなく、プロジェクト、権限、認証、ネットワーク、監視の設計です。開発者がサンプルコードを動かせても、本番環境で安全に展開できるとは限りません。
FoundryプロジェクトとRBACロールを確認する
公式情報では、前提条件としてAzureサブスクリプション、Foundryプロジェクト、Python 3.10以降、Azure CLIでのサインインなどが示されています。また、開発用途の最小権限としてFoundryプロジェクト上のFoundry Userロールが案内されています。(Microsoft Learn)
注意すべきなのは、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、CI/CD、権限付与スクリプトでロール名ではなくロール定義IDを使うと、名称変更の影響を受けにくくなります。公式RBAC情報でも、ロール名変更の展開中はGUIDを使うことが推奨されています。(Microsoft Learn)
| 確認項目 | 管理者が見るべき内容 | 放置した場合のリスク |
|---|---|---|
| ロール名 | 旧Azure AI系ロール名を前提にした手順が残っていないか | 権限付与の混乱、問い合わせ増加 |
| スコープ | サブスクリプション、リソース、プロジェクトのどこに付与するか | 過剰権限または403エラー |
| IaC／CLI | ロール名で指定していないか | 名称変更時に自動化が失敗する可能性 |
| 開発者権限 | Foundry Userで十分か、Project Managerが必要か | モデル展開やプロジェクト作成ができない |
| マネージドID | 実行環境のIDにも必要なロールがあるか | 本番だけ認証に失敗する |
APIキー中心の運用を見直す
今回のLangChain／LangGraph連携では、Foundryプロジェクトエンドポイントを使う場合、Microsoft Entra IDとAzure RBACで認証する流れが重視されています。公式ドキュメントでは、project_endpointを使う場合はMicrosoft Entra IDとプロジェクト上のAzure RBACが使われ、APIキーは/openai/v1のような直接サービスエンドポイント向けと説明されています。(Microsoft Learn)
本番環境では、APIキーよりもMicrosoft Entra ID認証を優先すべきです。Microsoftの認証・認可ドキュメントでも、Microsoft Entra IDは条件付きアクセス、マネージドID、細かなRBACに対応し、APIキーは迅速な試作には便利だが、ユーザー単位の追跡や細かな権限管理には向かないと説明されています。(Microsoft Learn)
判断基準はシンプルです。
| シナリオ | 推奨される認証 | 理由 |
|---|---|---|
| 個人の検証、短期PoC | APIキーも選択肢 | セットアップが簡単。ただし漏えい対策とローテーションは必須 |
| チーム開発 | Microsoft Entra ID | 開発者ごとの権限管理と監査がしやすい |
| 本番アプリ | マネージドIDまたはサービスプリンシパル | シークレットをコードや環境変数に置かずに済む |
| エージェント、評価、Toolbox連携 | Microsoft Entra ID | 一部機能ではEntra ID前提の設計になる |
| 監査や内部統制が必要な環境 | Microsoft Entra ID | 誰が何を実行したかを追跡しやすい |
APIキーを使う場合でも、ソースコード、Dockerイメージ、GitHub Actionsのログ、チャットツールへの貼り付けに残さないことが最低条件です。キーを使った試作から本番へ進む段階で、Entra ID認証へ切り替える計画を先に決めておくと、後からの手戻りを減らせます。
開発者が確認すべきインストールと依存関係
基本のインストールは次の形です。
pip install -U langchain-azure-ai azure-identityFoundry関連ツールを使う場合はtools、OpenTelemetry連携を使う場合はopentelemetryの追加インストールが案内されています。(Microsoft Learn)
pip install -U "langchain-azure-ai[tools]"
pip install -U "langchain-azure-ai[opentelemetry]"ここで失敗しやすいのは、最初から全部入れることです。検証環境では問題なくても、本番イメージのサイズ増加、依存関係の競合、セキュリティスキャンの指摘増加につながることがあります。
おすすめは、アプリの用途に合わせて段階的に追加する方法です。
| アプリの種類 | 入れるパッケージ | 補足 |
|---|---|---|
| モデル呼び出しだけ | langchain-azure-ai、azure-identity | まずは最小構成で十分 |
| Document IntelligenceやLogic Appsを使う | langchain-azure-ai[tools] | ツール系名前空間を使う場合に追加 |
| LangGraphの実行トレースを取りたい | langchain-azure-ai[opentelemetry] | Application InsightsやAzure Monitor連携を想定 |
| Foundry classicから移行中 | langchain-azure-ai[v1] | 非推奨クラスが必要な移行期間向け |
PyPI上のlangchain-azure-aiは、Python 3.10以上を要求し、tools、opentelemetry、v1などのextraを提供しています。2026年4月23日リリースの1.2.3では、Azure AI Foundryプロジェクトで管理されるツールにアクセスするAzureAIProjectToolboxの追加や、OpenTelemetryトレーサーの更新、依存パッケージのセキュリティ修正などが記載されています。(PyPI)
Foundry newとFoundry classicの違いに注意する
公式情報では、Microsoft Foundryの新しい環境ではazure-ai-projects>=2.0を使うこと、Foundry classicを使う場合はlangchain-azure-ai[v1]を使うことが示されています。(Microsoft Learn)
これは移行計画に大きく関わります。既存コードがFoundry classic向けのクラスや接続方式に依存している場合、単にパッケージを更新するだけでは動作しない可能性があります。
移行時は、次の順で確認すると安全です。
| 確認順 | 確認内容 | 見るべきポイント |
|---|---|---|
| 1 | 現在の環境がFoundry newかclassicか | プロジェクト、SDK、既存コードの前提を確認 |
| 2 | langchain-azure-aiのインストール方法 | [v1]が必要な旧クラスを使っていないか |
| 3 | エンドポイント指定 | project_connection_stringなど旧式の指定が残っていないか |
| 4 | 認証方式 | APIキー依存か、DefaultAzureCredentialへ移行できるか |
| 5 | 回帰テスト | モデル応答、RAG検索、ツール呼び出し、トレースを個別に確認 |
特に、Agent Service V1やAzure AI Inference SDK系の古いクラスを使っている場合は注意が必要です。langchain-azure-aiの変更履歴では、Foundry Agents V1からV2への移行、OpenAI互換APIへの移行、旧クラスはv1 extraが必要になることが説明されています。(PyPI)
エンドポイント設計はproject_endpointを基準にする
今回の公式情報では、多くのlangchain-azure-aiクラスがFoundryプロジェクトエンドポイント経由の接続に対応しており、AZURE_AI_PROJECT_ENDPOINTを一度設定して再利用できると説明されています。(Microsoft Learn)
export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"この考え方は、開発・検証・本番の環境分離にも向いています。たとえば、同じコードを使いながら、環境変数だけを切り替えて検証用プロジェクトと本番用プロジェクトを分けられます。
一方、直接サービスエンドポイントを使う場合は、次のような設定になります。
export OPENAI_BASE_URL="https://<resource>.services.ai.azure.com/openai/v1"
export OPENAI_API_KEY="<your-key>"どちらを選ぶかは、アプリの運用方針で決めるべきです。
| 接続方式 | 向いているケース | 注意点 |
|---|---|---|
| Foundryプロジェクトエンドポイント | 複数機能をFoundryプロジェクト単位で管理したい | Entra IDとRBAC設定が必要 |
| 直接サービスエンドポイント | モデル呼び出し中心の簡単な検証 | APIキー管理や権限分離に注意 |
| 両方を併用 | 移行期、PoCから本番への段階移行 | 設定が混在しやすいため命名ルールを決める |
実務では、開発初期にAPIキーで動作確認し、その後project_endpointとDefaultAzureCredentialへ移行するケースが多くなります。ただし、最初から本番化を見据えるなら、PoC段階でもEntra ID認証で試すほうが後工程の手戻りを減らせます。
DefaultAzureCredentialの動作を理解しておく
サンプルコードではDefaultAzureCredentialが使われています。これは、環境変数、マネージドID、開発者ツール、Azure CLIなど複数の認証情報ソースを順番に試し、最初に成功したものを使う仕組みです。公式情報でも、ローカル開発とデプロイ済みワークロードの既定値として使える一方、より厳密に制御したい場合はAzureCliCredentialやManagedIdentityCredentialなどに置き換える選択肢が示されています。(Microsoft Learn)
便利な反面、DefaultAzureCredentialには「ローカルでは動くが本番では動かない」落とし穴があります。
よくある原因は次の通りです。
| 症状 | 原因 | 対処 |
|---|---|---|
| ローカルでは成功、本番で401 | 本番のマネージドIDが有効でない | App Service、Functions、Container AppsなどでマネージドIDを有効化する |
| 本番で403 | IDは通っているがRBACが不足 | Foundry Userなど必要なロールを対象スコープに付与する |
| 開発者Aだけ動かない | Azure CLIのログイン先テナントが違う | az account showでサブスクリプションとテナントを確認 |
| CI/CDで失敗 | サービスプリンシパルに権限がない | デプロイ用IDと実行用IDを分けて権限を付与 |
| 意図しないIDで実行される | 複数の認証情報ソースが存在 | 本番ではManagedIdentityCredentialなど明示的な認証にする |
開発者向けにはDefaultAzureCredentialで始めても構いません。ただし、本番では「どのIDで実行されるか」をログや構成で確認できる状態にしておくべきです。
LangChain／LangGraphで使えるFoundry機能の整理
langchain-azure-aiは、モデル呼び出しだけでなく、エージェント、RAG、ツール、安全性、監視まで広くカバーします。すべてを一度に使う必要はありません。業務要件に合わせて、必要な部品を選ぶことが重要です。
チャットモデル：まずは最小構成で動作確認する
チャットモデルでは、Azure OpenAIやFoundryモデルカタログのモデルを呼び出せます。公式サンプルでは、init_chat_model("azure_ai:gpt-5.2")のような初期化例や、AzureAIOpenAIApiChatModelを使ってプロジェクトエンドポイントまたは直接エンドポイントからモデルを使う例が示されています。(Microsoft Learn)
実務では、まず次の3点を確認します。
- モデル名が実際にプロジェクトで利用可能か
- 認証方式がAPIキーかEntra IDか
- ストリーミング、JSON出力、ツール呼び出しなど必要な機能が動くか
モデル名は公式サンプルに出ているものをそのまま本番前提にせず、自社のFoundryプロジェクトでデプロイ済みのモデル名に置き換えて確認してください。
EmbeddingsとVector stores：RAGでは検索品質も設計する
RAGアプリでは、embeddings、vectorstores、retrieversの使い分けが重要です。公式情報では、Embeddingモデルで検索、取得、ランキング向けのベクトルを生成し、Azure AI SearchやCosmos DBのベクトル統合を使えることが整理されています。(Microsoft Learn)
管理者と開発者が一緒に決めるべきなのは、検索インデックスの場所、アクセス権、データ更新頻度、ログの扱いです。単にベクトル検索を動かすだけでは、社内文書の更新漏れ、権限外文書の参照、低品質な回答が起きます。
RAG展開前には、次をチェックしてください。
| 項目 | 確認内容 |
|---|---|
| データソース | SharePoint、Blob Storage、DBなど、どこから取り込むか |
| 権限 | ユーザーごとの閲覧権限を検索結果に反映できるか |
| 更新頻度 | 日次、時間単位、イベント駆動のどれが必要か |
| 評価 | 正解データを用意し、検索ヒット率と回答品質を測るか |
| 監査 | どの文書が回答に使われたかを記録するか |
Agent Service：LangGraphのノードとして使うと設計しやすい
Foundry Agent Serviceは、LangGraphやLangChainアプリから接続できます。関連ドキュメントでは、既存エージェントの利用、マルチエージェント構成、ツール付きワークフロー、人間による承認、トレーシングなどの実践シナリオが扱われています。(Microsoft Learn)
エージェントは便利ですが、業務アプリでは暴走や過剰実行を防ぐ設計が必要です。特に、外部システムを操作するツールを持たせる場合は、必ず次を決めてください。
| 設計項目 | 例 |
|---|---|
| 実行できる操作 | 読み取りだけ、申請作成まで、承認後に更新まで |
| 人間の承認 | 見積送信、顧客連絡、データ削除などは承認必須 |
| 失敗時の扱い | 再試行回数、タイムアウト、手動対応への切り替え |
| ログ | 入力、判断、ツール呼び出し、結果を追跡できるか |
| 権限 | エージェント用IDの権限を最小限にする |
「何でもできるAIエージェント」ではなく、「業務上許可された範囲で動くエージェント」として設計することが、本番展開の前提です。
Content Safety：後付けではなくワークフローに組み込む
langchain_azure_ai.agents.middlewareでは、Foundry Content Safetyやモデレーションを使って、ガードレールを組み込めます。公式情報では、Content Safetyを使って適切なガードレールを持つソリューションを展開する用途が示されています。(Microsoft Learn)
安全性チェックは、公開直前に追加するよりも、設計段階から組み込むほうが効果的です。たとえば、問い合わせチャットならユーザー入力とモデル出力の両方をチェックし、社内文書検索ならプロンプトインジェクションや機密情報の扱いを評価します。
特に注意したいのは、ブロック基準を厳しくしすぎると業務に使いにくくなり、緩すぎるとリスクが残る点です。検証時には、通常の問い合わせ、悪意ある入力、曖昧な入力、社外秘を含む入力など、複数パターンでテストしてください。
OpenTelemetryとAzure Monitor：本番ではトレースを必ず取る
LangChainやLangGraphのアプリは、単純なAPI呼び出しよりも処理経路が複雑です。モデル呼び出し、検索、ツール実行、条件分岐、リトライが絡むため、障害時に「どこで失敗したか」が分からなくなりがちです。
langchain-azure-ai[opentelemetry]を使うと、OpenTelemetryによるトレーシング連携を追加できます。PyPI上の説明でも、Azure Application Insightsへの自動トレーシング例が示され、enable_content_recordingでメッセージ内容の記録有無を制御する例が掲載されています。(PyPI)
本番で特に重要なのは、内容を記録するかどうかです。問い合わせ本文や社内文書の断片をトレースに残すと、調査はしやすくなりますが、個人情報や機密情報の管理範囲が広がります。
| 設定観点 | 推奨される考え方 |
|---|---|
| トレース取得 | 本番では取得する |
| メッセージ本文の記録 | 原則は最小化。必要な場合は保存先と閲覧権限を制限 |
| エラー情報 | モデル名、ツール名、実行時間、エラー種別は残す |
| 権限 | Application InsightsやAzure Monitorの閲覧権限を限定 |
| 保存期間 | 監査要件とコストを踏まえて設定 |
既存環境への影響範囲
今回の公式情報による影響は、すべてのAzure AI Foundry利用者に同じように及ぶわけではありません。影響が大きいのは、LangChain／LangGraphでAzure AI Foundryを本格利用している、またはこれから本番化するチームです。
| 利用状況 | 影響度 | 確認すべきこと |
|---|---|---|
| Azure AI Foundryをまだ使っていない | 低 | 新規構築時にlangchain-azure-aiを前提に設計 |
| Azure OpenAIをAPIキーで呼んでいるだけ | 中 | 将来のFoundry統合、Entra ID移行、監視を検討 |
| LangChainでRAGを構築済み | 中〜高 | パッケージ、認証、Vector store連携、トレースを確認 |
| LangGraphでエージェントを構築中 | 高 | Agent Service、RBAC、Content Safety、承認フローを確認 |
| Foundry classicを利用中 | 高 | [v1] extraの必要性、新環境への移行計画を確認 |
| 本番でAIアプリを運用中 | 高 | 監査、権限、キー管理、トレース、障害対応を見直し |
「サンプルコードが変わった」と捉えると影響を過小評価しがちです。実際には、認証、権限、運用監視、移行方針まで含めて見直すべき情報です。
移行・展開時の実務チェックリスト
本番展開前には、次のチェックリストを使うと抜け漏れを減らせます。
管理者向けチェックリスト
| チェック | 内容 |
|---|---|
| Foundryプロジェクト | 開発、検証、本番でプロジェクトを分けているか |
| RBAC | 開発者、管理者、実行用IDに必要最小限のロールを付与しているか |
| ロール名変更 | 旧Azure AIロール名を前提にした手順やスクリプトが残っていないか |
| 認証 | 本番でAPIキーではなくEntra ID／マネージドIDを使う設計か |
| シークレット | APIキーや接続文字列をコード、ログ、CI/CD出力に残していないか |
| ネットワーク | 必要に応じてPrivate Link、ファイアウォール、許可IPを設計しているか |
| 監視 | Application InsightsやAzure Monitorの保存期間と閲覧権限を決めているか |
| コスト | モデル呼び出し、検索、ツール、トレースのコストを見積もっているか |
開発者向けチェックリスト
| チェック | 内容 |
|---|---|
| Python | Python 3.10以降で動作確認しているか |
| パッケージ | langchain-azure-aiと必要なextraだけを入れているか |
| classic対応 | Foundry classic向けコードで[v1]が必要か確認したか |
| エンドポイント | AZURE_AI_PROJECT_ENDPOINTと直接エンドポイントを混在させていないか |
| 認証 | ローカル、CI/CD、本番で使うIDを明確にしているか |
| 例外処理 | 401、403、タイムアウト、モデル未展開時の処理を実装しているか |
| テスト | モデル応答、RAG検索、ツール実行、安全性チェックを個別にテストしたか |
| ログ | 機密情報を出さずに原因調査できるログを残しているか |
よくある失敗と対策
ローカルでは動くが本番で403になる
最も多い原因は、開発者本人には権限があるが、本番アプリのマネージドIDには権限がないケースです。DefaultAzureCredentialは環境に応じて異なるIDを使うため、ローカルの成功は本番の成功を保証しません。
対策は、実行環境のIDを明示し、そのIDにFoundry Userなど必要なロールを付与することです。モデルのデプロイやプロジェクト管理まで行う場合は、Foundry Project Manager以上が必要になることもあります。
APIキーを残したまま本番化してしまう
PoCで使ったAPIキーが、そのまま本番環境の環境変数やCI/CDシークレットに残ることがあります。APIキーは扱いやすい一方で、誰が使ったかの追跡や細かな権限制御が難しくなります。
対策は、本番化のゲートに「Entra ID認証へ切り替え済みか」を入れることです。どうしてもAPIキーを使う場合は、ローテーション手順、漏えい時の停止手順、キーの利用範囲を文書化してください。
旧クラスや旧接続方式を使い続ける
Foundry classicや古いAzure AI Inference SDK系のコードを使っている場合、パッケージ更新で破綻する可能性があります。v1 extraで一時的に維持できる場合もありますが、長期的には新しいFoundry環境とOpenAI互換API前提の構成へ移行する計画が必要です。(PyPI)
対策は、旧コードを一括で置き換えるのではなく、モデル呼び出し、RAG、エージェント、監視の単位で移行対象を分けることです。まずはモデル呼び出しだけを新方式で動かし、次に検索、ツール、トレーシングへ進むと失敗しにくくなります。
トレースに機密情報を残してしまう
トレーシングは障害調査に有効ですが、入力プロンプトや検索結果の断片をそのまま記録すると、ログが機密情報の保管場所になります。
対策は、トレースで何を記録するかを明確にすることです。本文を記録しない設定を基本にし、必要な場合のみ閲覧権限と保存期間を厳しく制御してください。
まず何から対応すべきか
すでにAzure AI FoundryとLangChain／LangGraphを使っている場合は、次の順で確認すると効率的です。
langchain-azure-aiの利用状況とバージョンを確認する- Foundry newかclassicかを切り分ける
AZURE_AI_PROJECT_ENDPOINTを使う構成にできるか確認する- APIキー依存の箇所を洗い出す
- Foundry RBACロール名変更の影響を確認する
- 本番実行用IDに必要なロールを付与する
- RAG、Agent Service、Content Safety、Tracingを用途別に検証する
これから新規に作る場合は、最初からlangchain-azure-ai、Foundryプロジェクトエンドポイント、Microsoft Entra ID、最小権限RBAC、OpenTelemetryによる監視を前提に設計するのが安全です。
Azure AI FoundryのLangChain／LangGraph対応は、生成AIアプリを「試作」から「運用できる業務システム」へ進めるための整理だと捉えると分かりやすくなります。まずは自社のアプリがモデル呼び出しだけなのか、RAGやエージェントまで含むのかを切り分け、認証・権限・監視を含めて小さく検証してください。
コメント