MicrosoftのAIエージェント開発で重要になるのが、Agent Pipeline Architectureの理解です。結論から言うと、Microsoft Agent Frameworkでは、エージェントの処理が「ミドルウェア」「コンテキスト」「チャットクライアント」「ツール呼び出し」などの層に分かれており、どの層に処理を追加するかで、ログ取得、権限制御、RAG、Copilot連携、監査、移行時の修正範囲が変わります。
特に2026年5月26日前後に更新されたMicrosoft Agent Framework関連の公式情報では、Microsoft Foundry、GitHub Copilot Agents、ツール、プロバイダー対応の整理が進み、管理者や開発者は「どのエージェントがローカルのChatClientを使うのか」「どの機能がリモートサービス側で管理されるのか」「ツール実行やファイル操作をどこで承認・監査するのか」を確認する必要があります。Agent Pipeline Architectureそのものは、Agent Frameworkのリクエスト処理を層構造として説明する公式ドキュメントで、エージェントの挙動を安全にカスタマイズするための前提知識になります。(Microsoft Learn)
Agent Pipeline Architectureとは何か
Agent Pipeline Architectureとは、Microsoft Agent Frameworkのエージェントがユーザーからのリクエストを処理する流れを、複数の層に分けて整理した考え方です。
単純に「プロンプトをLLMへ送る仕組み」ではありません。実際には、入力の検証、履歴の読み込み、RAGやメモリの追加、ツール呼び出し、モデルへの送信、応答の整形、監査ログの出力といった処理が、決められた順序で実行されます。
Microsoftの公式ドキュメントでは、C#のChatClientAgentは主に次の3層で構成されると説明されています。(Microsoft Learn)
| 層 | 役割 | 代表的な用途 |
|---|---|---|
| Agent middleware | エージェント実行全体を包み込む | ログ、入力検証、監査、ブロック処理 |
| Context layer | 履歴や追加コンテキストを組み込む | 会話履歴、RAG、ユーザー設定、動的指示 |
| Chat client layer | LLMサービスとの通信を担当する | モデル呼び出し、チャットミドルウェア、ツール呼び出し |
Pythonでは、AgentとChatClientが分かれた構成として説明されており、Agent側ではミドルウェア、テレメトリ、RawAgent、Context Providersが動き、ChatClient側ではFunctionInvocation、Chat Middleware、RawChatClientがモデル通信を処理します。(Microsoft Learn)
ここで重要なのは、すべてのカスタマイズを同じ場所に入れるべきではないという点です。例えば、入力の禁止語チェックはAgent middlewareに向いていますが、検索結果や社内ナレッジを追加する処理はContext layerに置く方が自然です。LLMへの送信直前のメッセージやオプションを調整したい場合は、Chat client layerの方が適しています。
MicrosoftのAI/Copilot更新で何が変わるのか
今回のAgent Pipeline Architecture関連の更新を実務目線で見ると、変化の中心は「エージェントの処理場所が明確になったこと」です。
以前のAIエージェント開発では、プロンプト、ツール、履歴、ログ、承認処理をアプリケーション側にまとめて実装しがちでした。しかしMicrosoft Agent Frameworkでは、処理の責務が層ごとに整理されているため、どこに何を実装すべきかを設計しやすくなっています。
特に影響が大きいのは次の3点です。
| 変更・整理されたポイント | 影響を受ける人 | 確認すべきこと |
|---|---|---|
| エージェント処理が層構造で明確化 | 開発者、アーキテクト | ログ、検証、RAG、ツール制御をどの層に置くか |
| Microsoft FoundryやGitHub Copilot Agentsなどプロバイダーごとの差が明確化 | 管理者、開発者 | ローカルChatClientを使うか、サービス管理型エージェントを使うか |
| ツール実行、MCP、Bing/SharePoint/Fabric連携などの対応範囲が整理 | 管理者、セキュリティ担当 | 利用可能なツール、プレビュー機能、承認フロー、監査ログ |
Microsoft Foundryの公式情報では、Foundry連携には大きく「Responses Agent」と「Foundry Agent」の2パターンがあります。Responses Agentはアプリ側でモデル、指示、ツールをプログラム的に指定する方式で、Foundry AgentはFoundry側で作成・バージョン管理されたサービス管理型のエージェントを利用する方式です。(Microsoft Learn)
この違いは、管理者にとって非常に重要です。アプリケーション側で柔軟に指示やツールを差し替えたいならResponses Agentが扱いやすく、厳格なバージョン管理やポータル管理を重視するならFoundry Agentが向いています。ただし、Foundry Agentではツールや指示はFoundry側の定義に従うため、実行時にクライアント側から自由に変更する設計には向きません。(Microsoft Learn)
利用者への影響：CopilotやAIエージェントの挙動が安定しやすくなる
一般利用者にとって、Agent Pipeline Architectureそのものを意識する場面は多くありません。しかし、業務システムやCopilot連携アプリを使う側には、次のような形で影響が出ます。
会話履歴や文脈の扱いが改善しやすい
Context layerでは、会話履歴や追加情報をリクエスト前に組み込めます。MicrosoftのContext Providersの説明では、各呼び出しの前後でコンテキストを追加し、実行後のデータ処理もできるとされています。(Microsoft Learn)
これにより、例えば次のような挙動を作りやすくなります。
「前回の問い合わせ内容を踏まえて回答する」
「ユーザーの所属部署に応じて参照する社内文書を変える」
「SharePointやAzure AI Searchの検索結果を回答前に追加する」
「会話後に重要な情報だけをメモリへ保存する」
ただし、何でも履歴やメモリに保存すればよいわけではありません。個人情報、機密情報、不要な長文履歴を無制限に保持すると、セキュリティリスクやコスト増加につながります。利用者向けに「何が保存されるのか」「どの範囲で使われるのか」を明示する運用が必要です。
ツール実行前の承認を組み込みやすい
Agent FrameworkのTools Overviewでは、Function Tools、Code Interpreter、File Search、Web Search、Hosted MCP Tools、Local MCP Tools、Foundry Toolboxesなど、複数のツール種別が整理されています。また、Tool Approvalにより、ツール実行前に人間の承認を挟む設計が可能です。(Microsoft Learn)
これは、CopilotやAIエージェントが単なる回答生成ではなく、ファイル検索、コード実行、外部システム連携、MCP経由の操作を行う場面で重要です。
例えば、社内FAQを検索するだけなら自動実行でも問題ない場合があります。一方で、ファイルの書き換え、シェルコマンド実行、外部APIへの登録、顧客データの参照などは、承認や監査ログを必須にすべきです。
管理者が確認すべき設定・運用ポイント
管理者が最初に確認すべきなのは、Agent Pipeline Architectureの全体像ではなく、自社のエージェントがどの層で何をしているかです。
エージェント種別ごとの管理範囲を確認する
すべてのエージェントが同じパイプラインで動くわけではありません。公式ドキュメントでは、A2AAgent、GitHubCopilotAgent、CopilotStudioAgentなどはローカルのIChatClientを使わず、リモートサービスと通信するため、フルのChatClientAgentパイプラインを使わない場合があると説明されています。これらのエージェントでもAgent-level middlewareは使えますが、Chat client middlewareは適用できないケースがあります。(Microsoft Learn)
管理者は、次のように整理しておくと判断しやすくなります。
| 確認項目 | 見るべきポイント |
|---|---|
| エージェント種別 | ChatClientAgent、FoundryAgent、GitHubCopilotAgent、CopilotStudioAgentなど |
| 実行場所 | アプリ側、Foundry側、GitHub Copilot CLI側、外部A2A先 |
| ミドルウェア適用範囲 | Agent middlewareだけか、Chat middlewareまで使えるか |
| ツール定義の管理場所 | コード側か、Foundryポータル側か、リモートサービス側か |
| 監査対象 | 入力、出力、ツール呼び出し、承認結果、外部接続先 |
この整理をせずに導入すると、「ログを入れたつもりなのにLLM呼び出し部分が記録されない」「ツールの承認を実装したつもりだがリモート側の操作は対象外だった」といった見落としが起きやすくなります。
GitHub Copilot Agentsは権限管理を必ず確認する
GitHub Copilot Agentsは、GitHub Copilot SDKをバックエンドとして使うエージェントをAgent Frameworkから扱える仕組みです。公式ドキュメントでは、シェルコマンド実行、ファイル操作、URL取得、MCPサーバー連携などのコーディング向け機能にアクセスできると説明されています。(Microsoft Learn)
一方で、GitHub Copilot AgentsではGitHub Copilot CLIのインストールと認証が必要であり、シェルやファイル権限を使う場合はDockerやDev Containerなどのコンテナ化環境で実行することが推奨されています。(Microsoft Learn)
管理者が確認すべきポイントは次の通りです。
| 項目 | 推奨される確認内容 |
|---|---|
| 実行環境 | ローカルPCで直接実行させず、Dev Containerや隔離環境を使う |
| 権限 | シェル、ファイル読み書き、URL取得を既定で許可しない |
| 承認フロー | Permission handlerやTool Approvalで危険操作を止める |
| ログ | 実行コマンド、対象ファイル、承認者、結果を追跡する |
| MCP接続 | ローカルMCP、リモートMCPの接続先と認証方式を管理する |
特に、ファイル操作やシェル実行を許可する場合は、AIエージェントを「補助ツール」ではなく「操作権限を持つ実行主体」として扱う必要があります。
OpenTelemetryの二重記録と機密データに注意する
Agent FrameworkはOpenTelemetryとの統合に対応しており、トレース、ログ、メトリックを出力できます。公式ドキュメントでは、Agent FrameworkがOpenTelemetry GenAI Semantic Conventionsに従って情報を出力すると説明されています。(Microsoft Learn)
ただし、チャットクライアントとエージェントの両方で可観測性を有効にすると、プロンプトや応答などのチャットコンテキストが両方のスパンに含まれ、情報が重複する可能性があります。特に機密データを含むトレースを有効にする場合は、どの層で記録するかを明確にする必要があります。(Microsoft Learn)
実務では、次のようなルールを決めておくと安全です。
| 目的 | 推奨設定 |
|---|---|
| 全体の実行時間を見たい | Agent layer中心で計測 |
| モデル呼び出しの遅延を見たい | Chat client layer中心で計測 |
| ツール実行の失敗を追いたい | Function middlewareとTool Approval結果を記録 |
| 機密情報を扱う | プロンプト・応答本文の記録を最小化 |
| 障害解析を優先する検証環境 | 一時的に詳細ログを有効化し、本番とは分ける |
「あとで調査できるように全部ログに残す」は、AIエージェントでは危険です。プロンプトには業務情報や個人情報が含まれやすいため、ログ設計はセキュリティ設計の一部として扱うべきです。
開発者が押さえるべき実装ポイント
開発者にとってAgent Pipeline Architectureの最大のメリットは、カスタマイズ箇所を選べることです。
Agent middlewareは全体制御に使う
Agent middlewareは、エージェントの実行全体を横断的に制御したい場合に使います。公式ドキュメントでは、Agent FrameworkのMiddlewareはログ、セキュリティ検証、エラー処理、結果変換などの横断的関心事を、コアのエージェントや関数ロジックを変更せずに実装できる仕組みとして説明されています。(Microsoft Learn)
向いている処理は次の通りです。
| 向いている処理 | 理由 |
|---|---|
| 入力チェック | モデルやツールに渡す前に止められる |
| 監査ログ | すべての実行に一貫して適用できる |
| レート制限 | ユーザー単位、テナント単位で制御しやすい |
| 結果のマスキング | 応答が返る直前に加工できる |
| セキュリティブロック | 後続処理を実行せず終了できる |
一方で、Agent middlewareにRAG検索やモデル固有のオプション調整を詰め込みすぎると、処理の見通しが悪くなります。エージェント全体に共通する処理だけを置くのが基本です。
Context Providersは履歴・RAG・動的指示に使う
Context Providersは、実行前にメッセージ、ツール、指示などを追加し、実行後に状態を保存する用途に向いています。公式ドキュメントでは、カスタムContext Providerは動的な指示、メッセージ、ツールの注入や、実行後の状態抽出に使えると説明されています。(Microsoft Learn)
よくある活用例は次の通りです。
「顧客IDに基づいてCRM情報を取得する」
「SharePointの関連文書を検索して追加する」
「過去の会話からユーザーの好みを反映する」
「部署ごとに回答ポリシーを変える」
「実行後に重要なメモだけを保存する」
ただし、Context Providerのインスタンスにセッション固有の状態を直接持たせる設計は避けるべきです。公式ドキュメントでも、AIContextProviderのインスタンスは複数セッションで使われるため、セッション固有の値はAgentSession側に保存する考え方が示されています。(Microsoft Learn)
Chat middlewareはモデル呼び出し直前の調整に使う
Chat middlewareは、AIモデルへ送信されるメッセージ、オプション、応答を扱う層です。Pythonの説明では、Chat middlewareは関数呼び出しループの内部で実行され、ツール結果をモデルへ戻す呼び出しを含め、モデル呼び出しごとに実行されるとされています。(Microsoft Learn)
この性質を理解していないと、ログが想定より多く出たり、ミドルウェアが複数回動いてコストや遅延が増えたりします。
Chat middlewareに向いている処理は、モデル呼び出し単位のロギング、モデルオプションの調整、LLM応答の検査、プロバイダー固有のパラメータ処理などです。ツールを複数回呼ぶエージェントでは、Chat middlewareが何回実行されるかをテストで確認しておく必要があります。
移行時に確認すべきポイント
Microsoft Agent Frameworkを既存のSemantic Kernel、AutoGen、独自エージェント基盤、または古いAgent Frameworkプレビュー版から移行する場合、Agent Pipeline Architectureの理解は移行漏れの防止に役立ちます。
Pythonはパッケージ分割とAPI変更を確認する
公式のPython 2026 Significant Changes Guideでは、2026年のプレビューから1.0.0への移行に伴う重要な変更が整理されています。例えば、agent-framework、agent-framework-core、agent-framework-openai、agent-framework-foundryはリリース済みパッケージとして--preが不要になった一方、agent-framework-github-copilotやagent-framework-foundry-localなどの一部ベータ系コネクターでは引き続き--preが必要です。(Microsoft Learn)
また、PythonではFoundry関連の埋め込み機能がagent_framework.foundryへ移動し、スタンドアロンのagent-framework-azure-aiパッケージからの移行が必要になります。(Microsoft Learn)
確認すべき代表例は次の通りです。
| 確認対象 | 移行時の注意点 |
|---|---|
| パッケージ | agent-framework-coreだけで不足する場合は、OpenAIやFoundryなどプロバイダー別パッケージを明示的に追加 |
| モデル指定 | model_idではなくmodelへ統一されている箇所を確認 |
| メッセージ生成 | Message(..., text=...)ではなくcontents=[...]を使う |
| Foundry | agent_framework.foundry配下のクライアントと環境変数へ移行 |
| ワークフロー | function_invocation_kwargsとclient_kwargsの使い分けを確認 |
| GitHub Copilot | agent-framework-github-copilotのPython要件やツールハンドラー変更を確認 |
移行時にやりがちな失敗は、「動いているサンプルコードをそのまま本番コードへ混ぜること」です。プレビュー機能、ベータパッケージ、GAパッケージが混在しているため、依存関係ファイルでバージョンと--preの有無を明示する必要があります。
Foundry Agentは「実行時に差し替えられる」と思い込まない
Foundry Agentを使う場合、エージェント定義はFoundry側にあります。公式ドキュメントでは、Foundry Agentのツールや指示は作成時の定義に厳格であり、実行時にツールや指示を変更することはサポートされないとされています。(Microsoft Learn)
そのため、移行時には次の判断が必要です。
柔軟にプロンプトやツールをコードで切り替える必要があるなら、Responses AgentやChatClientAgent寄りの設計が向いています。監査済みのエージェント定義をポータルやサービスAPIで管理し、バージョン固定で運用したいなら、Foundry Agentが向いています。
この判断を後回しにすると、開発中は動いても、本番展開時に「運用部門がバージョン管理できない」「セキュリティ部門がツール定義を確認できない」「逆に開発側が必要な動的変更を行えない」といった問題が起きます。
展開・本番運用で注意すべきこと
Agent Pipeline Architectureは開発だけでなく、本番展開の設計にも直結します。
本番ではDefaultAzureCredentialの扱いに注意する
Microsoft FoundryやOpenTelemetryのサンプルではDefaultAzureCredentialが使われることがありますが、公式ドキュメントでは、本番環境ではManagedIdentityCredentialなど特定の資格情報を検討するよう注意されています。理由として、フォールバックによる遅延や意図しない資格情報探索、セキュリティリスクが挙げられています。(Microsoft Learn)
本番では、少なくとも次を確認してください。
| 確認項目 | 推奨 |
|---|---|
| Azure認証 | Managed Identityなど明示的な資格情報を使う |
| ローカル開発 | Azure CLI認証と本番認証を分ける |
| シークレット | .envやローカル設定を本番へ持ち込まない |
| 権限 | エージェント実行に必要な最小権限だけを付与 |
| 監査 | 誰が、どのエージェントを、どの権限で実行したか記録 |
プレビュー・実験的機能は用途を限定する
Tools Overviewでは、一部のツールがpreviewやexperimentalとして整理されています。例えば、Bing Grounding、Bing Custom Search、Azure AI Search、SharePoint、Microsoft Fabric、Memory Search、Computer Use、Browser Automation、A2A toolなど、利用できる機能は増えていますが、状態がpreviewやexperimentalのものも含まれます。(Microsoft Learn)
プレビュー機能を本番で使う場合は、次のようなガードレールを置くべきです。
| リスク | 対策 |
|---|---|
| APIや仕様が変わる | バージョン固定、変更検知、検証環境での先行テスト |
| 管理画面やドキュメントが変わる | 運用手順を定期更新 |
| コンプライアンス境界が変わる | データ送信先とリージョンを確認 |
| 予期せぬ操作が発生する | 承認フロー、サンドボックス、操作ログを必須化 |
特にWeb検索系やグラウンディング系ツールは、データが外部に送信される可能性があります。Foundryの公式情報でも、Bing系のWeb groundingは検索データがAzureのコンプライアンス境界外へ送信される旨が説明されています。(Microsoft Learn)
失敗しやすいポイントと回避策
Agent Pipeline Architectureを導入する際、設計でつまずきやすいのは「機能をどこに置くか」の判断です。
| 失敗例 | 起きる問題 | 回避策 |
|---|---|---|
| すべてをAgent middlewareに入れる | RAG、ログ、承認、変換が混ざり保守しにくい | 横断制御はAgent middleware、文脈追加はContext Providersへ分ける |
| Chat middlewareで重い処理をする | ツール呼び出しループで何度も動き遅くなる | モデル呼び出し単位で必要な処理だけに限定する |
| Foundry Agentをコード管理の延長で扱う | 実行時にツールや指示を変えられず詰まる | Foundry側定義とコード側定義の責務を分ける |
| GitHub Copilot Agentに広い権限を与える | ファイル操作やシェル実行の影響範囲が大きくなる | コンテナ化、許可制、監査ログを必須にする |
| 可観測性を全層で有効化する | プロンプトや応答が重複記録される | 記録する層と機密データの扱いを決める |
| プレビュー機能を無条件で本番投入する | 仕様変更や運用トラブルが起きやすい | 検証環境、代替手段、ロールバック手順を用意する |
実務では、最初から複雑なマルチエージェント構成にするより、1つのエージェントで「入力検証」「履歴管理」「ツール承認」「ログ」の最小構成を作り、パイプライン上のどこで何が動いているかを確認する方が安全です。
管理者・開発者向けチェックリスト
最後に、Microsoft Agent FrameworkのAgent Pipeline Architectureを確認する際のチェックリストをまとめます。
管理者向け
| チェック項目 | 確認内容 |
|---|---|
| エージェント種別 | ChatClientAgent、FoundryAgent、GitHubCopilotAgent、CopilotStudioAgentのどれか |
| 実行環境 | ローカル、コンテナ、Foundry、GitHub Copilot CLI、外部A2A先 |
| 権限 | ファイル、シェル、URL取得、MCP、外部APIの許可範囲 |
| 承認 | ツール実行前に人間の承認が必要な操作を定義 |
| ログ | 入力、出力、ツール呼び出し、承認結果、エラーをどこまで残すか |
| データ境界 | Web検索、Bing grounding、SharePoint、Fabric連携時の送信先 |
| バージョン管理 | Foundry Agentや依存パッケージのバージョン固定 |
| 本番認証 | Managed Identityなど本番向け資格情報の利用 |
開発者向け
| チェック項目 | 確認内容 |
|---|---|
| ミドルウェア設計 | Agent、Function、Chatのどこに置くべき処理か |
| Context Providers | 履歴、RAG、メモリ、動的指示を適切に分離しているか |
| ツール定義 | Function Tools、MCP、Hosted Toolsの対応プロバイダーを確認したか |
| ストリーミング | 非ストリーミングとストリーミングの両方で動作確認したか |
| Python移行 | model、contents、パッケージ分割、Foundry namespaceを確認したか |
| 例外処理 | ツール失敗、モデル失敗、承認拒否、タイムアウトを処理しているか |
| テスト | ミドルウェアの実行順序、ツール承認、監査ログをテストしているか |
| コスト | Chat middlewareやツールループで不要なモデル呼び出しが増えていないか |
まず何から対応すべきか
Agent Pipeline Architectureは、Microsoft Agent FrameworkでAIエージェントを安全に拡張するための設計図です。まずは、自社または自分のプロジェクトで使っているエージェントを一覧化し、「どの層で何をしているか」を書き出してください。
最初に見るべき順番は、次の通りです。
- 使っているエージェント種別を確認する
- ツール、MCP、ファイル操作、シェル実行の有無を確認する
- Agent middleware、Context Providers、Chat middlewareの責務を分ける
- OpenTelemetryや監査ログの記録範囲を決める
- Foundry AgentやGitHub Copilot Agentsを使う場合は、実行環境と権限を確認する
- Pythonやパッケージ構成を移行中なら、1.0.0向けの変更点を洗い出す
MicrosoftのAI/Copilot連携は、単に「高性能なモデルを呼び出す」段階から、業務システム内で安全に動くエージェント基盤へ移っています。Agent Pipeline Architectureを理解しておくことで、開発者は拡張ポイントを間違えにくくなり、管理者は権限、監査、移行、展開のリスクを具体的に管理しやすくなります。
コメント