Memulai streaming dua arah menggunakan WebSocket

Amazon Bedrock AgentCore Runtime memungkinkan Anda menyebarkan agen yang mendukung WebSocket streaming untuk komunikasi dua arah waktu nyata. Panduan ini memandu Anda melalui pembuatan, pengujian, dan penerapan agen streaming dua arah pertama Anda menggunakan. WebSocket

Di bagian ini, Anda belajar:

Untuk informasi lebih lanjut tentang WebSocket protokol, lihat WebSocket RFC 64 55.

Bagaimana AgentCore Runtime mendukung WebSocket koneksi

AgentCore Dukungan Runtime memungkinkan koneksi streaming dua arah yang persisten antara klien dan agen. WebSocket AgentCore Runtime mengharapkan kontainer untuk WebSocket mengimplementasikan titik akhir 8080 pada port di /ws jalur, yang selaras dengan praktik WebSocket server standar.

AgentCore Dukungan Runtime menyediakan kemampuan tanpa server, isolasi sesi, identitas, dan pengamatan yang sama seperti. WebSocket InvokeAgentRuntime Selain itu, ini memungkinkan streaming pesan dua arah latensi rendah, real-time melalui WebSocket koneksi menggunakan otentikasi SigV4 atau OAuth 2.0, menjadikannya ideal untuk aplikasi seperti agen suara percakapan waktu nyata.

Pustaka WebSocket yang didukung

Streaming dua arah menggunakan WebSockets AgentCore Runtime mendukung aplikasi menggunakan pustaka WebSocket bahasa apa pun. Satu-satunya persyaratan adalah klien terhubung ke titik akhir layanan dengan koneksi WebSocket protokol:

wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<agentRuntimeArn>/ws

menggunakan salah satu metode otentikasi yang didukung (header SIGv4, URL pra-tanda tangan SigV4, atau OAuth 2.0) dan bahwa aplikasi agen mengimplementasikan kontrak WebSocket layanan seperti yang ditentukan dalam kontrak protokol HTTP. Kontrak protokol HTTP

Fleksibilitas ini memungkinkan Anda untuk menggunakan WebSocket implementasi pilihan Anda di berbagai bahasa pemrograman dan kerangka kerja, memastikan kompatibilitas dengan basis kode dan alur kerja pengembangan yang ada.

Menggunakan WebSocket dengan AgentCore Runtime

Dalam tutorial memulai ini Anda akan membuat, menguji, dan menerapkan aplikasi agen yang mendukung streaming dua arah menggunakan bedrock-agentcore Python SDK dan CLI untuk penerapan. AgentCore

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Langkah 1: Siapkan proyek dan instal dependensi

Buat folder proyek dan instal paket yang diperlukan:

mkdir agentcore-runtime-quickstart-websocket
cd agentcore-runtime-quickstart-websocket
python3 -m venv .venv
source .venv/bin/activate

Tingkatkan pip ke versi terbaru:

pip install --upgrade pip

Instal paket yang diperlukan berikut:

pip install bedrock-agentcore

Langkah 2: Buat agen streaming dua arah

Buat file sumber untuk kode agen streaming dua arah Anda bernamawebsocket_echo_agent.py. Tambahkan kode berikut:

from bedrock_agentcore import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@app.websocket
async def websocket_handler(websocket, context):
    """Simple echo WebSocket handler."""
    await websocket.accept()

    try:
        data = await websocket.receive_json()
        # Echo back
        await websocket.send_json({"echo": data})
    except Exception as e:
        print(f"Error: {e}")
    finally:
        await websocket.close()

if __name__ == "__main__":
    app.run(log_level="info")

Buat requirements.txt dan tambahkan yang berikut ini:

bedrock-agentcore

Ketergantungan websockets pustaka python disertakan

Memahami kode

Langkah 3: Uji agen streaming dua arah Anda secara lokal

Mulai agen streaming dua arah Anda

Buka jendela terminal dan mulai agen streaming dua arah Anda dengan perintah berikut:

python websocket_echo_agent.py

Anda akan melihat output yang menunjukkan server berjalan pada port 8080.

Uji WebSocket koneksi

Buat WebSocket klien lokal bernamawebsocket_agent_client.py:

import asyncio
import websockets
import json

async def local_websocket():
    uri = "ws://localhost:8080/ws"

    try:
        async with websockets.connect(uri) as websocket:
            # Send a message
            await websocket.send(json.dumps({"inputText": "Hello WebSocket!"}))

            # Receive the echo response
            response = await websocket.recv()
            print(f"Received: {response}")
    except Exception as e:
        print(f"Connection failed: {e}")

if __name__ == "__main__":
    asyncio.run(local_websocket())

Uji agen streaming dua arah Anda secara lokal dengan membuka jendela terminal lain dan menjalankan klien:

python websocket_agent_client.py

Sukses: Anda harus melihat respons sepertiReceived: {"echo":{"inputText":"Hello WebSocket!"}}. Di jendela terminal yang menjalankan agen, masukkan Ctrl+C untuk menghentikan agen.

Langkah 4: Terapkan agen streaming dua arah Anda ke Runtime AgentCore

Instal alat penyebaran

Instal AgentCore CLI:

npm install -g @aws/agentcore

Verifikasi instalasi:

agentcore --version

Untuk perintah dan opsi yang tersedia, lihat referensi AgentCore CLI.

Buat proyek dan terapkan ke AWS

Buat proyek baru untuk agen streaming dua arah Anda:

cd ..
agentcore create --project-name WebSocketProject --no-agent
cd WebSocketProject
agentcore add agent \
  --name WebSocketAgent \
  --type byo \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --protocol HTTP \
  --code-location ../agentcore-runtime-quickstart-websocket \
  --entrypoint websocket_echo_agent.py

Menyebarkan agen Anda:

agentcore deploy

AgentCore Proyek mereferensikan direktori agentcore-runtime-quickstart-websocket sumber yang ada.

Setelah penerapan, Anda akan menerima ARN runtime agen yang terlihat seperti:

arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/websocket_echo_agent-xyz123

Simpan ARN ini karena Anda akan membutuhkannya untuk memanggil agen yang Anda gunakan.

Langkah 5: Panggil agen streaming dua arah yang Anda gunakan

Menyiapkan variabel lingkungan

Siapkan variabel lingkungan yang diperlukan:

Metode autentikasi

T InvokeAgentRuntimeWithWebSocketStream indakan API membuat WebSocket koneksi yang mendukung streaming dua arah antara klien dan agen. Anda dapat mengotentik WebSocket asi koneksi menggunakan metode berikut:

Hubungkan menggunakan header yang ditandatangani SIGv4

Contoh berikut menunjukkan cara membuat WebSocket koneksi dan berkomunikasi dengan runtime agen menggunakan header yang ditandatangani SIGv4:

from bedrock_agentcore.runtime import AgentCoreRuntimeClient
import websockets
import asyncio
import json
import os

async def main():
    # Get runtime ARN from environment variable
    runtime_arn = os.getenv('AGENT_ARN')
    if not runtime_arn:
        raise ValueError("AGENT_ARN environment variable is required")

    # Initialize client
    client = AgentCoreRuntimeClient(region="us-west-2")

    # Generate WebSocket connection with authentication
    ws_url, headers = client.generate_ws_connection(
        runtime_arn=runtime_arn
    )

    try:
        async with websockets.connect(ws_url, additional_headers=headers) as ws:
            # Send message
            await ws.send(json.dumps({"inputText": "Hello!"}))

            # Receive response
            response = await ws.recv()
            print(f"Received: {response}")
    except websockets.exceptions.InvalidStatus as e:
        print(f"WebSocket handshake failed with status code: {e.response.status_code}")
        print(f"Response headers: {e.response.headers}")
        print(f"Response body: {e.response.body.decode()}")
    except Exception as e:
        print(f"Connection failed: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Jalankan klien untuk menguji agen yang Anda gunakan:

python websocket_agent_client_sigv4_headers.py

Sukses: Anda akan melihat respons seperti:

Received: {"echo":{"inputText":"Hello!"}}

Hubungkan menggunakan URL yang telah ditandatangani sebelumnya (SIGv4 melalui parameter kueri)

Contoh berikut menunjukkan cara membuat WebSocket URL dengan parameter kueri SIGv4 dan membuat koneksi:

from bedrock_agentcore.runtime import AgentCoreRuntimeClient
import websockets
import asyncio
import json
import os

async def main():
    runtime_arn = os.getenv('AGENT_ARN')
    if not runtime_arn:
        raise ValueError("AGENT_ARN environment variable is required")

    client = AgentCoreRuntimeClient(region="us-west-2")

    # Generate WebSocket pre-signed URL (with SigV4 via query parameters)
    # wss://...amazonaws.com/runtimes/.../ws?X-Amz-Algorithm=AWS4-HMAC-SHA256
    #   &X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Expires=300
    #   &X-Amz-SignedHeaders=...&X-Amz-Signature=...
    sigv4_url = client.generate_presigned_url(
        runtime_arn=runtime_arn,
        expires=300  # 5 minutes
    )

    try:
        async with websockets.connect(sigv4_url) as ws:
            await ws.send(json.dumps({"inputText": "Hello!"}))
            response = await ws.recv()
            print(f"Received: {response}")
    except websockets.exceptions.InvalidStatus as e:
        print(f"WebSocket handshake failed with status code: {e.response.status_code}")
        print(f"Response headers: {e.response.headers}")
        print(f"Response body: {e.response.body.decode()}")
    except Exception as e:
        print(f"Connection failed: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Jalankan klien untuk menguji agen yang Anda gunakan:

python websocket_agent_client_sigv4_query_parameters.py

Sukses: Anda akan melihat respons seperti:

Received: {"echo":{"inputText":"Hello!"}}

Hubungkan menggunakan OAuth

AgentCore Runtime mendukung otentikasi token OAuth Bearer untuk koneksi. WebSocket Untuk menggunakan otentikasi OAuth, Anda perlu mengonfigurasi runtime agen Anda dengan otorisasi JWT seperti yang dijelaskan di bagian contoh otorisasi masuk JWT dan akses keluar OAuth dari Otentikasi dan otorisasi dengan Auth Masuk dan Auth Keluar.

Setelah Anda menyelesaikan pengaturan OAuth dan memperoleh token pembawa mengikuti Langkah 4: Gunakan token pembawa untuk memanggil agen Anda di panduan OAuth, Anda dapat menggunakan token itu untuk membuat koneksi. WebSocket

Klien Python dengan OAuth

Contoh berikut menunjukkan cara membuat WebSocket koneksi dari Python menggunakan OAuth:

from bedrock_agentcore.runtime import AgentCoreRuntimeClient
import websockets
import asyncio
import json
import os

async def main():
    # Get runtime ARN from environment variable
    runtime_arn = os.getenv('AGENT_ARN')
    if not runtime_arn:
        raise ValueError("AGENT_ARN environment variable is required")

    # Get OAuth bearer token from environment variable
    bearer_token = os.getenv('BEARER_TOKEN')
    if not bearer_token:
        raise ValueError("BEARER_TOKEN environment variable required for OAuth")

    # Initialize client
    client = AgentCoreRuntimeClient(region="us-west-2")

    # Generate WebSocket connection with OAuth
    ws_url, headers = client.generate_ws_connection_oauth(
        runtime_arn=runtime_arn,
        bearer_token=bearer_token
    )

    try:
        async with websockets.connect(ws_url, additional_headers=headers) as ws:
            # Send message
            await ws.send(json.dumps({"inputText": "Hello!"}))

            # Receive response
            response = await ws.recv()
            print(f"Received: {response}")
    except websockets.exceptions.InvalidStatus as e:
        print(f"WebSocket handshake failed with status code: {e.response.status_code}")
        print(f"Response headers: {e.response.headers}")
        print(f"Response body: {e.response.body.decode()}")
    except Exception as e:
        print(f"Connection failed: {e}")

if __name__ == "__main__":
    asyncio.run(main())

Jalankan klien untuk menguji agen yang Anda gunakan:

python websocket_agent_client_oauth.py

Sukses: Anda akan melihat respons seperti:

Received: {"echo":{"inputText":"Hello!"}}

JavaScript Klien browser dengan OAuth

WebSocket API asli browser tidak menyediakan metode untuk mengatur header khusus selama jabat tangan. Untuk mendukung otentikasi OAuth dari browser, AgentCore Runtime menerima token pembawa yang disematkan di Sec-WebSocket-Protocol header selama jabat tangan. WebSocket

Token harus dikodekan base64url dan diawali denganbase64UrlBearerAuthorization., diikuti oleh subprotokol sentinel. base64UrlBearerAuthorization

Contoh berikut menunjukkan cara membuat WebSocket koneksi dari browser JavaScript menggunakan OAuth:

<!DOCTYPE html>
<html>
<body>
    <button onclick="connect()">Connect</button>
    <div id="output"></div>

    <script>
        function connect() {
            const bearerToken = "your_oauth_token_here";
            const runtimeArn = "arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/agent-xyz123";

            // Base64url encode token
            const base64url = btoa(bearerToken)
                .replace(/\+/g, '-')
                .replace(/\//g, '_')
                .replace(/=/g, '');

            const ws = new WebSocket(
                `wss://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/${runtimeArn}/ws`,
                [`base64UrlBearerAuthorization.${base64url}`, "base64UrlBearerAuthorization"]
            );

            ws.onopen = () => ws.send(JSON.stringify({ inputText: "Hello!" }));
            ws.onmessage = (e) => document.getElementById("output").innerText = e.data;
        }
    </script>
</body>
</html>

Manajemen sesi

Menye session_id di X-Amzn-Bedrock-AgentCore-Runtime-Session-Id akan () pada WebSocket koneksi (baik sebagai parameter kueri URL atau header permintaan) merutekan koneksi ke sesi runtime yang terisolasi. Agen dapat mengakses konteks percakapan yang disimpan dalam sesi tersebut, untuk menerapkan kontinuitas percakapan dengan mereferensikan interaksi sebelumnya. ID sesi yang berbeda mengakses konteks terisolasi yang terpisah, memastikan isolasi lengkap antara pengguna atau percakapan.

Untuk manajemen siklus hidup sesi yang komprehensif termasuk pelacakan, pembersihan, dan penanganan kesalahan, lihat Menggunakan sesi terisolasi untuk agen.

Menggunakan sesi dengan WebSocket koneksi

Untuk menggunakan sesi dengan WebSocket koneksi, buat ID sesi unik untuk setiap pengguna atau percakapan dan berikan saat membuat koneksi:

Dengan menggunakan ID sesi yang sama untuk WebSocket koneksi terkait, Anda memastikan bahwa konteks dipertahankan di percakapan yang sama, memungkinkan agen Anda memberikan respons koheren yang dibangun berdasarkan interaksi sebelumnya.

Siklus hidup sesi dengan WebSocket koneksi

Untuk WebSocket koneksi, batas waktu idle sesi diatur ulang setiap kali ada aktivitas pesan antara klien dan agen. Ini termasuk pertukaran WebSocket pesan apa pun seperti mengirim data dari klien ke agen, menerima tanggapan dari agen ke klien, atau WebSocket ping/pong bingkai. Ini berarti bahwa WebSocket percakapan aktif akan menjaga sesi tetap hidup selama pesan terus mengalir, mencegah penghentian sesi prematur selama interaksi yang sedang berlangsung.

Untuk informasi selengkapnya tentang mengonfigurasi setelan siklus hidup, lihat Meng onfigurasi pengaturan AgentCore siklus hidup Amazon Bedrock. Untuk kontrol langsung siklus hidup sesi melalui status kesehatan agen, lihat Manajemen siklus hidup sesi Runtime.

Hentikan sesi runtime

Untuk menghentikan sesi berjalan sebelum sesi yang dapat dikonfigurasi IdleRuntimeSessionTimeout (default pada 15 menit), lihat Menghentikan sesi yang sedang berjalan.

Observabilitas

Amazon Bedrock AgentCore Observability membantu Anda melacak, men-debug, dan memantau agen yang Anda host di Amazon Bedrock Runtime. AgentCore Pertama aktifkan Pencarian CloudWatch Transaksi dengan mengikuti petunjuk di Meng aktifkan pengamatan AgentCore runtime Amazon Bedrock. Untuk mengamati agen Anda, lihat Meli hat data pengamatan untuk agen Amazon Bedrock AgentCore Anda.

Untuk WebSocket koneksi, jejak mewakili sesi koneksi lengkap, bukan pertukaran pesan individual.

Header Kustom

Header khusus memungkinkan Anda meneruskan informasi kontekstual dari aplikasi Anda langsung ke kode agen Anda pada WebSocket koneksi awal. Untuk informasi lengkap tentang dukungan, konfigurasi, dan batasan header kustom, lihat Mener uskan header khusus ke Amazon Bedrock AgentCore Runtime.

Selain itu, header yang diawali dengan X-Amzn-Bedrock-AgentCore-Runtime-Custom- dapat diteruskan sebagai parameter kueri URL dalam WebSocket koneksi.

Misalnya, Anda dapat meneruskan header kustom sebagai parameter kueri di WebSocket URL:

wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<agentRuntimeArn>/ws?X-Amzn-Bedrock-AgentCore-Runtime-Custom-TestHeader=query-param-test-value

Wadah aplikasi agen akan menerima ini sebagai header:

"headers": {
    "x-amzn-bedrock-agentcore-runtime-custom-testheader": "query-param-test-value"
  }

Lampiran

Pertimbangan keamanan

Pemecahan masalah

WebSocket-specific Masalah umum

Berikut ini adalah masalah umum yang mungkin Anda temui:

Penanganan kesalahan

WebSocket kesalahan muncul dalam dua fase, tergantung kapan mereka terjadi.

Pembentukan koneksi (sebelum WebSocket peningkatan)

Membuka koneksi adalah permintaan HTTP standar. Kode status HTTP mencerminkan pengecualian, dan header x-amzn-ErrorType respons membawa nama pengecualian. Layanan dapat mengembalikan salah satu kesalahan berikut sebelum membuat WebSocket koneksi.

Koneksi aktif (setelah WebSocket upgrade)

Setelah ditetapkan, kesalahan dikomunikasikan dengan kode WebSocket tutup standar daripada kode status HTTP. WebSocket Kode penutupan umum meliputi:

WebSocket vs protokol lainnya

Kapan menggunakan WebSocket:

Kapan menggunakan HTTP:

Contoh memulai tambahan

Untuk contoh tambahan menggunakan streaming WebSocket dua arah dengan AgentCore Runtime, lihat contoh streaming WebSocket dua arah: GitHub