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

AG-UI kontrak protokol

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

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

Persyaratan implementasi protokol

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

Persyaratan kontainer

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

Persyaratan jalur

/pemanggilan - POST

Tujuan

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

Kasus penggunaan

Titik akhir pemanggilan melayani beberapa tujuan utama:

Format permintaan

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

AG-UI-compliant agen mengharapkan mu RunAgentInput atan JSON. Contoh:

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

Untuk detail RunAgentInput skema lengkap 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"}

/d - WebSocket

Tujuan

Menyediakan komunikasi real-time dua arah antara klien dan agen

Kasus penggunaan

T WebSocket itik akhir melayani beberapa tujuan utama:

/ping - DAPATKAN

Tujuan

Memverifikasi bahwa AG-UI agen 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

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>

Otentikasi SIGv4

Otentikasi AWS SIGv4 standar juga didukung untuk akses terprogram.

Penanganan kesalahan

AG-UI serialisasi setiap kesalahan sebagai RUN_ERROR peristiwa SSE (Content-Type: text/event-stream), apakah kesalahan terjadi sebelum atau selama streaming. Kategori hanya berbeda dalam kode status HTTP yang menyertainya acara:

Tabel berikut memetakan setiap pengecualian runtime AG-UI ke kode kesalahan SSE, kode status HTTP, dan pesan. Beberapa pengecualian berbagi kode kesalahan SSE tetapi mengembalikan pesan yang berbeda, sehingga mereka terdaftar sebagai baris terpisah.

ConflictExceptiondan RetryableConflictException keduanya menggunakan kode SESSION_BUSY kesalahan SSE (HTTP 409) tetapi dibedakan oleh pesan mereka. Layanan mengembalikan RetryableConflictException (Session operation in progress, please retry) ketika operasi kedua mencapai sesi saat layanan menyediakan atau menghancurkan sesi itu. Ini bersifat sementara dan dapat dicoba ulang — coba lagi dengan mundur eksponensial pendek, karena AG-UI klien tidak mencobanya ulang secara otomatis.

Contoh kesalahan runtime (kegagalan agen):

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

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

Contoh kesalahan sesi-sibuk (konflik yang dapat dicoba ulang):

HTTP/1.1 409 Conflict
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"SESSION_BUSY","message":"Session operation in progress, please retry"}

Tanggapan otentikasi OAuth

OAuth-configured agen mengembalikan kesalahan otentikasi dengan kode status HTTP standar. Respons menyertakan 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: 12345678-1234-1234-1234-123456789012

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.