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](runtime-agui.md).
**Topics**
+ [Persyaratan implementasi protokol](#agui-protocol-implementation-requirements)
+ [Persyaratan kontainer](#agui-container-requirements)
+ [Persyaratan jalur](#agui-path-requirements)
+ [Persyaratan otentikasi](#agui-authentication-requirements)
+ [Penanganan kesalahan](#agui-error-handling)
+ [Tanggapan otentikasi OAuth](#agui-oauth-authentication-responses)
## Persyaratan implementasi protokol
AG-UI Agen Anda harus menerapkan persyaratan protokol khusus ini:
+ **Transport**: Ev Server-Sent ents (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 dengan protokol HTTP)
+ **Platform**: wadah ARM64 - Diperlukan untuk kompatibilitas dengan lingkungan AWS runtime Amazon Bedrock AgentCore
## 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:
+ Streaming tanggapan obrolan
+ Status agen dan langkah berpikir
+ Panggilan alat dan hasil
#### 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](https://docs.ag-ui.com/sdk/js/core/types).
#### 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:
+ 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"
}
```
`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 kapan terakhir diubah. `status`
**Awas**
Jangan `time_of_last_update` mengatur waktu saat ini pada setiap ping. Stempel waktu yang maju pada setiap ping menandakan perubahan status terus menerus, yang mencegah batas waktu sesi idle agar tidak pernah diaktifkan — sesi kemudian bertahan hingga `MaxLifetime` dan dapat menghabiskan kuota sesi Anda. Jika Anda menghilangkan bidang tersebut, platform melacak perubahan status dengan sendirinya. 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
X-Amzn-Bedrock-AgentCore-Runtime-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:
+ **Connection-level kesalahan**: Terjadi sebelum permintaan mencapai wadah Anda (otentikasi, otorisasi, validasi, pembatasan, konflik sesi). Per `RUN_ERROR` istiwa dikembalikan dengan kode status HTTP asli kesalahan (misalnya, 401, 403, atau 409).
+ **Kesalahan runtime**: Terjadi selama eksekusi agen setelah streaming dimulai. Hanya `AGENT_ERROR` termasuk dalam kategori ini. A `RUN_ERROR` cara ini mengembalikan HTTP 200 karena streaming sudah dimulai.
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.
| Kode Kesalahan SSE | Pengecualian Runtime | Kode Kesalahan HTTP | Pesan Kesalahan |
| --- | --- | --- | --- |
| `UNAUTHORIZED` | UnauthorizedException | 401 | Diperlukan otentikasi atau kredentif tidak valid |
| `ACCESS_DENIED` | AccessDeniedException | 403 | Izin tidak memadai untuk operasi yang diminta |
| `VALIDATION_ERROR` | ValidationException | 400 | Data atau parameter permintaan tidak valid |
| `RATE_LIMIT_EXCEEDED` | ThrottlingException | 429 | Terlalu banyak permintaan dari klien |
| `SESSION_BUSY` | ConflictException | 409 | Konflik sumber daya - Sumber daya sudah ada |
| `SESSION_BUSY` | RetryableConflictException | 409 | Operasi sesi sedang berlangsung, silakan coba lagi |
| `SERVICE_QUOTA_EXCEEDED` | ServiceQuotaExceededException | 429 | Kuota layanan terlampaui |
| `AGENT_ERROR` | RuntimeClientError | 200 | Kode agen gagal selama eksekusi - periksa CloudWatch log Anda |
| `INTERNAL_ERROR` | Pengecualian lainnya | 500 | Terjadi kesalahan internal saat memproses permintaan |
`ConflictException`dan `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](https://datatracker.ietf.org/doc/html/rfc7235)) 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.