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

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 titik akhir untuk WebSocket koneksi 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:

Persyaratan jalur

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

T /invocations itik akhir melayani beberapa tujuan utama:

Contoh format Permintaan

Content-Type: application/json

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

Format tanggapan

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

Respon JSON (non-streaming)

Tujuan

Memberikan tanggapan lengkap untuk permintaan yang dapat diproses dengan cepat

Kasus penggunaan

Tanggapan JSON ideal untuk:

Contoh format respons JSON

Content-Type: application/json

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

Respon SSE (streaming)

Server-sent Events (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

Tanggapan SSE ideal untuk:

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

M WebSocket enerima permintaan peningkatan dan mempertahankan koneksi persisten untuk interaksi agen streaming

Kasus penggunaan

T /ws itik akhir melayani beberapa tujuan utama:

Pembentukan koneksi

WebSocket koneksi dimulai dengan permintaan peningkatan HTTP:

Contoh Permintaan Upgrade 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 Resp WebSocket ons Upgrade

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

Persyaratan penanganan pesan

Titik WebSocket akhir Anda harus menangani:

Format pesan

Pesan Teks

Format JSON (Direkomendasikan)

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 tanggapan

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

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

Kasus penggunaan

Pesan biner mendukung beberapa skenario:

Persyaratan penanganan

Penanganan pesan biner membutuhkan:

Siklus hidup koneksi

Pembentukan Koneksi

Pertukaran Pesan

/ping - DAPATKAN

Tujuan

Memverifikasi bahwa agen Anda beroperasi dan siap menangani permintaan

Kasus penggunaan

T /ping itik akhir melayani beberapa tujuan utama:

Format tanggapan

Mengembalikan kode status yang menunjukkan kesehatan agen Anda:

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

Penanganan kesalahan

Tidak seperti A2A, MCP, dan AG-UI protokol, protokol HTTP tidak membungkus kesalahan dalam amplop khusus protokol. Layanan mengembalikan kesalahan secara langsung sebagai respons HTTP asli: kode status HTTP mencerminkan pengecualian, dan header x-amzn-ErrorType respons membawa nama pengecualian. Tabel berikut mencantumkan pengecualian yang dapat Anda terima.

ConflictExceptiondan RetryableConflictException keduanya mengembalikan HTTP 409. x-amzn-ErrorTypeHeader dan pesan membedakannya. Layanan mengembalikan RetryableConflictException (Session operation in progress, please retry) ketika operasi kedua menargetkan sesi yang disediakan atau dihancurkan oleh layanan. Kondisi ini bersifat sementara dan dapat dicoba kembali. Coba lagi dengan mundur eksponensial pendek. SDK AWS mencoba ulang pengecualian ini secara otomatis saat percobaan ulang default diaktifkan. Jika Anda memanggil API secara langsung tanpa AWS SDK, Anda harus mencobanya lagi sendiri.

Tanggapan otentikasi OAuth

OAuth-configured agen mengikuti standar otentikasi RFC 6749 (OAuth 2.0). Ketika otentikasi hilang, 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}"