# Kontrak protokol A2A
<a name="runtime-a2a-protocol-contract"></a>

Kontrak protokol A2A mendefinisikan persyaratan untuk menerapkan komunikasi agen-ke-agen di Amazon Bedrock Runtime. AgentCore Kontrak ini menentukan persyaratan teknis, titik akhir, dan pola komunikasi yang harus diterapkan oleh server A2A Anda.

Misalnya kode, lihat [Menerapkan server A2A](runtime-a2a.md) di Runtime. AgentCore 

**Topics**
+ [Persyaratan implementasi protokol](#protocol-implementation-requirements)
+ [Persyaratan kontainer](#container-requirements)
+ [Persyaratan jalur](#path-requirements)
+ [Persyaratan otentikasi](#authentication-requirements)
+ [Penanganan kesalahan](#error-handling)
+ [Tanggapan Otentikasi OAuth](#a2a-oauth-authentication-responses)

## Persyaratan implementasi protokol
<a name="protocol-implementation-requirements"></a>

Server A2A Anda harus menerapkan persyaratan protokol khusus ini:
+  **Transport**: [JSON-RPC 2.0](https://www.jsonrpc.org/specification) melalui HTTP - Mengaktifkan komunikasi agen-ke-agen standar
+  **Manajemen Sesi**: Platform secara otomatis menambahkan `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header untuk isolasi sesi
+  **Penemuan Agen**: Harus menyediakan Kartu Agen di titik `/.well-known/agent-card.json` akhir

## Persyaratan kontainer
<a name="container-requirements"></a>

Server A2A Anda harus digunakan sebagai aplikasi kontainer yang memenuhi spesifikasi berikut:
+  **Tuan rumah**: `0.0.0.0` 
+  **Port**: `9000` - Port standar untuk komunikasi server A2A (berbeda dari protokol HTTP dan MCP)
+  **Platform**: Kontainer ARM64 - Diperlukan untuk kompatibilitas dengan lingkungan AWS runtime Amazon Bedrock AgentCore 

## Persyaratan jalur
<a name="path-requirements"></a>

### /- POSTING
<a name="root-post-endpoint"></a>

#### Tujuan
<a name="root-endpoint-purpose"></a>

Menerima JSON-RPC 2.0 pesan dan memprosesnya melalui kemampuan agen Anda, menyelesaikan pass-through muatan [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)API dengan pesan protokol A2A

#### Kasus penggunaan
<a name="root-endpoint-use-cases"></a>

Titik akhir root melayani beberapa tujuan utama:
+ Agent-to-agent komunikasi dan kolaborasi
+ Multi-step alur kerja agen dan delegasi tugas
+ Real-time pengalaman percakapan antar agen
+ Pemanggilan alat dan berbagi kemampuan

#### Format permintaan
<a name="root-endpoint-request-format"></a>

Server A2A mengharapkan JSON-RPC 2.0 permintaan yang diformat:

```
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"
    }
  }
}
```

#### Format respons
<a name="root-endpoint-response-format"></a>

Server A2A merespons dengan respons berformat JSON-RPC 2.0 yang berisi tugas dan artefak:

```
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- -card.json - DAPATKAN known/agent
<a name="agent-card-endpoint"></a>

#### Tujuan
<a name="agent-card-purpose"></a>

Menyediakan metadata Kartu Agen untuk penemuan agen dan kemampuan iklan

#### Kasus penggunaan
<a name="agent-card-use-cases"></a>

Endpoint Kartu Agen melayani beberapa tujuan utama:
+ Penemuan agen dalam sistem multi-agen
+ Kemampuan dan keterampilan iklan
+ Spesifikasi persyaratan otentikasi
+ Konfigurasi titik akhir layanan

#### Format respons
<a name="agent-card-response-format"></a>

Mengembalikan metadata JSON yang menjelaskan identitas dan kemampuan agen:

```
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 - DAPATKAN
<a name="ping-endpoint"></a>

#### Tujuan
<a name="ping-purpose"></a>

Memverifikasi bahwa server A2A Anda beroperasi dan siap menangani permintaan

#### Format respons
<a name="ping-response-format"></a>

Mengembalikan kode status yang menunjukkan kesehatan agen Anda:
+  **Content-Type** : `application/json` 
+  **Kode Status HTTP**: `200` untuk kode kesalahan yang sehat dan sesuai untuk keadaan tidak sehat

```
{
  "status": "Healthy"
}
```

 `status`diperlukan dan merupakan salah satu dari `Healthy` atau`HealthyBusy`. Sementara statusnya`HealthyBusy`, sesi runtime tetap hidup.

`time_of_last_update`Bidang opsional (stempel waktu Unix dalam hitungan detik) dapat disertakan untuk melaporkan ketika yang terakhir diubah. `status`

**Awas**  
Jangan atur `time_of_last_update` ke waktu saat ini pada setiap ping. Stempel waktu yang maju pada setiap ping menandakan perubahan status berkelanjutan, yang mencegah batas waktu sesi idle tidak pernah diaktifkan — sesi kemudian bertahan hingga `MaxLifetime` dan dapat menghabiskan kuota sesi Anda. Jika Anda menghilangkan bidang, platform melacak perubahan statusnya sendiri. Jika Anda menggunakan Bedrock AgentCore SDK, respons ping ditangani untuk Anda.

## Persyaratan otentikasi
<a name="authentication-requirements"></a>

Server A2A mendukung beberapa mekanisme otentikasi:

### Token Pembawa OAuth 2.0
<a name="oauth-bearer-tokens"></a>

Untuk otentikasi klien A2A, sertakan token Bearer di header permintaan:

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

### SiGv4 Otentikasi
<a name="sigv4-authentication"></a>

Otentikasi AWS SiGv4 standar juga didukung untuk akses terprogram.

## Penanganan kesalahan
<a name="error-handling"></a>

Server A2A mengembalikan kesalahan sebagai respons kesalahan standar JSON-RPC 2.0 dengan kode status HTTP 200 untuk mempertahankan kepatuhan protokol:


| JSON-RPC Kode Kesalahan | Pengecualian Runtime | Kode Kesalahan HTTP | JSON-RPC Pesan Kesalahan | 
| --- | --- | --- | --- | 
| -32501 | ResourceNotFoundException | 404 | Sumber daya tidak ditemukan - Sumber daya yang diminta tidak ada | 
| -32052 | ValidationException | 400 | Kesalahan validasi - Data permintaan tidak valid | 
| -32053 | ThrottlingException | 429 | Batas tarif terlampaui - Terlalu banyak permintaan | 
| -32054 | ResourceConflictException | 409 | Konflik sumber daya - Sumber daya sudah ada | 
| -32055 | RuntimeClientError | 424 | Kesalahan klien runtime - Silakan periksa CloudWatch log Anda untuk informasi lebih lanjut | 

Contoh respon kesalahan:

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

## Tanggapan Otentikasi OAuth
<a name="a2a-oauth-authentication-responses"></a>

OAuth-configured agen mengikuti standar [otentikasi RFC 6749 (OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749)). Ketika otentikasi tidak ada, layanan mengembalikan respons 401 Tidak Sah dengan WWW-Authenticate header (per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), memungkinkan klien menemukan titik akhir server otorisasi melalui API. GetRuntimeProtectedResourceMetadata 

### 401 Tidak Sah - Otentikasi Hilang
<a name="a2a-401-unauthorized"></a>

```
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}"
```

**catatan**  
SigV4-configured agen mengembalikan HTTP 403 dengan `ACCESS_DENIED` kesalahan dan tidak menyertakan `WWW-Authenticate` header.