Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Kontrak protokol A2A

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 server A2A Anda.

Misalnya kode, lihat Menye barkan server A2A di AgentCore Runtime.

Persyaratan implementasi protokol

Server A2A Anda harus menerapkan persyaratan protokol khusus ini:

Persyaratan kontainer

Server A2A Anda harus digunakan sebagai aplikasi kontainer yang memenuhi spesifikasi berikut:

Persyaratan jalur

/- POSTING

Tujuan

M JSON-RPC enerima pesan 2.0 dan memprosesnya melalui kemampuan agen Anda, menyelesaikan pass-through payload InvokeAgentRuntime API dengan pesan protokol A2A

Kasus penggunaan

Titik akhir root melayani beberapa tujuan utama:

Format permintaan

Server A2A mengharapkan permintaan JSON-RPC berformat 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"
    }
  }
}

Format respons

Server A2A merespons dengan tanggapan JSON-RPC berformat 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

Tujuan

Menyediakan metadata Kartu Agen untuk penemuan agen dan iklan kemampuan

Kasus penggunaan

Titik akhir Kartu Agen melayani beberapa tujuan utama:

Format respons

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

Tujuan

Memverifikasi bahwa server A2A Anda beroperasi dan siap menangani permintaan

Format respons

Mengembalikan kode status yang menunjukkan kesehatan agen Anda:

{
  "status": "Healthy"
}

statusdiperlukan dan merupakan salah satu dari Healthy atauHealthyBusy. Sementara statusnyaHealthyBusy, sesi runtime tetap hidup.

time_of_last_updateBidang opsional (stempel waktu Unix dalam hitungan detik) dapat disertakan untuk melaporkan kapan terakhir diubah. status

Persyaratan otentikasi

Server A2A mendukung beberapa mekanisme otentikasi:

Token Pembawa OAuth 2.0

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

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

Otentikasi SIGv4

Otentikasi AWS SIGv4 standar juga didukung untuk akses terprogram.

Penanganan kesalahan

Server A2A mengembalikan kesalahan sebagai respons kesalahan JSON-RPC 2.0 standar. Tabel berikut memetakan setiap pengecualian runtime ke kode JSON-RPC kesalahan, kode status HTTP, dan pesan. Beberapa pengecualian berbagi kode JSON-RPC kesalahan tetapi mengembalikan pesan yang berbeda, sehingga mereka terdaftar sebagai baris terpisah.

ConflictExceptiondan RetryableConflictException keduanya menggunakan kode JSON-RPC kesalahan -32054 (HTTP 409). Pesan mereka membedakan mereka. Layanan mengembalikan RetryableConflictException (Session operation in progress, please retry) ketika operasi kedua menargetkan sesi yang disediakan atau dihancurkan oleh layanan. Kondisi ini bersifat sementara dan dapat dicoba kembali. Penelepon harus mencoba lagi dengan mundur eksponensial pendek, karena klien A2A tidak mencobanya ulang secara otomatis.

Contoh respons kesalahan:

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

Tanggapan otentikasi OAuth

OAuth-configured agen mengikuti standar otentikasi RFC 6749 (OAuth 2.0). Ketika otentikasi hilang, layanan mengembalikan respons 401 Tidak Sah dengan WWW-Authenticate header (per RFC 7235), memungkinkan klien menemukan titik akhir server otorisasi melalui API. GetRuntimeProtectedResourceMetadata

401 Tidak Sah - Otentikasi Hilang

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