# Kontrak protokol HTTP
<a name="runtime-http-protocol-contract"></a>

Memahami persyaratan untuk menerapkan protokol HTTP dalam aplikasi agen Anda. Gunakan protokol HTTP untuk membuat titik akhir REST API langsung untuk request/response pola tradisional dan WebSocket titik akhir untuk koneksi streaming dua arah waktu nyata.

**catatan**  
Baik titik akhir HTTP WebSocket (`/invocations``/ws`) dan () dapat digunakan pada wadah yang sama menggunakan port 8080, memungkinkan implementasi agen tunggal untuk mendukung interaksi API tradisional dan streaming dua arah waktu nyata.

Misalnya kode, lihat [Memulai dengan AgentCore CLI](runtime-get-started-cli.md).

**Topics**
+ [Persyaratan kontainer](#container-requirements-http)
+ [Persyaratan jalur](#path-requirements-http)
+ [Tanggapan Otentikasi OAuth](#http-oauth-authentication-responses)

## Persyaratan kontainer
<a name="container-requirements-http"></a>

Agen Anda harus digunakan sebagai aplikasi kontainer yang memenuhi spesifikasi berikut:
+  **Tuan rumah**: `0.0.0.0` 
+  **Port**: `8080` - Port standar untuk komunikasi HTTP-based agen
+  **Platform**: kontainer ARM64 - Diperlukan untuk kompatibilitas dengan lingkungan AgentCore Runtime

## Persyaratan jalur
<a name="path-requirements-http"></a>

### /doa - POST
<a name="invocations-endpoint"></a>

Ini adalah titik akhir interaksi agen utama dengan input dan JSON/SSE output JSON.

 **Tujuan** 

Menerima permintaan masuk dari pengguna atau aplikasi dan memprosesnya melalui logika bisnis agen Anda

 **Kasus penggunaan** 

`/invocations`Titik akhir melayani beberapa tujuan utama:
+ Interaksi dan percakapan pengguna langsung
+ Integrasi API dengan sistem eksternal
+ Pemrosesan batch dari beberapa permintaan
+ Real-time tanggapan streaming untuk operasi yang berjalan lama

 **Contoh format Permintaan** 

```
Content-Type: application/json

{
  "prompt": "What's the weather today?"
}
```

 **Format respons** 

Agen Anda dapat merespons menggunakan salah satu format berikut tergantung pada kasus penggunaan:

#### Respons JSON (non-streaming)
<a name="json-response"></a>

 **Tujuan** 

Memberikan tanggapan lengkap untuk permintaan yang dapat diproses dengan cepat

 **Kasus penggunaan** 

Tanggapan JSON ideal untuk:
+ Skenario menjawab pertanyaan sederhana
+ Perhitungan deterministik
+ Pencarian data cepat
+ Konfirmasi status

 **Contoh format respons JSON** 

```
Content-Type: application/json

{
  "response": "Your agent's response here",
  "status": "success"
}
```

#### Respons SSE (streaming)
<a name="sse-response"></a>

Server-sent event (SSE) memungkinkan Anda memberikan respons streaming real-time. Untuk informasi selengkapnya, lihat spesifikasi [Server-sent acara](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events).

 **Tujuan** 

Memungkinkan pengiriman respons tambahan untuk operasi yang berjalan lama dan pengalaman pengguna yang lebih baik

 **Kasus penggunaan** 

Respons SSE ideal untuk:
+ Real-time pengalaman percakapan
+ Pembuatan konten progresif
+ Long-running perhitungan dengan hasil menengah
+ Umpan dan pembaruan data langsung

 **Contoh format respons SSE** 

```
Content-Type: text/event-stream

data: {"event": "partial response 1"}
data: {"event": "partial response 2"}
data: {"event": "final response"}
```

### /ws - WebSocket (Opsional)
<a name="ws-endpoint"></a>

Ini adalah titik akhir WebSocket koneksi utama untuk komunikasi dua arah waktu nyata.

 **Tujuan** 

Menerima permintaan WebSocket peningkatan dan mempertahankan koneksi persisten untuk interaksi agen streaming

 **Kasus penggunaan** 

`/ws`Titik akhir melayani beberapa tujuan utama:
+ Real-time antarmuka percakapan
+ Sesi agen interaktif dengan umpan balik langsung
+ Streaming pemrosesan data dengan komunikasi dua arah

 **Pembentukan koneksi** 

WebSocket koneksi dimulai dengan permintaan pemutakhiran HTTP:

 **Contoh Permintaan Peningkatan HTTP** 

```
GET /ws HTTP/1.1
Host: agent-endpoint
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: session-uuid
```

 **Contoh WebSocket Upgrade Response** 

```
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
```

 **Persyaratan penanganan pesan** 

 WebSocket Titik akhir Anda harus menangani:
+  **Penerimaan koneksi**: Panggilan `await websocket.accept()` untuk membuat koneksi
+  **Penerimaan pesan**: Mendukung jenis teks atau pesan biner berdasarkan kebutuhan aplikasi Anda
+  **Pemrosesan pesan**: Menangani pesan masuk sesuai dengan logika bisnis agen Anda
+  **Pengiriman respons**: Kirim tanggapan yang sesuai menggunakan `send_text()` atau `send_bytes()` 
+  **Siklus hidup koneksi**: Mengelola pembuatan koneksi, pemeliharaan, dan penghentian

#### Format pesan
<a name="websocket-message-formats"></a>

##### Pesan Teks
<a name="websocket-text-messages"></a>

##### Format JSON (Disarankan)
<a name="websocket-json-format"></a>

 **Tujuan** 

Pertukaran data terstruktur untuk interaksi agen

 **Contoh pesan** 

```
{
  "prompt": "Hello, can you help me with this question?",
  "session_id": "session-uuid",
  "message_type": "user_message"
}
```

 **Contoh respon** 

```
{
  "response": "I'd be happy to help you with your question!",
  "session_id": "session-uuid",
  "message_type": "agent_response"
}
```

##### Format Teks Biasa
<a name="websocket-plain-text-format"></a>

 **Tujuan** 

Komunikasi berbasis teks sederhana

 **Contoh** 

```
Hello, can you help me with this question?
```

##### Pesan Biner
<a name="websocket-binary-messages"></a>

 **Tujuan** 

Support untuk data non-teks seperti gambar, audio, atau format biner lainnya

 **Kasus penggunaan** 

Pesan biner mendukung beberapa skenario:
+ Multi-modal interaksi agen
+ Unggahan dan unduhan file
+ Transmisi data terkompresi
+ Data protokol biner

 **Persyaratan penanganan** 

Penanganan pesan biner membutuhkan:
+ Penggunaan `receive_bytes()` dan `send_bytes()` metode
+ Menerapkan pemrosesan data biner yang sesuai
+ Pertimbangkan batasan ukuran pesan

#### Siklus hidup koneksi
<a name="websocket-connection-lifecycle"></a>

##### Pembentukan Koneksi
<a name="websocket-connection-establishment"></a>

1.  **Handshake HTTP**: Klien mengirim permintaan WebSocket peningkatan

1.  **Upgrade Response**: Agen menerima dan mengembalikan 101 Switching Protocols

1.  **WebSocket Aktif**: Komunikasi dua arah dimulai

1.  **Pengikatan Sesi**: Kaitkan koneksi dengan pengenal sesi

##### Pertukaran Pesan
<a name="websocket-message-exchange"></a>

1.  **Continuous Loop**: Menerapkan loop mendengarkan pesan

1.  **Pemrosesan Pesan**: Menangani pesan masuk secara asinkron

1.  **Generasi Respons**: Kirim tanggapan yang sesuai

1.  **Penanganan Kesalahan**: Mengelola pengecualian dan masalah koneksi

### /ping - DAPATKAN
<a name="ping-endpoint"></a>

 **Tujuan** 

Memverifikasi bahwa agen Anda beroperasi dan siap menangani permintaan

 **Kasus penggunaan** 

`/ping`Titik akhir melayani beberapa tujuan utama:
+ Pemantauan layanan untuk mendeteksi dan memperbaiki masalah
+ Pemulihan otomatis melalui infrastruktur AWS terkelola

 **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

Jika agen Anda perlu memproses tugas latar belakang, Anda dapat menunjukkannya dengan `/ping` status. Jika status ping adalah`HealthyBusy`, sesi runtime dianggap aktif.

 **Contoh format respons Ping** 

```
{
  "status": "<status_value>"
}
```

 **status** (wajib)  
 `Healthy`- Sistem siap menerima pekerjaan baru  
 `HealthyBusy`- Sistem beroperasi tetapi saat ini sibuk dengan tugas asinkron. Sementara statusnya`HealthyBusy`, sesi runtime dianggap aktif dan tetap hidup.

 **time\_of\_last\_update** (opsional)  
Stempel waktu Unix (dalam detik) saat terakhir berubah. `status` Setel hanya pada perubahan status yang sebenarnya.  
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.

## Tanggapan Otentikasi OAuth
<a name="http-oauth-authentication-responses"></a>

OAuth-configured agen mengikuti standar [otentikasi RFC 6749 (OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749)). Ketika otentikasi tidak ada, layanan mengembalikan respons 401 Tidak Sah dengan WWW-Authenticate header (per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), memungkinkan klien menemukan titik akhir server otorisasi melalui API. GetRuntimeProtectedResourceMetadata 

### 401 Tidak Sah
<a name="http-401-unauthorized"></a>

Dikembalikan ketika header Otorisasi hilang.

Termasuk WWW-Authenticate header:

```
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```

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