Microsoft Agent Framework - アーキテクチャドキュメント

Posted at 2025-10-25

概要
プロジェクト構造
技術スタック
主要コンポーネント
デザインパターンとアーキテクチャパターン
データフローとコンポーネント間の相互作用
エントリーポイントと主要な実行フロー
設定と依存関係
特筆すべきアーキテクチャ上の決定事項
拡張性とカスタマイズ

概要

Microsoft Agent Frameworkは、AIエージェントの構築、オーケストレーション、デプロイメントのための包括的なマルチ言語フレームワークです。PythonとC#/.NETの両方の実装をサポートし、単純なチャットエージェントから、グラフベースのオーケストレーションを備えた複雑なマルチエージェントワークフローまで、幅広いユースケースに対応しています。

主な特徴

マルチ言語サポート: PythonとC#/.NETで一貫したAPI
グラフベースワークフロー: データフロー、ストリーミング、チェックポイント、ヒューマンインザループ機能を備えたエージェント連携
豊富なLLMプロバイダー対応: OpenAI、Azure OpenAI、Azure AI、Anthropic、OLLaMAなど
組み込みの観測可能性: OpenTelemetryによる分散トレーシングとモニタリング
柔軟なミドルウェアシステム: リクエスト/レスポンス処理のカスタマイズ
Model Context Protocol (MCP)統合: 外部ツールとの標準化された統合

プロジェクト構造

このフレームワークは、マルチ言語モジュラーモノレポとして構成されており、Pythonと.NETの実装が明確に分離されています。

agent-framework/
├── python/                          # Python実装
│   ├── packages/                    # モジュラーパッケージ群
│   │   ├── core/                    # コアエージェントフレームワーク
│   │   ├── azure-ai/               # Azure AI統合
│   │   ├── a2a/                     # Agent-to-Agentプロトコル
│   │   ├── copilotstudio/          # Microsoft Copilot Studio統合
│   │   ├── mem0/                    # メモリ管理
│   │   ├── redis/                   # Redisバックエンド
│   │   ├── devui/                   # 開発者向けUI
│   │   ├── purview/                 # Azure Purview統合
│   │   └── lab/                     # 実験的機能（ベンチマーク、強化学習等）
│   └── samples/                     # サンプルコード
├── dotnet/                          # .NET実装
│   ├── src/                         # .NETソースプロジェクト
│   │   ├── Microsoft.Agents.AI/    # コアライブラリ
│   │   ├── Microsoft.Agents.AI.Workflows/  # ワークフローエンジン
│   │   ├── Microsoft.Agents.AI.OpenAI/     # OpenAI統合
│   │   └── ...                      # その他のプロバイダー実装
│   ├── tests/                       # テストプロジェクト
│   └── samples/                     # サンプルプロジェクト
├── docs/                            # 設計ドキュメントとADR
│   ├── design/                      # 設計ドキュメント
│   ├── decisions/                   # Architecture Decision Records (ADR)
│   └── specs/                       # 仕様書
├── workflow-samples/                # ワークフローの例
└── .github/                         # CI/CD自動化

パッケージ階層（Python）

Pythonパッケージは階層的なティアアーキテクチャで構成されています：

Tier 0（コアコンポーネント）: agent_frameworkから直接インポート可能
- エージェント、ツール、型システム
Tier 1（高度なコンポーネント）:
- コンテキストプロバイダー、ミドルウェア
Tier 2（統合）:
- コネクター、拡張機能、外部サービス統合

この設計により、初心者は単一のpip installで始められ、プロダクション環境では粒度の細かいインストールが可能です。

技術スタック

Python実装

カテゴリ	技術
言語バージョン	Python 3.10+
パッケージマネージャー	UV（モダンなPythonパッケージマネージャー）
コア依存関係	Pydantic 2.x、OpenTelemetry、OpenAI SDK
LLMプロバイダー	OpenAI、Azure OpenAI、Azure AI、Anthropic、OLLaMA、カスタムプロバイダー
観測可能性	OpenTelemetry + Azure Monitor統合
型システム	Pydanticによる完全な型ヒントと検証
プロトコル統合	MCP（Model Context Protocol）

.NET実装

カテゴリ	技術
ターゲット	.NET Standard / C# 12+
ビルドシステム	Visual Studio Solution (.slnx)
パッケージ管理	NuGet
主要ライブラリ	Microsoft.Extensions.AI、Azure SDK
依存性注入	Microsoft.Extensions.DependencyInjection
認証	Azure Identity、Bearer Token Policy

主要コンポーネント

Python コアコンポーネント

1. エージェント（`_agents.py` - 1200+行）

エージェントシステムの中核を担うコンポーネントです。

主要クラス:

AgentProtocol: すべてのエージェントのベースプロトコル
BaseAgent: エージェント実装の抽象基底クラス
ChatAgent: チャットベースエージェントの具象実装

責務:

エージェントのオーケストレーション
ツールの呼び出し管理
ストリーミング応答の処理
会話履歴の管理

例:

from agent_framework import ChatAgent
from agent_framework.azure import AzureOpenAIResponsesClient

agent = AzureOpenAIResponsesClient(...).create_agent(
    name="MyAgent",
    instructions="あなたは親切なアシスタントです。"
)

response = await agent.run("こんにちは！")

2. チャットクライアント（`_clients.py` - 900+行）

LLMバックエンドとの通信を抽象化します。

主要クラス:

ChatClientProtocol: LLMバックエンド用のプロトコル
BaseChatClient: 抽象基底クラス
OpenAI、Azure OpenAI、Azure AI向けの具象実装

責務:

LLMプロバイダーとの通信
リクエスト/レスポンスのシリアライゼーション
ストリーミング応答のサポート
エラーハンドリング

3. 型システム（`_types.py` - 3400+行）

フレームワーク全体で使用される型定義を提供します。

主要な型:

メッセージ型:

ChatMessage: チャットメッセージの表現
ChatResponse: LLMからの応答
ChatResponseUpdate: ストリーミング更新

コンテンツ型:

TextContent: テキストコンテンツ
DataContent: 構造化データ
UriContent: URI参照
FunctionCallContent: 関数呼び出し
ImageContent: 画像データ

応答型:

AgentRunResponse: エージェント実行結果
AgentRunResponseUpdate: ストリーミング更新

特徴:

Pydanticベースの検証
自動シリアライゼーション/デシリアライゼーション
型安全性の保証

4. ツールと関数呼び出し（`_tools.py` - 1700+行）

エージェントが使用できるツールの定義と管理を行います。

主要コンポーネント:

ToolProtocol: ツールのプロトコル定義
AIFunction: AI関数デコレーター
ホストツール:
- HostedCodeInterpreterTool: コード実行
- HostedWebSearchTool: Web検索
- HostedFileSearchTool: ファイル検索
MCP統合によるツール拡張

例:

from agent_framework import AIFunction

@AIFunction
async def get_weather(city: str) -> str:
    """指定された都市の天気を取得します。"""
    # 実装
    return f"{city}の天気は晴れです"

agent = ChatAgent(
    chat_client=...,
    tools=[get_weather]
)

5. ミドルウェアシステム（`_middleware.py` - 1500+行）

リクエスト/レスポンス処理のインターセプトとカスタマイズを可能にします。

ミドルウェアタイプ:

AgentMiddleware: エージェント実行のミドルウェア
ChatMiddleware: チャットクライアントのミドルウェア
FunctionMiddleware: 関数呼び出しのミドルウェア

ユースケース:

ロギングとモニタリング
認証と承認
レート制限
エラーハンドリング
リクエスト/レスポンスの変換

パターン: パイプラインパターン（Chain of Responsibility）

6. ワークフロー（`_workflows/` - 40+ファイル）

グラフベースの複雑なエージェントオーケストレーションを実現します。

コアコンポーネント:

_workflow_builder.py: ワークフローの構築
_workflow_executor.py: ワークフローの実行
_group_chat.py: グループチャットオーケストレーション
_sequential.py: 順次実行
_concurrent.py: 並行実行

状態管理:

_shared_state.py: 共有状態管理
_checkpoint.py: チェックポイント機能
_conversation_state.py: 会話状態管理

グラフ実行:

_edge.py: エッジの定義
_edge_runner.py: エッジ実行ロジック
_runner_context.py: 実行コンテキスト

機能:

チェックポイントによる状態保存
ヒューマンインザループ
ストリーミング対応
ワークフローの可視化
イベント駆動アーキテクチャ

7. メモリとコンテキスト（`_memory.py` - 300+行）

エージェントの実行コンテキストと拡張機能を管理します。

主要クラス:

Context: 実行ごとのコンテキスト
ContextProvider: コンテキスト拡張のプラグインシステム
AggregateContextProvider: 複数プロバイダーの統合

8. スレッドとメッセージストア（`_threads.py` - 600+行）

会話の履歴管理と永続化を担当します。

主要コンポーネント:

AgentThread: スレッドの表現
ChatMessageStoreProtocol: メッセージストレージのプロトコル
永続化ストレージとインメモリストレージのサポート

9. 観測可能性（`observability.py` - 2300+行）

分散トレーシングとメトリクス収集を提供します。

機能:

OpenTelemetry統合
メトリクス収集（トークン使用量、操作時間）
エージェント実行のトレーシング
Azure Monitor エクスポーターサポート

セマンティック規則:

AI固有のスパン属性
標準化されたメトリクス名
ベンダーニュートラルな設計

10. MCP統合（`_mcp.py` - 1300+行）

Model Context Protocolを通じた外部ツール統合を実現します。

サポート機能:

Stdio、HTTP、WebSocketサーバー接続
MCPとAgent Framework間のツール変換
双方向ツール実行

.NET コアコンポーネント

1. AIAgent & 抽象化

主要クラス:

AIAgent: すべてのエージェントの抽象基底クラス
AIAgentMetadata: エージェントのメタデータ
AIContext: エージェント実行のコンテキスト
AgentThread: スレッド管理
ChatMessageStore: メッセージの永続化

2. ワークフローフレームワーク

主要コンポーネント:

WorkflowBuilder: ワークフロー構築のFluent API
Executor & ExecutorIsh: 実行ユニット
イベント駆動実行モデル
関数エグゼキューターとエージェントエグゼキューターのサポート

3. プロバイダー実装

OpenAI統合
Azure OpenAI統合
Azure AI統合
A2A（Agent-to-Agent）プロトコル

4. ホスティング

AIAgentExtensions: DIセットアップ
ASP.NET Coreホスティングサポート
OpenAI固有のホスティング

デザインパターンとアーキテクチャパターン

1. プロトコルベース設計（Python）

概要: @runtime_checkableプロトコルを使用した構造的サブタイピング

メリット:

疎結合
ダックタイピングの活用
柔軟なカスタム実装

例:

from typing import Protocol, runtime_checkable

@runtime_checkable
class ChatClientProtocol(Protocol):
    async def get_response(self, messages: list) -> ChatResponse:
        ...

2. ビルダーパターン

適用箇所:

ワークフロービルダー（Sequential、Concurrent、GroupChat、Handoff）
エージェント設定Fluent API

例:

workflow = Sequential()
    .add_executor(agent1)
    .add_executor(agent2)
    .build()

3. ミドルウェア/パイプラインパターン

概要: リクエストとレスポンスの前処理・後処理

階層:

エージェントミドルウェア
チャットミドルウェア
関数ミドルウェア

パターン: Chain of Responsibility

4. ファクトリーパターン

適用箇所:

異なるプロバイダー用のチャットクライアントファクトリー
関数からのツール生成

5. デコレーターパターン

適用箇所:

観測可能性のためのエージェントとチャットクライアントのラッピング
.NETの拡張メソッド

6. オブザーバー/イベントパターン

適用箇所:

ワークフローイベント（WorkflowEvent、ExecutorEventなど）
ストリーミング応答のための非同期イベントストリーム

7. ストラテジーパターン

適用箇所:

異なるチャットクライアント実装
プロバイダー固有のツール処理
チェックポイントストレージ戦略

8. コンポジションパターン

適用箇所:

コンテキストプロバイダーの組み合わせ
複数ソースからの集約プロバイダー

9. コンテキスト/ステートパターン

適用箇所:

ミドルウェアコンテキスト
状態受け渡しのためのワークフローコンテキスト
ワークフローにおける共有状態

データフローとコンポーネント間の相互作用

エージェント実行フロー

ユーザー入力
    ↓
ミドルウェアパイプライン（前処理）
    ↓
ChatAgent.run() / run_streaming()
    ↓
ツールの検証と登録
    ↓
チャットクライアント（プロバイダー固有）
    ↓
関数呼び出し（ツールコールがある場合）
    ↓
レスポンス処理
    ↓
ミドルウェアパイプライン（後処理）
    ↓
ユーザー出力

ワークフロー実行フロー

Workflow.run() / run_streaming()
    ↓
検証（グラフ接続性、型チェック）
    ↓
ランナーコンテキストのセットアップ
    ↓
エグゼキューターの呼び出し
    ↓
エッジの評価
    ↓
次のエグゼキューターの選択
    ↓
イベント発行
    ↓
チェックポイント（有効な場合）
    ↓
完了/ハンドオフ

ミドルウェアパイプライン

リクエスト
    ↓
Middleware 1 (前処理)
    ↓
Middleware 2 (前処理)
    ↓
    ...
    ↓
コアロジック実行
    ↓
    ...
    ↓
Middleware 2 (後処理)
    ↓
Middleware 1 (後処理)
    ↓
レスポンス

エントリーポイントと主要な実行フロー

Python エントリーポイント

1. シンプルなエージェント

from agent_framework import ChatAgent

agent = ChatAgent(chat_client=...)
response = await agent.run("メッセージ")

2. ワークフロー

from agent_framework.workflows import Workflow

workflow = Workflow()
result = await workflow.run(initial_message)

3. 低レベルチャット

from agent_framework.azure import AzureOpenAIResponsesClient

client = AzureOpenAIResponsesClient(...)
response = await client.get_response(messages)

4. ストリーミング

async for update in agent.run_streaming(message):
    print(update)

.NET エントリーポイント

1. エージェント作成

var agent = chatClient.CreateAIAgent(
    name: "AgentName",
    instructions: "指示内容"
);

2. エージェント実行

var response = await agent.RunAsync(message);

3. ストリーミング

await foreach (var update in agent.RunStreamingAsync(message))
{
    Console.WriteLine(update);
}

設定と依存関係

Python 設定

環境変数:

Azure認証情報
LLMエンドポイントとAPIキー
OpenTelemetry設定

設定ファイル:

.envファイルサポート
Pydantic settingsによる構造化設定
パッケージごとのpyproject.toml設定
ルートレベルの統合設定

依存関係管理:

uvによる高速パッケージ管理
pyproject.tomlによる依存関係宣言
オプショナル依存関係のサポート（extras）

.NET 設定

認証:

Azure Identityライブラリ
Bearer Tokenポリシー
APIキーサポート

設定:

依存性注入コンテナ
appsettings.jsonサポート
ビルダーパターンによるエージェントセットアップ

依存関係管理:

NuGetパッケージマネージャー
.csprojファイルによる依存関係管理

特筆すべきアーキテクチャ上の決定事項

1. 階層化パッケージアーキテクチャ（Python）

設計原則:

Tier 0: コアコンポーネント（エージェント、ツール、型）- 直接インポート
Tier 1: 高度なコンポーネント（コンテキストプロバイダー、ミドルウェア）
Tier 2: 統合（コネクター、拡張機能）

目的:

初心者向け: 単一のpip install
プロダクション向け: 粒度の細かいインストール
依存関係の最小化

2. ネームスペースパッケージ（Lab モジュール）

特徴:

単一PyPIパッケージ（agent-framework-lab）に複数サブモジュール
モジュラーな実験的機能
モノリシックな依存関係を回避

3. プロトコルファースト設計（Python）

利点:

構造的サブタイピングによるカスタム実装の許容
厳格な継承階層の排除
エコシステムの拡張性

例:

@runtime_checkable
class AgentProtocol(Protocol):
    async def run(self, message: str) -> AgentRunResponse:
        ...

4. 統一された応答型

設計:

ストリーミングと非ストリーミングの両方に単一のChatResponseとAgentRunResponse
プライマリコンテンツ（結果）とセカンダリコンテンツ（進捗）の分離
拡張可能なコンテンツ型システム

5. OpenTelemetryネイティブの観測可能性

特徴:

AI用のセマンティック規則を組み込み
カスタムテレメトリーコード不要
ベンダーニュートラルなメトリクスとトレース

メリット:

標準化された計測
複数のバックエンドサポート
業界標準への準拠

6. MCP（Model Context Protocol）統合

機能:

MCP経由の外部ツールのファーストクラスサポート
Stdio、HTTP、WebSocketトランスポート対応
双方向ツール実行

意義:

外部ツールエコシステムとの統合
標準化されたツールプロトコル

7. イベント駆動ワークフロー

設計:

ワークフローは値を返すのではなく、イベントを発行
ストリーミング、チェックポイント、ヒューマンインザループシナリオに対応
グラフベースのDAG実行モデル

利点:

非同期処理
進捗の可視化
柔軟な実行制御

8. チェックポイント/セーブポイントアーキテクチャ

実装:

ファイルベースとインメモリのチェックポイント戦略
ワークフローの再開機能
タイムトラベルデバッグ

ユースケース:

長時間実行ワークフローの再開
デバッグとリプレイ
再現性の保証

9. クロスランゲージ一貫性

原則:

PythonとC#/.NET間でAPIをミラーリング
類似の抽象化とパターン
統一された設計ドキュメント（ADR）

メリット:

学習曲線の短縮
チーム間の知識共有
一貫した開発者体験

10. Agent-to-Agent通信（A2Aプロトコル）

機能:

エージェント間相互作用の構造化プロトコル
ネストされた連携エージェントデプロイメント対応
メッセージベースの通信モデル

ユースケース:

マルチエージェントシステム
階層的エージェントアーキテクチャ
分散エージェント展開

拡張性とカスタマイズ

拡張ポイント

1. カスタムエージェント実装

Python:

from agent_framework import AgentProtocol

class MyCustomAgent:
    async def run(self, message: str) -> AgentRunResponse:
        # カスタム実装
        pass

C#:

public class MyCustomAgent : AIAgent
{
    public override async Task<AgentRunResponse> RunAsync(string message)
    {
        // カスタム実装
    }
}

2. カスタムツール

from agent_framework import AIFunction

@AIFunction
async def custom_tool(param: str) -> str:
    """カスタムツールの説明"""
    return "結果"

3. カスタムミドルウェア

from agent_framework import AgentMiddleware

class MyMiddleware(AgentMiddleware):
    async def on_run(self, context, next):
        # 前処理
        result = await next(context)
        # 後処理
        return result

4. カスタムコンテキストプロバイダー

from agent_framework import ContextProvider

class MyContextProvider(ContextProvider):
    async def get_context(self) -> str:
        return "追加コンテキスト"

5. カスタムチャットクライアント

from agent_framework import ChatClientProtocol

class MyCustomChatClient:
    async def get_response(self, messages) -> ChatResponse:
        # カスタムLLMプロバイダー実装
        pass

その他のアーキテクチャハイライト

レイジーローディング: パッケージ初期化時に遅延読み込みを使用し、依存関係全体のインポートを回避
型安全性: Pythonでの包括的な型ヒント、.NETでの強い型付け
テストフレームワーク: ユニットテストと統合テストの分離されたテストスイート
サンプル構成: 機能ドメインごとに整理（agents、workflows、toolsなど）
ドキュメント: 重要な設計選択のためのArchitecture Decision Records (ADR)
非同期ファースト: Pythonでの完全なasync/awaitサポート、.NETでのTaskベース
シリアライゼーション: エージェント、スレッド、状態の永続化のための自動シリアライゼーション

まとめ

Microsoft Agent Frameworkは、単純なシングルエージェントアプリケーションから、チェックポイント、観測可能性、ヒューマンインザループ機能を備えた複雑なマルチエージェントワークフローまで、幅広いユースケースをサポートする、モジュラーで拡張可能なアーキテクチャを提供しています。

プロトコルベースの設計、階層化パッケージアーキテクチャ、クロスランゲージ一貫性により、開発者は柔軟性を保ちながら、シンプルに始めてエンタープライズレベルの機能にスケールできます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Microsoft Agent Framework - アーキテクチャドキュメント

目次

概要

主な特徴

プロジェクト構造

パッケージ階層（Python）

技術スタック

Python実装

.NET実装

主要コンポーネント

Python コアコンポーネント

1. エージェント（_agents.py - 1200+行）

2. チャットクライアント（_clients.py - 900+行）

3. 型システム（_types.py - 3400+行）

4. ツールと関数呼び出し（_tools.py - 1700+行）

5. ミドルウェアシステム（_middleware.py - 1500+行）

6. ワークフロー（_workflows/ - 40+ファイル）

7. メモリとコンテキスト（_memory.py - 300+行）

8. スレッドとメッセージストア（_threads.py - 600+行）

9. 観測可能性（observability.py - 2300+行）

10. MCP統合（_mcp.py - 1300+行）

.NET コアコンポーネント

1. AIAgent & 抽象化

2. ワークフローフレームワーク

3. プロバイダー実装

4. ホスティング

デザインパターンとアーキテクチャパターン

1. プロトコルベース設計（Python）

2. ビルダーパターン

3. ミドルウェア/パイプラインパターン

4. ファクトリーパターン

5. デコレーターパターン

6. オブザーバー/イベントパターン

7. ストラテジーパターン

8. コンポジションパターン

9. コンテキスト/ステートパターン

データフローとコンポーネント間の相互作用

エージェント実行フロー

ワークフロー実行フロー

ミドルウェアパイプライン

エントリーポイントと主要な実行フロー

Python エントリーポイント

1. シンプルなエージェント

2. ワークフロー

3. 低レベルチャット

4. ストリーミング

.NET エントリーポイント

1. エージェント作成

2. エージェント実行

3. ストリーミング

設定と依存関係

Python 設定

.NET 設定

特筆すべきアーキテクチャ上の決定事項

1. 階層化パッケージアーキテクチャ（Python）

2. ネームスペースパッケージ（Lab モジュール）

3. プロトコルファースト設計（Python）

4. 統一された応答型

5. OpenTelemetryネイティブの観測可能性

6. MCP（Model Context Protocol）統合

7. イベント駆動ワークフロー

8. チェックポイント/セーブポイントアーキテクチャ

9. クロスランゲージ一貫性

10. Agent-to-Agent通信（A2Aプロトコル）

拡張性とカスタマイズ

拡張ポイント

1. カスタムエージェント実装

2. カスタムツール

3. カスタムミドルウェア

4. カスタムコンテキストプロバイダー

5. カスタムチャットクライアント

その他のアーキテクチャハイライト

まとめ

1. エージェント（`_agents.py` - 1200+行）

2. チャットクライアント（`_clients.py` - 900+行）

3. 型システム（`_types.py` - 3400+行）

4. ツールと関数呼び出し（`_tools.py` - 1700+行）

5. ミドルウェアシステム（`_middleware.py` - 1500+行）

6. ワークフロー（`_workflows/` - 40+ファイル）

7. メモリとコンテキスト（`_memory.py` - 300+行）

8. スレッドとメッセージストア（`_threads.py` - 600+行）

9. 観測可能性（`observability.py` - 2300+行）

10. MCP統合（`_mcp.py` - 1300+行）