Azure AI FoundryでLangGraphを使う場合、まず押さえるべき結論は、langchain-azure-aiを使ってFoundry Agent ServiceのエージェントをLangGraph／LangChainアプリに組み込み、既存エージェントの再利用、マルチエージェント構成、ツール実行、承認フロー、トレースまで一連の実装パターンとして扱えるようになっていることです。管理者や開発者がすぐ確認すべきなのは、AZURE_AI_PROJECT_ENDPOINT、モデルデプロイ名、Microsoft Entra ID／Azure RBAC、Foundry新ポータルとclassicの違い、ツールの実行場所、Application Insightsを含む監視設定です。(Microsoft Learn)
2026年5月19日（日本時間）前後の公式Docs更新として見ると、対象ドキュメントを含むFoundry関連ファイルにms.subservice: foundry-sdkが追加され、Foundry SDK領域のドキュメントとして整理されています。差分そのものは主にメタデータ整理ですが、実務上は「LangGraphをAzure AI FoundryのAgent Serviceとどう接続し、どう運用するか」を確認するタイミングと捉えるのが有効です。(GitHub)
Azure AI FoundryのAgent Service更新で何が変わるのか
今回のポイントは、LangGraphを単独のワークフローエンジンとして使うだけでなく、Foundry Agent Service上のエージェントをLangGraphのノードとして扱えることです。公式ドキュメントでは、langchain-azure-aiパッケージを使い、既存エージェントの利用、マルチエージェントグラフ、ツール付きワークフロー、human-in-the-loop承認、トレースまでを実用シナリオとして扱っています。(Microsoft Learn)
| 確認項目 | 変わること・重要になること | 実務での判断基準 |
|---|---|---|
| エージェントの扱い | Foundry Agent ServiceのエージェントをLangGraph互換ノードとして利用できる | 本番はFoundryポータルまたはSDKで作った既存エージェントを参照し、コードはオーケストレーションに集中させる |
| グラフ構成 | ローカルのルーティング処理とFoundryエージェントを組み合わせられる | 問い合わせ分類、専門エージェントへの委譲、承認が必要な処理の分岐に向く |
| ツール実行 | ローカルツールと組み込みツールの実行場所が分かれる | データ境界、権限、ログ、ネットワーク到達性を分けて設計する |
| 承認フロー | MCPToolなどでツール実行前の承認を組み込める | 外部API呼び出し、書き込み、削除、課金につながる操作では承認を必須にする |
| 可観測性 | OpenTelemetry、Application Insights、Azure Monitorで実行状況を確認する | 障害調査だけでなく、モデル・ツール・エージェント単位の改善に使う |
| classic移行 | v1系と新しいFoundryポータル向け実装を混同しない | 既存コードのimport、インストールオプション、ポータル上の表示先を棚卸しする |
特に注意したいのは、「LangGraphを使える」こと自体よりも、どの処理がアプリ側で実行され、どの処理がFoundry Agent Service側で実行されるかです。ここを曖昧にすると、ツールの権限、ログの見え方、データの保存場所、障害時の切り分けでつまずきます。
対象になる利用者と影響範囲
この更新の影響を受けやすいのは、Azure AI Foundry上でAIエージェント、Copilot風アプリ、社内ナレッジ検索、業務自動化エージェントを開発しているチームです。特に、LangChain／LangGraphを既にPoCで使っていて、本番運用に向けてAzure側の認証、監視、権限管理に寄せたい場合は確認優先度が高くなります。
開発者への影響
開発者は、AgentServiceFactoryを起点にFoundryプロジェクトへ接続し、既存エージェントをget_agent_nodeで参照するか、create_prompt_agentでコードからエージェントを作成できます。公式ドキュメントでは、本番に近い構成ではFoundryポータルまたはFoundry SDKでエージェント設定を一元管理し、コード側ではグラフの構成に集中する方法が推奨されています。(Microsoft Learn)
実務では、次のように使い分けると判断しやすくなります。
| 実装方法 | 向いている場面 | 注意点 |
|---|---|---|
既存エージェントをget_agent_nodeで参照 | 本番運用、複数チームでのエージェント管理、設定変更をポータル側に寄せたい場合 | version="latest"は便利だが、本番では特定バージョン固定を検討する |
create_prompt_agentでコードから作成 | PoC、検証、自動テスト、エージェント設定をコード管理したい場合 | サンプル作成後の削除、命名ルール、重複作成を管理する |
| LangGraphのローカルノードと組み合わせる | 条件分岐、入力分類、専門エージェントへのルーティング | ローカル処理とFoundry側処理のログを分けて見られるようにする |
管理者への影響
管理者は、単にパッケージ導入を許可するだけでは不十分です。Foundryプロジェクト、モデルデプロイ、Azure RBAC、Microsoft Entra ID、Application Insights、下流リソースへのアクセス権を確認する必要があります。関連ドキュメントでは、Foundryプロジェクトエンドポイントを使う場合、認証にはMicrosoft Entra IDとAzure RBACが使われ、APIキーは/openai/v1などの直接サービスエンドポイント向けと説明されています。(Microsoft Learn)
また、FoundryのRBACロール名は変更が進んでおり、表示上は旧名が残る場合があります。ロールIDと中心的なアクセス許可は名前変更によって変わらないとされていますが、運用手順書や監査資料では旧名称と新名称の対応を確認しておくと混乱を防げます。(Microsoft Learn)
最初に確認すべき前提条件と設定
公式手順の前提条件は、Azureサブスクリプション、Foundryプロジェクト、プロジェクトにデプロイ済みのチャットモデル、Python 3.10以降、Azure CLIでのサインインです。モデル名としてgpt-4.1が例示されていますが、実際には自社プロジェクトでデプロイしたモデルのデプロイ名を指定します。(Microsoft Learn)
開発環境では、まずパッケージと認証ライブラリを入れます。
pip install -U "langchain-azure-ai[tools,opentelemetry]" azure-identity[tools]はDocument IntelligenceやAzure Logic Appsコネクタなどのツール利用、[opentelemetry]は生成AIソリューション向けのOpenTelemetryサポートを含めるために使います。(Microsoft Learn)
次に、プロジェクトエンドポイントとモデルデプロイ名を環境変数に設定します。
export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export MODEL_DEPLOYMENT_NAME="gpt-4.1"ここで失敗しやすいのは、Azure AI Foundryの「リソースのエンドポイント」と「Foundryプロジェクトのエンドポイント」を取り違えることです。AZURE_AI_PROJECT_ENDPOINTには、Foundryプロジェクトを指すURLを設定します。トラブルシューティングの公式チェックリストでも、正しいプロジェクトエンドポイントを指しているか、モデルデプロイ名が既存のデプロイと一致しているか、az account showで認証コンテキストを確認することが挙げられています。(Microsoft Learn)
AgentServiceFactoryでFoundry Agent Serviceへ接続する
AgentServiceFactoryは、LangGraph内でFoundry Agent Serviceと連携するエージェントを構成する入口です。このファクトリから作成または参照されるエージェントは、Foundryプロジェクト内で管理され、新しいFoundryポータルに表示されます。(Microsoft Learn)
基本形は次の通りです。
import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents import AgentServiceFactory
factory = AgentServiceFactory(
project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)ローカル開発ではAzure CLIのサインインを使えますが、本番ではマネージドIDを使う構成を検討してください。DefaultAzureCredentialは複数の資格情報ソースを順番に試すため便利ですが、より厳密に制御したい場合は、ローカル開発でAzureCliCredential、本番ワークロードでManagedIdentityCredentialのように明示的な資格情報へ置き換える考え方もあります。(Microsoft Learn)
既存エージェントをLangGraphノードとして使う
本番運用に近い構成では、FoundryポータルまたはFoundry SDKで作成・設定したエージェントを、コードから参照する形が扱いやすくなります。エージェントの設定をFoundry側に集約でき、アプリケーションコードはルーティングや状態管理などのオーケストレーションに集中できます。(Microsoft Learn)
echo_node = factory.get_agent_node(
name="my-echo-agent",
version="latest",
)version="latest"は検証では便利ですが、本番では意図しない挙動変更を避けるため、安定版のバージョン番号を固定する運用を検討してください。特に、社内問い合わせ、契約書レビュー、顧客対応など、回答の一貫性が求められる用途では、エージェントのプロンプトやツール設定が変わるだけで品質や監査結果に影響します。
LangGraphでルーティングやマルチエージェント構成を作る
LangGraphと組み合わせる利点は、すべての処理を1つの巨大なエージェントに任せるのではなく、条件分岐や専門エージェントへの委譲を明示的に設計できることです。公式例では、ローカルのrouter_nodeがユーザーメッセージを見て、Foundryエージェントに委譲するか、ローカルで処理するかを切り替える構成が示されています。(Microsoft Learn)
実務では、次のような構成が現実的です。
| ユースケース | LangGraph側の役割 | Foundry Agent Service側の役割 |
|---|---|---|
| 社内ヘルプデスク | 問い合わせ内容を分類し、IT、人事、経理に分岐 | 各領域の専門エージェントが回答生成やツール実行を担当 |
| ドキュメント処理 | 入力ファイル種別や処理ステータスを管理 | Document Intelligenceなどのツールを使って抽出・要約 |
| 顧客対応Copilot | 危険な操作や外部連携前に承認フローへ分岐 | 応答生成、検索、MCPToolなどのサーバー側ツール実行 |
| データ分析支援 | 入力データの検証、可視化依頼の分岐 | Code Interpreter Toolで分析や画像生成を実行 |
設計のコツは、「判断はLangGraph、専門処理はFoundryエージェント」と分けることです。すべてをエージェントの推論任せにすると、デバッグしにくく、監査もしづらくなります。逆に、条件分岐をグラフとして明示しておくと、どの入力がどのエージェントへ渡ったのかを説明しやすくなります。
ツール実行は「ローカル」と「組み込み」を分けて考える
Foundry Agent ServiceでLangGraphを使う際に、最も設計ミスが起きやすいのがツールです。公式ドキュメントでは、ローカルツールと組み込みツールを区別しています。ローカルツールはエージェントコードが動く場所で実行される関数やLangChain／LangGraphエコシステムのツールで、組み込みツールはFoundry Agent Service側でサーバーサイド実行されます。(Microsoft Learn)
| 種類 | 実行場所 | 例 | 注意点 |
|---|---|---|---|
| ローカルツール | アプリケーション実行環境 | Python関数、独自業務ロジック、Document Intelligence Toolなど | アプリ側のネットワーク、シークレット、依存ライブラリ、ログ管理が必要 |
| 組み込みツール | Foundry Agent Service側 | CodeInterpreterTool、ImageGenTool、FileSearchTool、MCPToolなど | Foundry側の権限、ファイル、ベクターストア、承認設定を確認する |
ローカルツールは、税率計算、社内ID変換、入力値検証など、決定論的な処理に向いています。組み込みツールは、コード実行、ファイル検索、画像生成、MCPサーバー連携など、Agent Service側で管理したい処理に向いています。
失敗しやすいのは、ローカルツールを「Azure側で勝手に動く」と誤解することです。ローカルツールはアプリの実行環境に依存します。App Service、Container Apps、AKS、Functionsなどへ展開する場合は、その実行基盤から必要なリソースへ到達できるか、認証情報が安全に渡されるかを確認してください。
Human-in-the-loop承認は本番運用で必ず検討する
MCPToolなど一部のツールでは、実行前に承認を要求できます。公式ドキュメントでは、require_approval="always"を指定し、LangGraphのCommandで承認を再開する例が示されています。(Microsoft Learn)
承認フローは、次のような処理で特に重要です。
| 承認を入れるべき処理 | 理由 |
|---|---|
| 外部APIへの書き込み | 誤った更新や二重登録を防ぐため |
| メール送信やチャット投稿 | 社外・部門外への誤送信を防ぐため |
| チケット作成・クローズ | 業務プロセスへ直接影響するため |
| ファイル削除・権限変更 | 復旧が難しい操作につながるため |
| 課金やリソース作成 | 想定外コストを防ぐため |
AIエージェントの本番導入では、「回答を生成する」よりも「実際に行動する」場面のリスクが大きくなります。読み取り専用の検索や要約であれば自動化しやすい一方、書き込みや外部送信は承認を挟む設計にしておくと、監査や社内説明がしやすくなります。
可観測性はApplication InsightsとAzure Monitorまで含めて設計する
LangGraphとFoundry Agent Serviceを組み合わせると、処理の一部はAgent Service側で実行され、他の部分はアプリケーションコード側で実行されます。公式ドキュメントでは、AzureAIOpenTelemetryTracerを使い、OpenTelemetry標準でAzure Application Insightsへトレースを送る方法が示されています。(Microsoft Learn)
重要なのは、トレース上で「2つのエージェント」を意識することです。1つはFoundryエージェント、もう1つは複数ノードで構成されたLangGraphグラフ全体です。FoundryエージェントのトレースはFoundryポータルで確認できますが、開発中にLangGraph全体のトレースを見るにはAzureポータルのAzure Monitorを使う必要があると説明されています。(Microsoft Learn)
運用時は、少なくとも次の項目をログやトレースで追えるようにしてください。
| 追跡したい項目 | 見るべき理由 |
|---|---|
| agent_id | どのエージェントが応答したかを切り分ける |
| conversation_id | 会話継続や問い合わせ単位の調査に使う |
| tool call | 外部リソース呼び出しや失敗箇所を確認する |
| 承認待ち・承認結果 | 人間の判断が介入したポイントを監査する |
| モデルデプロイ名 | モデル差し替えによる品質変化を分析する |
| レイテンシ | ボトルネックがモデル、ツール、ネットワークのどこにあるかを確認する |
classicから移行する場合の注意点
Foundry classicを利用している場合は、新しいFoundryポータル向けの実装と混同しないことが重要です。公式ドキュメントでは、langchain_azure_ai.agents.v1.AgentServiceFactoryで作成されたエージェントはFoundryポータルclassicにのみ表示されると説明されています。(Microsoft Learn)
classic向けドキュメントでは、langchain-azure-ai[tools,v1]やazure-ai-agentsを含むインストール例が示され、[v1]はFoundry classicサポートを含めるために必要とされています。(Microsoft Learn)
移行時は、次の順番で棚卸ししてください。
| 確認対象 | 確認内容 | 対応の目安 |
|---|---|---|
| Python import | langchain_azure_ai.agents.v1を使っていないか | 新ポータル向けはlangchain_azure_ai.agentsへ移行を検討 |
| インストールオプション | [v1]を前提にしていないか | classic継続なら維持、新環境なら不要か確認 |
| エージェント表示先 | classic側にしか表示されないエージェントがないか | 新ポータルで再作成・再設定が必要か判断 |
| エンドポイント | 正しいFoundryプロジェクトエンドポイントか | 環境変数とCI/CDのシークレットを更新 |
| バージョン指定 | latest依存になっていないか | 本番は固定バージョンで検証 |
| ツール設定 | ファイル、ベクターストア、MCPサーバーが移行先で使えるか | 権限・リージョン・接続先を再確認 |
移行の失敗例として多いのは、コードだけを新パッケージへ変更し、ポータル上のエージェントやツールリソースを移していないケースです。エージェントが見つからない、ツールだけ動かない、トレースが出ないといった症状は、classicと新ポータルの混在が原因になりやすいです。
展開前チェックリスト
本番または社内検証環境へ展開する前に、以下を確認してください。
| 分類 | チェック項目 | 合格基準 |
|---|---|---|
| 接続 | AZURE_AI_PROJECT_ENDPOINTが正しい | Foundryプロジェクトのエンドポイントを指している |
| モデル | MODEL_DEPLOYMENT_NAMEが正しい | 対象プロジェクトに同名のモデルデプロイが存在する |
| 認証 | Entra ID／RBACが設定済み | 開発者、CI/CD、実行基盤のIDが必要最小権限を持つ |
| 実行環境 | Python 3.10以降 | 依存パッケージとランタイムが一致している |
| エージェント | 名前とバージョンを管理 | 本番ではlatest依存を避ける方針を決めている |
| ツール | ローカル／組み込みの実行場所を把握 | ネットワーク、認証、データ境界を説明できる |
| 承認 | 危険操作に承認を設定 | 書き込み、送信、削除、課金操作に人間の確認を入れる |
| 監視 | Application InsightsとAzure Monitorを設定 | agent_id、tool call、conversation_idを追える |
| クリーンアップ | サンプルエージェントを削除 | 検証用リソースが残っていない |
公式ドキュメントでも、サンプルで作成したエージェントは未使用リソースを残さないよう削除すること、削除後はLangGraphオブジェクトを使用できないことが明記されています。検証コードにfactory.delete_agent()を入れる場合は、本番エージェントを誤って削除しないよう、名前空間や環境名を分けてください。(Microsoft Learn)
よくあるトラブルと切り分け方
| 症状 | よくある原因 | 最初に確認すること |
|---|---|---|
| 認証エラーになる | Azure CLIのテナント違い、RBAC不足、マネージドID未設定 | az account show、実行ID、Foundryプロジェクトのロール |
| エージェントが見つからない | 新ポータルとclassicの混在、名前・バージョン違い | importがv1か、ポータル上の表示先、get_agent_nodeの指定 |
| モデル呼び出しに失敗する | デプロイ名の不一致、モデル未デプロイ | MODEL_DEPLOYMENT_NAMEとFoundry上のデプロイ一覧 |
| ツールだけ失敗する | ローカル実行環境に依存関係がない、サーバー側リソースがない | ツールがローカルか組み込みか、ベクターストアやファイルIDの存在 |
| トレースが出ない | OpenTelemetry設定不足、Application Insights接続不足 | AzureAIOpenTelemetryTracer設定、Azure MonitorのAgentsビュー |
| 承認後に再開できない | thread_idやcheckpointerの設定不足 | LangGraphのconfig、MemorySaver、Commandのresume指定 |
公式のトラブルシューティングでも、まず診断ログを有効にし、構成、認証コンテキスト、モデルデプロイ、下流依存リソース、サブスクリプションやリージョンを確認する流れが示されています。(Microsoft Learn)
まず取るべき次のアクション
Azure AI FoundryでLangGraphを使うなら、最初に大規模なマルチエージェント構成を作るのではなく、既存エージェントを1つget_agent_nodeで参照し、最小のLangGraphから動作確認してください。その後、ローカルツール、組み込みツール、承認フロー、トレースを順番に追加すると、問題の切り分けがしやすくなります。
管理者は、Foundryプロジェクト、RBAC、モデルデプロイ、Application Insights、classic利用有無を先に棚卸ししてください。開発者は、AgentServiceFactory、AZURE_AI_PROJECT_ENDPOINT、MODEL_DEPLOYMENT_NAME、エージェントのバージョン固定、ツールの実行場所を確認してください。ここまで整えば、LangGraphとFoundry Agent Serviceを組み合わせた実用的なAIエージェントを、PoCから本番運用へ進めやすくなります。
コメント