Agent2Agent 入門 (8) - 拡張機能

「Agent2Agent」の「エクステンション」についてまとめました。

前回

1. はじめに

「A2A」は、エージェント間の通信を可能にする堅固な基盤です。しかしながら、一部ドメインでは、プロトコルの汎用メソッドが提供する以上の構造が必要となることは明らかです。こうしたケースをサポートするために、プロトコルに「拡張機能」が追加されています。「拡張機能」を使用することで、エージェントとクライアントは、コアプロトコルの上に重ねる追加のカスタムロジックをネゴシエートできます。

2. 拡張機能の適用範囲

「拡張機能」の具体的な使用方法は、意図的に定義されていません。これは、「拡張機能」を使用することで、現在知られているユースケース以外にも「A2A」を拡張できるようにするためです。ただし、以下のようなユースケースは明確に予測可能です。

「拡張機能」では許可されないプロトコルの変更がいくつかあります。以下がその例です。

これらの制限は、「拡張機能」によってクライアントとエージェントが実行するコアタイプ検証が壊れるのを防ぐために存在します。

3. 拡張機能の宣言

3-1. 拡張機能の宣言

エージェントは、AgentCapabilities オブジェクトに AgentExtension オブジェクトを含めることで、AgentCard 内で拡張機能のサポートを宣言します。

・拡張機能を表示する AgentCard の例

{
    "name": "Magic 8-ball",
    "description": "An agent that can tell your future... maybe.",
    "version": "0.1.0",
    "url": "https://example.com/agents/eightball",
    "capabilities": {
        "streaming": true,
        "extensions": [
            {
                "uri": "https://example.com/ext/konami-code/v1",
                "description": "Provide cheat codes to unlock new fortunes",
                "required": false,
                "params": {
                    "hints": [
                        "When your sims need extra cash fast",
                        "You might deny it, but we've seen the evidence of those cows."
                    ]
                }
            }
        ]
    },
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/plain"],
    "skills": [
        {
            "id": "fortune",
            "name": "Fortune teller",
            "description": "Seek advice from the mystical magic 8-ball",
            "tags": ["mystical", "untrustworthy"]
        }
    ]
}

3-2. 必須拡張機能

「拡張機能」は追加機能を実現する手段ですが、一部のエージェントはコアA2Aプロトコルで表現可能な要件よりも厳しい要件を持つことが予想されます。例えば、エージェントはすべての受信メッセージに作成者による暗号署名を要求する場合があります。必須と宣言された拡張機能は、このようなユースケースをサポートすることを目的としています。

「AgentCard」が必須拡張機能を宣言した場合、これはクライアントに対して、拡張機能の一部がリクエストの構造化に影響を与えることを通知するものです。エージェントへのリクエストの送信方法に直接影響を与えないため、エージェントはデータのみの拡張機能を必須としてマークすべきではありません。

「AgentCard」が必須拡張機能を宣言し、クライアントがその必須拡張機能の有効化を要求しない場合、エージェントは受信リクエストを拒否し、適切なエラーコードを返す必要があります。

クライアントが拡張機能の有効化を要求したが、拡張機能で定義されたプロトコルに従っていない場合、エージェントはリクエストを拒否し、適切な検証失敗メッセージを返す必要があります。

4. 拡張機能仕様

4-1. 拡張機能仕様

拡張機能の詳細は仕様によって定義されます。このドキュメントの正確な形式は規定されていませんが、少なくとも以下の内容が含まれている必要があります。

4-2. 拡張機能の依存関係

拡張機能は他の拡張機能に依存する場合があります。この依存関係は、拡張機能のコア機能が依存する拡張機能がないと実行できない場合は必須、別の拡張機能が存在すると追加機能が有効になる場合はオプションとなります。拡張機能の仕様では、依存関係とその種類を文書化する必要があります。

依存関係は、AgentExtension オブジェクト内ではなく、拡張機能の仕様内で宣言されます。拡張機能の仕様に記載されているすべての必要な依存関係と拡張機能を有効化するのは、クライアントの責任です。

5. 拡張機能のアクティベーション

拡張機能はデフォルトで非アクティブにする必要があります。これにより、「デフォルトがベースライン」のエクスペリエンスが提供され、拡張機能を認識しないクライアントは、拡張機能によって提供される詳細情報やデータに煩わされることはありません。代わりに、クライアントとエージェントは、リクエストに対してどの拡張機能がアクティブであるかを決定するためのネゴシエーションを実行します。このネゴシエーションは、クライアントがエージェントへのHTTPリクエストにX-A2A-Extensionsヘッダーを含めることで開始されます。このヘッダーの値は、クライアントがアクティベートしようとしている拡張機能URIのリストである必要があります。

クライアントは任意の拡張機能のアクティベーションを要求できます。エージェントは、リクエスト内でサポートされている拡張機能を識別し、アクティベーションを実行する責任があります。エージェントがサポートしていない拡張機能が要求された場合は無視できます。

すべての拡張機能がアクティベートできるわけではありません。データのみの拡張機能は、AgentCardを介して追加情報を提供するためだけに存在します。クライアントはこれらの拡張機能のアクティベーションを要求できます。拡張機能はアクティベーション時に追加のロジックを実行しないため、リクエストには影響しません。

一部の拡張機能には、アクティベーションに追加の前提条件がある場合があります。例えば、機密性の高い拡張機能の中には、その拡張機能を有効化できるユーザーを規定するアクセス制御リストが存在する場合があります。要求された拡張機能のうち、どの拡張機能を有効化するかはエージェントが決定します。

クライアントが依存関係のある拡張機能の有効化を要求した場合、そのクライアントは依存関係のある拡張機能の有効化も要求し、その要件を遵守する必要があります。クライアントが要求された拡張機能に必要な依存関係をすべて要求していない場合、サーバーは適切なエラーを返してリクエストを失敗させる可能性があります。

エージェントが有効化されたすべての拡張機能を特定したら、レスポンスには有効化されたすべての拡張機能を識別する X-A2A-Extensions ヘッダーを含める必要があります。

・拡張機能の有効化を示すリクエストの例

POST /agents/eightball HTTP/1.1
Host: example.com
Content-Type: application/json
X-A2A-Extensions: https://example.com/ext/konami-code/v1
Content-Length: 519

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "1",
  "params": {
    "message": {
        "kind": "message",
        "messageId": "1",
        "role": "user",
        "parts": [{"kind": "text", "text": "Oh magic 8-ball, will it rain today?"}]
    },
    "metadata": {
        "https://example.com/ext/konami-code/v1/code": "motherlode",
    }
  }
}

・アクティブ化された拡張機能を反映する対応する応答

HTTP/1.1 200 OK
Content-Type: application/json
X-A2A-Extensions: https://example.com/ext/konami-code/v1
Content-Length: 338

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "kind": "message",
    "messageId": "2",
    "role": "agent",
    "parts": [{"kind": "text", "text": "That's a bingo!"}],
  }
}

6. 実装に関する考慮事項

A2A プロトコルは拡張機能の「内容」を定義しますが、このセクションでは拡張機能の実装の作成、バージョン管理、配布に関するベストプラクティスである「方法」に関するガイダンスを提供します。

6-1. バージョン管理

拡張機能の仕様は必然的に進化します。クライアントとエージェントが互換性のある実装をネゴシエートできるようにするために、明確なバージョン管理戦略を策定することが重要です。

6-2. 発見可能性と公開

拡張機能が有用であるためには、他の開発者がその仕様を見つけ、使い方を理解できる必要があります。

6-3. パッケージングと再利用性

導入を促進するために、拡張機能のロジックは、既存の A2A クライアントおよびサーバーアプリケーションに簡単に統合できる再利用可能なライブラリにパッケージ化する必要があります。

# Hypothetical Python Server Integration
from konami_code_extension import CheatCodeHandler
from a2a.server import A2AServer, DefaultRequestHandler

# The extension hooks into the request handler to process its logic
extension = CheatCodeHandler(description="")
extension.add_cheat(
    code="motherlode",
    hint="When your sims need extra cash fast",
)
extension.add_cheat(
    code="thereisnocowlevel",
    hint="You might deny it, but we've seen the evidence of those cows.",
)
request_handler = DefaultRequestHandler(
    agent_executor=MyAgentExecutor(extension),
    task_store=InMemoryTaskStore(),
    extensions=[extension]
)

server = A2AServer(agent_card, request_handler)
server.run()

6-4. セキュリティ

拡張機能はA2Aプロトコルのコア動作を変更するため、新たなセキュリティ上の考慮事項が生じます。

次回