# A2A プロトコル契約
A2A プロトコル契約は、Amazon Bedrock AgentCore ランタイムでagent-to-agent通信を実装するための要件を定義します。この契約は、A2A サーバーが実装する必要がある技術要件、エンドポイント、および通信パターンを指定します。
コード例については、[AgentCore ランタイムで A2A サーバーをデプロイする](runtime-a2a.md)」を参照してください。
**Topics**
+ [プロトコル実装要件](#protocol-implementation-requirements)
+ [コンテナの要件](#container-requirements)
+ [パスの要件](#path-requirements)
+ [認証要件](#authentication-requirements)
+ [エラー処理](#error-handling)
+ [OAuth 認証レスポンス](#a2a-oauth-authentication-responses)
## プロトコル実装要件
A2A サーバーは、以下の特定のプロトコル要件を実装する必要があります。
+ **トランスポート**: HTTP 経由の [JSON-RPC 2.0](https://www.jsonrpc.org/specification) - 標準化されたagent-to-agent通信を有効にする
+ **セッション管理**: プラットフォームはセッション分離の`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`ヘッダーを自動的に追加します
+ **エージェント検出**: `/.well-known/agent-card.json`エンドポイントでエージェントカードを指定する必要があります
## コンテナの要件
A2A サーバーは、以下の仕様を満たすコンテナ化されたアプリケーションとしてデプロイする必要があります。
+ **ホスト:** `0.0.0.0`
+ **ポート** : `9000` - A2A サーバー通信用の標準ポート (HTTP および MCP プロトコルとは異なります)
+ **プラットフォーム** : ARM64 コンテナ - AWS Amazon Bedrock AgentCore ランタイム環境との互換性に必要です
## パスの要件
### / - POST
#### 目的
JSON-RPC 2.0 メッセージを受信し、エージェントの機能を通じて処理し、A2A プロトコルメッセージを含む [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) API ペイロードの完全なパススルー
#### ユースケース
ルートエンドポイントには、いくつかの重要な目的があります。
+ Agent-to-agent通信とコラボレーション
+ マルチステップのエージェントワークフローとタスクの委任
+ エージェント間のリアルタイムの会話エクスペリエンス
+ ツールの呼び出しと機能共有
#### リクエストの形式
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 サーバーが動作しており、リクエストを処理する準備ができていることを確認します
#### レスポンスの形式
エージェントの状態を示すステータスコードを返します。
+ **Content-Type:** `application/json`
+ **HTTP ステータスコード**: 異常状態の正常で適切なエラーコード`200`の場合
```
{
"status": "Healthy"
}
```
`status` は必須であり、 `Healthy` または のいずれかです`HealthyBusy`。ステータスが の間`HealthyBusy`、ランタイムセッションは維持されます。
オプション`time_of_last_update`フィールド (Unix タイムスタンプを秒単位で指定) を含めて、`status`最後に変更された日時をレポートできます。
**警告**
すべての ping で現在の時刻`time_of_last_update`に設定しないでください。すべての ping で進行するタイムスタンプは、継続的なステータス変更を示します。これにより、アイドル状態のセッションタイムアウトが発砲されるのを防ぐことができます。その後、セッションは まで保持`MaxLifetime`され、セッションクォータが枯渇する可能性があります。フィールドを省略すると、プラットフォームはステータスの変更を単独で追跡します。Bedrock AgentCore SDK を使用すると、ping レスポンスが自動的に処理されます。
## 認証要件
A2A サーバーは、複数の認証メカニズムをサポートしています。
### OAuth 2.0 ベアラートークン
A2A クライアント認証の場合は、リクエストヘッダーにベアラートークンを含めます。
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### SigV4 認証
Standard AWS SigV4 認証は、プログラムによるアクセスでもサポートされています。
## エラー処理
A2A サーバーは、プロトコルコンプライアンスを維持するために、HTTP 200 ステータスコードを持つ標準の JSON-RPC 2.0 エラーレスポンスとしてエラーを返します。
| JSON-RPC エラーコード | ランタイム例外 | HTTP エラーコード | JSON-RPC エラーメッセージ |
| --- | --- | --- | --- |
| -32501 | ResourceNotFoundException | 404 | リソースが見つかりません - リクエストされたリソースは存在しません |
| -32052 | ValidationException | 400 | 検証エラー - 無効なリクエストデータ |
| -32053 | ThrottlingException | 429 | レート制限を超えました - リクエストが多すぎます |
| -32054 | ResourceConflictException | 409 | リソースの競合 - リソースが既に存在します |
| -32055 | RuntimeClientError | 424 | ランタイムクライアントエラー - 詳細については、CloudWatch ログを確認してください |
エラー応答のサンプル:
```
{
"jsonrpc": "2.0",
"id": "req-001",
"error": {
"code": -32052,
"message": "Validation error - Invalid request data"
}
}
```
## OAuth 認証レスポンス
OAuth 設定のエージェントは、[RFC 6749 (OAuth 2.0) ](https://datatracker.ietf.org/doc/html/rfc6749)認証標準に従います。認証がない場合、サービスは WWW-Authenticate ヘッダー ([RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235) ごと) を含む 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}"
```
**注記**
SigV4-configuredのエージェントは`ACCESS_DENIED`エラーで HTTP 403 を返し、`WWW-Authenticate`ヘッダーは含まれません。