View a markdown version of this page

Kontrak protokol HTTP - Batuan Dasar Amazon AgentCore
Persyaratan kontainerPersyaratan jalurTanggapan Otentikasi OAuth

Kontrak protokol HTTP

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.

Persyaratan kontainer

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

/doa - POST

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

/invocationsTitik 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)

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)

Server-sent event (SSE) memungkinkan Anda memberikan respons streaming real-time. Untuk informasi selengkapnya, lihat spesifikasi Server-sent acara.

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)

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

/wsTitik 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

Pesan Teks
Format JSON (Disarankan)

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

Tujuan

Komunikasi berbasis teks sederhana

Contoh 

Hello, can you help me with this question?
Pesan Biner

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

Pembentukan Koneksi

  1. Handshake HTTP: Klien mengirim permintaan WebSocket peningkatan

  2. Upgrade Response: Agen menerima dan mengembalikan 101 Switching Protocols

  3. WebSocket Aktif: Komunikasi dua arah dimulai

  4. Pengikatan Sesi: Kaitkan koneksi dengan pengenal sesi

Pertukaran Pesan

  1. Continuous Loop: Menerapkan loop mendengarkan pesan

  2. Pemrosesan Pesan: Menangani pesan masuk secara asinkron

  3. Generasi Respons: Kirim tanggapan yang sesuai

  4. Penanganan Kesalahan: Mengelola pengecualian dan masalah koneksi

/ping - DAPATKAN

Tujuan

Memverifikasi bahwa agen Anda beroperasi dan siap menangani permintaan

Kasus penggunaan

/pingTitik 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 adalahHealthyBusy, 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 statusnyaHealthyBusy, 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.

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.

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

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.