A2A .NET SDK 包括的ドキュメント

1. プロジェクト概要

A2A (Agent2Agent) .NET SDK は、Google の A2A Protocol v0.2.1 を実装する .NET ライブラリで、.NET アプリケーションでエージェント間通信を可能にします。この SDK は ASP.NET Core アプリケーションと連携するよう設計されており、エージェントに A2A サポートを追加する簡単な方法を提供します。

主要機能

プロトコル互換性: A2A Protocol v0.2.1 のほとんどの機能を実装
マルチフレームワークサポート: .NET 9.0、.NET 8.0、.NET Standard 2.0 をサポート
ASP.NET Core 統合: シンプルな統合方法を提供
タスク管理: 標準化されたタスク管理と実行サポート
ストリーミング: リアルタイムストリーミングレスポンスをサポート
OpenTelemetry: 組み込みテレメトリと可観測性サポート

プロジェクトステータス

ライブラリはプロトコル機能のほとんどを実装していますが、一部のシナリオはまだ不完全な場合があります。最大の欠落機能は、プッシュ通知を使用したクライアントコールバックです。

2. A2A .NET Core アーキテクチャ

2.1 プロジェクト構造

src/
├── A2A/                    # コア A2A プロトコル実装
│   ├── Client/            # クライアントコンポーネント
│   ├── JsonRpc/           # JSON-RPC 実装
│   ├── Models/            # データモデル
│   ├── Server/            # サーバーサイドコンポーネント
│   └── openapi.yaml       # API 仕様
└── A2A.AspNetCore/        # ASP.NET Core 統合

2.2 コアコンポーネント

A2A Core Library: コアプロトコル実装を含む
A2A.AspNetCore: ASP.NET Core 統合を提供
Sample Projects: さまざまな使用シナリオを示すサンプルコード

3. A2A .NET クライアント実装

3.1 A2AClient クラス

A2AClient クラスは、エージェントとの通信のためのメインクライアントインターフェースで、IA2AClient インターフェースを実装します。

主要機能:

public class A2AClient : IA2AClient
{
    // メッセージ送信
    public Task<A2AResponse> SendMessageAsync(MessageSendParams taskSendParams)
    
    // タスク取得
    public Task<AgentTask> GetTaskAsync(string taskId)
    
    // タスクキャンセル
    public Task<AgentTask> CancelTaskAsync(TaskIdParams taskIdParams)
    
    // ストリームメッセージ送信
    public async IAsyncEnumerable<SseItem<A2AEvent>> SendMessageStreamAsync(MessageSendParams taskSendParams)
    
    // タスク再購読
    public async IAsyncEnumerable<SseItem<A2AEvent>> ResubscribeToTaskAsync(string taskId)
}

主要特徴:

JSON-RPC 通信: すべての通信は JSON-RPC プロトコルを通じて実行
ストリーミングレスポンス: リアルタイムストリーミングのための Server-Sent Events (SSE) をサポート
シリアライゼーション最適化: 高性能シリアライゼーションのために System.Text.Json ソースジェネレーターを使用
エラーハンドリング: 完全なエラーハンドリングと状態管理

3.2 JsonRpcContent クラス

JSON-RPC リクエスト専用の HTTP コンテンツクラス:

public class JsonRpcContent : HttpContent
{
    public JsonRpcContent(JsonRpcRequest request)
    {
        _request = request;
        Headers.ContentType = new MediaTypeHeaderValue("application/json");
    }
}

3.3 A2ACardResolver クラス

エージェントカード情報の解析と取得に使用:

public class A2ACardResolver
{
    public async Task<AgentCard> GetAgentCardAsync(Uri agentUri)
    public async Task<AgentCard> GetAgentCardAsync(string agentUrl)
}

4. A2A .NET サーバー実装

4.1 TaskManager クラス

TaskManager は、タスクライフサイクル管理を担当するコアサーバーサイドコンポーネントです。

主要責任:

タスクライフサイクル管理: タスクの作成、更新、キャンセル
メッセージ処理: 受信メッセージとタスク更新の処理
イベント配信: タスク状態変更イベントの管理
ストレージ抽象化: ITaskStore インターフェースを通じたタスク永続化

コアメソッド:

public class TaskManager : ITaskManager
{
    // イベントハンドラー
    public Func<MessageSendParams, Task<Message>>? OnMessageReceived { get; set; }
    public Func<AgentTask, Task> OnTaskCreated { get; set; }
    public Func<AgentTask, Task> OnTaskCancelled { get; set; }
    public Func<AgentTask, Task> OnTaskUpdated { get; set; }
    public Func<string, AgentCard> OnAgentCardQuery { get; set; }
    
    // コア操作
    public async Task<AgentTask> CreateTaskAsync(string? contextId = null)
    public async Task<AgentTask?> CancelTaskAsync(TaskIdParams? taskIdParams)
    public async Task<A2AResponse?> SendMessageAsync(MessageSendParams messageSendParams)
    public async Task<IAsyncEnumerable<A2AEvent>> SendMessageStreamAsync(MessageSendParams messageSendParams)
    public async Task UpdateStatusAsync(string taskId, TaskState status, Message? message = null, bool final = false)
    public async Task ReturnArtifactAsync(string taskId, Artifact artifact)
}

4.2 ITaskStore インターフェース

タスクストレージのための抽象インターフェース:

public interface ITaskStore
{
    Task<AgentTask?> GetTaskAsync(string taskId);
    Task SetTaskAsync(AgentTask task);
    Task UpdateStatusAsync(string taskId, TaskState status);
}

4.3 ASP.NET Core 統合

A2A.AspNetCore ライブラリが提供する拡張メソッドを通じて:

// JSON-RPC A2A サポートを追加
app.MapA2A(taskManager, "/echo");

// HTTP A2A サポートを追加
app.MapHttpA2A(taskManager, "/echo");

5. A2A .NET データモデル

5.1 コアモデルクラス

AgentCard - エージェントカード

public class AgentCard
{
    public string Name { get; set; }                    // エージェント名
    public string Description { get; set; }            // エージェント説明
    public string Url { get; set; }                     // エージェント URL
    public AgentProvider? Provider { get; set; }        // プロバイダー情報
    public string Version { get; set; }                 // バージョン情報
    public AgentCapabilities Capabilities { get; set; } // エージェント機能
    public List<AgentSkill> Skills { get; set; }        // エージェントスキル
    public List<string> DefaultInputModes { get; set; } // デフォルト入力モード
    public List<string> DefaultOutputModes { get; set; }// デフォルト出力モード
}

AgentTask - エージェントタスク

public class AgentTask : A2AResponse
{
    public string Id { get; set; }                      // タスク ID
    public string? ContextId { get; set; }              // コンテキスト ID
    public AgentTaskStatus Status { get; set; }         // タスクステータス
    public List<Artifact>? Artifacts { get; set; }      // タスクアーティファクト
    public List<Message>? History { get; set; }         // メッセージ履歴
    public Dictionary<string, JsonElement>? Metadata { get; set; } // メタデータ
}

Message - メッセージ

public class Message : A2AResponse
{
    public MessageRole Role { get; set; }               // メッセージロール (User/Agent)
    public List<Part> Parts { get; set; }               // メッセージパーツ
    public string? MessageId { get; set; }              // メッセージ ID
    public string? TaskId { get; set; }                 // 関連タスク ID
    public string? ContextId { get; set; }              // コンテキスト ID
    public Dictionary<string, JsonElement>? Metadata { get; set; } // メタデータ
}

5.2 タスク状態

public enum TaskState
{
    Submitted,      // 送信済み
    Working,        // 作業中
    InputRequired,  // 入力必要
    Completed,      // 完了
    Canceled,       // キャンセル済み
    Failed,         // 失敗
    Rejected        // 拒否
}

5.3 メッセージパートタイプ

複数のメッセージパートタイプをサポート:

TextPart: テキストコンテンツ
FilePart: ファイルコンテンツ
DataPart: データコンテンツ

6. A2A .NET AgentServer サンプル詳細分析

6.1 プロジェクト概要

AgentServer サンプルは、以下を含む複数の異なるタイプのエージェントを作成・デプロイする方法を示します:

EchoAgent: シンプルなエコーエージェント
EchoAgentWithTasks: タスクサポート付きエコーエージェント
HostedClientAgent: ホストされたクライアントエージェント
ResearcherAgent: リサーチャーエージェント（ステートマシン実装）

6.2 EchoAgent 実装

public class EchoAgent
{
    private ITaskManager? _taskManager;

    public void Attach(TaskManager taskManager)
    {
        _taskManager = taskManager;
        taskManager.OnMessageReceived = ProcessMessage;
        taskManager.OnAgentCardQuery = GetAgentCard;
    }

    public Task<Message> ProcessMessage(MessageSendParams messageSendParams)
    {
        var messageText = messageSendParams.Message.Parts.OfType<TextPart>().First().Text;
        var message = new Message()
        {
            Role = MessageRole.Agent,
            MessageId = Guid.NewGuid().ToString(),
            ContextId = messageSendParams.Message.ContextId,
            Parts = [new TextPart() { Text = $"Echo: {messageText}" }]
        };
        return Task.FromResult(message);
    }
}

6.3 ResearcherAgent 実装

ResearcherAgent はより複雑なステートマシン実装を示します:

public class ResearcherAgent
{
    private enum AgentState
    {
        Planning,                    // 計画フェーズ
        WaitingForFeedbackOnPlan,   // 計画フィードバック待ち
        Researching                 // 研究フェーズ
    }

    public async Task Invoke(string taskId, string message)
    {
        switch (_agentStates[taskId])
        {
            case AgentState.Planning:
                await DoPlanning(taskId, message);
                break;
            case AgentState.WaitingForFeedbackOnPlan:
                if (message == "go ahead")
                    await DoResearch(taskId, message);
                else
                    await DoPlanning(taskId, message);
                break;
            case AgentState.Researching:
                await DoResearch(taskId, message);
                break;
        }
    }
}

7. AgentServer サンプルの実行方法

7.1 環境要件

.NET 9.0 SDK 以上
オプション: OpenTelemetry Collector（テレメトリデータ用）

7.2 実行手順

プロジェクトのクローン:

git clone https://github.com/a2aproject/a2a-dotnet
cd a2a-dotnet

サンプルディレクトリに移動:
```
cd samples/AgentServer
```
プロジェクトの実行:
```
dotnet run
```
サービス実行の確認: サービスは以下のポートで開始されます:
- HTTP: http://localhost:5048
- HTTPS: https://localhost:7014

7.3 利用可能なエンドポイント

/echo - シンプルなエコーエージェント
/echotasks - タスクサポート付きエコーエージェント
/hostedclient - ホストされたクライアントエージェント
/researcher - リサーチャーエージェント

7.4 API 呼び出しのテスト

エージェントカードの取得

curl -X GET http://localhost:5048/echo/.well-known/agent.json

エコーエージェントへのメッセージ送信

curl -X POST http://localhost:5048/echo \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "12345",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello, world!"
          }
        ]
      }
    }
  }'

リサーチャーエージェントタスクの作成

curl -X POST http://localhost:5048/researcher \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "research-1",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Research the current price of butter"
          }
        ]
      }
    }
  }'

8. シーケンス図

8.1 シンプルなメッセージ処理シーケンス図

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant Agent as Agent Implementation
    participant TaskMgr as TaskManager

    Client->>Server: POST /echo (JSON-RPC message/send)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>Agent: OnMessageReceived()
    Agent->>Agent: ProcessMessage()
    Agent-->>TaskMgr: Return Message
    TaskMgr-->>Server: Return A2AResponse
    Server-->>Client: JSON-RPC Response

8.2 タスク処理シーケンス図

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant TaskMgr as TaskManager
    participant Agent as Agent Implementation
    participant Store as TaskStore

    Client->>Server: POST /researcher (message/send)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>TaskMgr: CreateTaskAsync()
    TaskMgr->>Store: SetTaskAsync()
    TaskMgr->>Agent: OnTaskCreated()
    Agent->>Agent: State Change (Planning)
    Agent->>TaskMgr: UpdateStatusAsync(Working)
    TaskMgr->>Store: UpdateStatusAsync()
    Agent->>TaskMgr: ReturnArtifactAsync()
    Agent->>TaskMgr: UpdateStatusAsync(InputRequired)
    TaskMgr-->>Server: Return AgentTask
    Server-->>Client: JSON-RPC Response

    Note over Client,Store: Client sends follow-up message

    Client->>Server: POST /researcher (message/send, taskId)
    Server->>TaskMgr: SendMessageAsync()
    TaskMgr->>Store: GetTaskAsync()
    TaskMgr->>Agent: OnTaskUpdated()
    Agent->>Agent: State processing logic
    Agent->>TaskMgr: UpdateStatusAsync(Completed)
    TaskMgr-->>Server: Return AgentTask
    Server-->>Client: JSON-RPC Response

8.3 ストリーミング処理シーケンス図

sequenceDiagram
    participant Client as Client
    participant Server as A2A Server
    participant TaskMgr as TaskManager
    participant Agent as Agent Implementation

    Client->>Server: POST /echo (JSON-RPC message/stream)
    Server->>TaskMgr: SendMessageStreamAsync()
    TaskMgr->>Agent: OnMessageReceived()
    
    loop Streaming Response
        Agent->>TaskMgr: Generate Event
        TaskMgr->>Server: A2AEvent
        Server->>Client: Server-Sent Event
    end
    
    Agent->>TaskMgr: Complete Processing
    TaskMgr->>Server: End Stream
    Server->>Client: Close Connection

9. A2A .NET 主要設計パターン

9.1 イベント駆動アーキテクチャ

TaskManager はイベント駆動パターンを使用:

OnMessageReceived: 受信メッセージの処理
OnTaskCreated: タスク作成イベント
OnTaskUpdated: タスク更新イベント
OnTaskCancelled: タスクキャンセルイベント

9.2 ストラテジーパターン

異なるエージェント実装は異なる処理戦略を持つことができます:

ステートレス処理 (EchoAgent)
ステートフル処理 (ResearcherAgent)
タスク指向処理 (EchoAgentWithTasks)

9.3 ストレージ抽象化

ITaskStore インターフェースを通じたタスクストレージの抽象化:

InMemoryTaskStore: インメモリストレージ実装
データベースストレージ実装に拡張可能

10. A2A .NET パフォーマンスと可観測性

10.1 パフォーマンス最適化

ソース生成シリアライゼーション: System.Text.Json ソースジェネレーターを使用
AOT 互換性: Native AOT コンパイルをサポート
非同期処理: async/await パターンの包括的使用
ストリーミング処理: 大容量データストリーミングをサポート

10.2 可観測性

統合された OpenTelemetry サポート:

分散トレーシング: ActivitySource 統合
メトリクス収集: タスクステータスとパフォーマンスメトリクス
ログ: 構造化ログサポート

// OpenTelemetry 設定例
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddSource(TaskManager.ActivitySource.Name)
        .AddSource(A2AJsonRpcProcessor.ActivitySource.Name)
        .AddConsoleExporter()
        .AddOtlpExporter());

11. A2A .NET まとめ

A2A .NET SDK は、.NET アプリケーションでエージェント間通信を実装するための完全で本番対応のソリューションを提供します。

11.1 主な利点

標準化されたプロトコル: Google の A2A Protocol 標準に基づく
簡単な統合: シンプルな ASP.NET Core 統合
柔軟なアーキテクチャ: 複数のエージェント実装パターンをサポート
高性能: 最適化されたシリアライゼーションと非同期処理
可観測性: 組み込みテレメトリとモニタリングサポート
拡張性: 抽象インターフェースがカスタム実装をサポート

11.2 使用例

AI エージェントシステム: インテリジェントエージェント相互作用システムの構築
マイクロサービスアーキテクチャ: サービス間のインテリジェント通信
ワークフローエンジン: 複雑なビジネスプロセスのエージェントベース処理
チャットボット: マルチエージェント協調対話システム

11.3 今後の開発

プッシュ通知: 完全なクライアントコールバックサポート
より多くのストレージバックエンド: データベースと分散ストレージサポート
セキュリティ強化: より包括的な認証と認可メカニズム
プロトコル更新: A2A Protocol の最新バージョンとの歩調合わせ

11.4 開発推奨事項

シンプルに始める: 基本概念を理解するために EchoAgent を使用
状態管理の理解: ResearcherAgent のステートマシン実装を研究
エラーハンドリングの重視: 包括的なエラーハンドリングと回復メカニズムの実装
モニタリングとデバッグ: システムモニタリングのために OpenTelemetry を活用
テスト駆動: 包括的な単体テストと統合テストの作成

この SDK は、.NET 開発者に次世代インテリジェントエージェントシステムを構築するための強力で柔軟なプラットフォームを提供します。明確なアーキテクチャと豊富なサンプルを通じて、開発者は迅速に開始し、複雑なエージェント間通信アプリケーションを構築できます。