A2A .NET SDK Comprehensive Documentation

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 コアコンポーネント

1. A2A Core Library: コアプロトコル実装を含む
2. A2A.AspNetCore: ASP.NET Core 統合を提供
3. 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)
}

主要特徴:

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

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 は、タスクライフサイクル管理を担当するコアサーバーサイドコンポーネントです。

主要責任:

1. タスクライフサイクル管理: タスクの作成、更新、キャンセル
2. メッセージ処理: 受信メッセージとタスク更新の処理
3. イベント配信: タスク状態変更イベントの管理
4. ストレージ抽象化: 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 サンプルは、以下を含む複数の異なるタイプのエージェントを作成・デプロイする方法を示します:

1. EchoAgent: シンプルなエコーエージェント
2. EchoAgentWithTasks: タスクサポート付きエコーエージェント
3. HostedClientAgent: ホストされたクライアントエージェント
4. 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 実行手順

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

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

2. サンプルディレクトリに移動:

   cd samples/AgentServer
   

3. プロジェクトの実行:

   dotnet run
   

4. サービス実行の確認: サービスは以下のポートで開始されます:

   • 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 パフォーマンス最適化

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

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 主な利点

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

11.2 使用例

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

11.3 今後の開発

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

11.4 開発推奨事項

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

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