View a markdown version of this page

AG-UI kontrak protokol - Batuan Dasar Amazon AgentCore
Persyaratan implementasi protokolPersyaratan kontainerPersyaratan jalurPersyaratan otentikasiPenanganan kesalahanTanggapan otentikasi OAuth

AG-UI kontrak protokol

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

Misalnya kode, lihat Menerapkan AG-UI server di AgentCore Runtime.

Persyaratan implementasi protokol

AG-UI Agen Anda harus menerapkan persyaratan protokol khusus ini:

  • Transport: Server-Sent Events (SSE) atau WebSocket - SSE menyediakan streaming searah dari server ke klien, sementara WebSocket memungkinkan komunikasi real-time dua arah

  • Manajemen Sesi: Platform secara otomatis menambahkan X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header untuk isolasi sesi

Persyaratan kontainer

AG-UI Agen Anda harus digunakan sebagai aplikasi kontainer yang memenuhi spesifikasi berikut:

  • Tuan rumah: 0.0.0.0

  • Port: 8080 - Port standar untuk komunikasi AG-UI agen (sama seperti protokol HTTP)

  • Platform: Kontainer ARM64 - Diperlukan untuk kompatibilitas dengan lingkungan AWS runtime Amazon Bedrock AgentCore

Persyaratan jalur

/doa - POST

Tujuan

Menerima permintaan pengguna dan mengalirkan tanggapan sebagai Server-Sent Acara (SSE)

Kasus penggunaan

Titik akhir pemanggilan melayani beberapa tujuan utama:

  • Streaming tanggapan obrolan

  • Status agen dan langkah berpikir

  • Panggilan alat dan hasil

Format permintaan

Amazon Bedrock AgentCore meneruskan payload permintaan langsung ke container Anda tanpa validasi. Untuk menjadi AG-UI-compliant, permintaan Anda harus mengikuti RunAgentInput format. Implementasi container Anda menentukan bidang mana yang diperlukan dan bagaimana kesalahan validasi ditangani.

AG-UI-compliant agen mengharapkan muatan RunAgentInput JSON. Contoh:

{
  "threadId": "thread-123",
  "runId": "run-456",
  "messages": [{"id": "msg-1", "role": "user", "content": "Hello, agent!"}],
  "tools": [],
  "context": [],
  "state": {},
  "forwardedProps": {}
}

Untuk detail lengkap RunAgentInput skema dan format pesan, lihat AG-UI Jenis.

Format respons

AG-UI agen merespons dengan aliran SSE-formatted acara:

Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-789","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-789","delta":"Processing your request"}

data: {"type":"TOOL_CALL_START","toolCallId":"tool-001","toolCallName":"search","parentMessageId":"msg-789"}

data: {"type":"TOOL_CALL_RESULT","messageId":"msg-789","toolCallId":"tool-001","content":"Search completed"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-789"}

data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"}

/ws - WebSocket

Tujuan

Menyediakan komunikasi real-time dua arah antara klien dan agen

Kasus penggunaan

WebSocket Titik akhir melayani beberapa tujuan utama:

  • Real-time antarmuka percakapan

  • Sesi agen interaktif dengan interupsi pengguna

  • Multi-turn percakapan dengan koneksi persisten

/ping - DAPATKAN

Tujuan

Memverifikasi bahwa AG-UI agen Anda beroperasi dan siap menangani permintaan

Format respons

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

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

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

AG-UI agen mendukung beberapa mekanisme otentikasi:

Token Pembawa OAuth 2.0

Untuk otentikasi AG-UI klien, 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

Kesalahan diklasifikasikan menjadi dua kategori berdasarkan kapan terjadi:

  • Connection-level kesalahan: Terjadi sebelum permintaan mencapai penampung Anda (otentikasi, validasi, pelambatan). Ini mengembalikan kode status HTTP standar.

  • Kesalahan runtime: Terjadi selama eksekusi agen setelah streaming dimulai. Ini muncul sebagai RUN_ERROR peristiwa dalam aliran SSE daripada kode status HTTP.

AG-UI Kode Kesalahan Status HTTP Deskripsi

UNAUTHORIZED

401

Otentikasi diperlukan atau kredensi tidak valid

ACCESS_DENIED

403

Izin tidak memadai untuk operasi yang diminta

VALIDATION_ERROR

400

Data atau parameter permintaan tidak valid

RATE_LIMIT_EXCEEDED

429

Terlalu banyak permintaan dari klien

AGENT_ERROR

200

Kode agen gagal selama eksekusi - periksa CloudWatch log Anda

Contoh kesalahan runtime (kegagalan agen):

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

data: {"type":"RUN_ERROR","code":"AGENT_ERROR","message":"Agent execution failed"}

Tanggapan otentikasi OAuth

OAuth-configured agen mengembalikan kesalahan otentikasi dengan kode status HTTP standar. Respons termasuk WWW-Authenticate header (per RFC 7235) untuk penemuan OAuth melalui API. GetRuntimeProtectedResourceMetadata

Contoh kesalahan otentikasi OAuth:

HTTP/1.1 401 Unauthorized
Content-Type: text/event-stream
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
x-amzn-requestid: 8bg30e9c-7e26-6bge-dc4b-75h368cc10cf

data: {"type":"RUN_ERROR","code":"UNAUTHORIZED","message":"Authentication required"}

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