A2A プロトコル契約

A2A プロトコル契約は、Amazon Bedrock AgentCore ランタイムでagent-to-agent通信を実装するための要件を定義します。この契約は、A2A サーバーが実装する必要がある技術要件、エンドポイント、および通信パターンを指定します。

コード例については、AgentCore ランタイムで A2A サーバーをデプロイする」を参照してください。

プロトコル実装要件

A2A サーバーは、以下の特定のプロトコル要件を実装する必要があります。

コンテナの要件

A2A サーバーは、以下の仕様を満たすコンテナ化されたアプリケーションとしてデプロイする必要があります。

パスの要件

/ - POST

目的

JSON-RPC 2.0 メッセージを受信し、エージェントの機能を通じて処理し、A2A プロトコルメッセージを含む InvokeAgentRuntime API ペイロードの完全なパススルー

ユースケース

ルートエンドポイントには、いくつかの重要な目的があります。

リクエストの形式

A2A サーバーは、JSON-RPC 2.0 形式のリクエストを想定しています。

Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Your message content here"
        }
      ],
      "messageId": "unique-message-id"
    }
  }
}

レスポンスの形式

A2A サーバーは、タスクとアーティファクトを含む JSON-RPC 2.0 形式のレスポンスで応答します。

Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "artifacts": [
      {
        "artifactId": "unique-artifact-id",
        "name": "agent_response",
        "parts": [
          {
            "kind": "text",
            "text": "Agent response content"
          }
        ]
      }
    ]
  }
}

/.well-known/agent-card.json - GET

目的

エージェント検出と機能アドバタイズのためのエージェントカードメタデータを提供します

ユースケース

エージェントカードエンドポイントには、いくつかの重要な目的があります。

レスポンスの形式

エージェントの ID と機能を説明する JSON メタデータを返します。

Content-Type: application/json
{
  "name": "Agent Name",
  "description": "Agent description and purpose",
  "version": "1.0.0",
  "url": "https://bedrock-agentcore.region.amazonaws.com/runtimes/agent-arn/invocations/",
  "protocolVersion": "0.3.0",
  "preferredTransport": "JSONRPC",
  "capabilities": {
    "streaming": true
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "skill-id",
      "name": "Skill Name",
      "description": "Skill description and capabilities",
      "tags": []
    }
  ]
}

/ping - GET

目的

A2A サーバーが動作しており、リクエストを処理する準備ができていることを確認します

レスポンスの形式

エージェントの状態を示すステータスコードを返します。

{
  "status": "Healthy"
}

status は必須であり、 Healthy または のいずれかですHealthyBusy。ステータスが の間HealthyBusy、ランタイムセッションは維持されます。

オプションtime_of_last_updateフィールド (Unix タイムスタンプを秒単位で指定) を含めて、status最後に変更された日時をレポートできます。

認証要件

A2A サーバーは、複数の認証メカニズムをサポートしています。

OAuth 2.0 ベアラートークン

A2A クライアント認証の場合は、リクエストヘッダーにベアラートークンを含めます。

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

SigV4 認証

Standard AWS SigV4 認証は、プログラムによるアクセスでもサポートされています。

エラー処理

A2A サーバーは、プロトコルコンプライアンスを維持するために、HTTP 200 ステータスコードを持つ標準の JSON-RPC 2.0 エラーレスポンスとしてエラーを返します。

エラー応答のサンプル:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "error": {
    "code": -32052,
    "message": "Validation error - Invalid request data"
  }
}

OAuth 認証レスポンス

OAuth 設定のエージェントは、RFC 6749 (OAuth 2.0) 認証標準に従います。認証がない場合、サービスは WWW-Authenticate ヘッダー (RFC 7235 ごと) を含む 401 Unauthorized レスポンスを返します。これにより、クライアントは GetRuntimeProtectedResourceMetadata API を通じて認可サーバーエンドポイントを検出できます。

401 未承認 - 認証がありません

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"