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

Misalnya kode, lihat Menerapkan server A2A di Runtime. AgentCore

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

Menerima JSON-RPC 2.0 pesan dan memprosesnya melalui kemampuan agen Anda, menyelesaikan pass-through muatan InvokeAgentRuntimeAPI dengan pesan protokol A2A

Kasus penggunaan

Titik akhir root melayani beberapa tujuan utama:

Format permintaan

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

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

Tujuan

Menyediakan metadata Kartu Agen untuk penemuan agen dan kemampuan iklan

Kasus penggunaan

Endpoint 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 ketika yang 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>

SiGv4 Otentikasi

Otentikasi AWS SiGv4 standar juga didukung untuk akses terprogram.

Penanganan kesalahan

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

Contoh respon 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 tidak ada, 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}"