Memulai dengan 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 penyebaran agen streaming dua arah pertama Anda menggunakan. WebSocket

Di bagian ini, Anda belajar:

Untuk informasi lebih lanjut tentang WebSocket protokol, lihat WebSocket RFC 6455.

Bagaimana AgentCore Runtime mendukung koneksi WebSocket

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

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

WebSocket Pustaka yang didukung

Streaming dua arah menggunakan WebSockets on AgentCore Runtime mendukung aplikasi yang menggunakan perpustakaan bahasa apa pun WebSocket . 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-ditandatangani SigV4, atau OAuth 2.0) dan bahwa aplikasi agen mengimplementasikan kontrak layanan sebagaimana ditentukan dalam kontrak protokol HTTP. WebSocket

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 menyebarkan aplikasi agen yang mendukung streaming dua arah menggunakan SDK Python batuan dasar agentcore 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 Anda

Buat file sumber untuk kode agen streaming dua arah Anda bernama. websocket_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 kodenya

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.

WebSocket Koneksi uji

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

Buat proyek dan terapkan ke AWS

Buat proyek baru untuk agen streaming dua arah Anda:

agentcore create

Menyebarkan agen Anda:

agentcore deploy

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

Mengatur variabel lingkungan

Siapkan variabel lingkungan yang diperlukan:

Metode autentikasi

Tindakan InvokeAgentRuntimeWithWebSocketStream API membuat WebSocket koneksi yang mendukung streaming dua arah antara klien dan agen. Anda dapat mengautentikasi WebSocket koneksi menggunakan metode berikut:

Connect menggunakan header bertanda SiGv4

Contoh berikut menunjukkan cara membuat WebSocket koneksi dan berkomunikasi dengan runtime agen menggunakan header bertanda 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!"}}

Connect menggunakan URL yang telah ditandatangani sebelumnya (SiGv4 melalui parameter kueri)

Contoh berikut menunjukkan cara membuat WebSocket URL dengan parameter query 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!"}}

Connect 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 dalam otorisasi masuk JWT dan bagian sampel akses keluar OAuth dari Otentikasi dan otorisasi dengan Auth Masuk dan Auth Keluar.

Setelah Anda menyelesaikan pengaturan OAuth dan memperoleh token pembawa berikut 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 header selama jabat tangan. Sec-WebSocket-Protocol 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

Menyediakan session_id (X-Amzn-Bedrock-AgentCore-Runtime-Session-Id) 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 itu, untuk menerapkan kontinuitas percakapan dengan merujuk interaksi sebelumnya. ID sesi yang berbeda mengakses konteks terpisah 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 teruskan saat membuat koneksi:

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

Siklus hidup sesi dengan koneksi WebSocket

Untuk WebSocket koneksi, batas waktu idle sesi diatur ulang setiap kali ada aktivitas pesan antara klien dan agen. Ini termasuk pertukaran WebSocket pesan 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 membuat 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 Mengonfigurasi setelan siklus hidup Amazon Bedrock AgentCore . Untuk kontrol lebih langsung atas siklus hidup sesi melalui status kesehatan agen, lihat Manajemen siklus hidup sesi runtime.

Hentikan sesi runtime

Untuk menghentikan sesi berjalan sebelum 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 Penelusuran CloudWatch Transaksi dengan mengikuti petunjuk di Mengaktifkan observabilitas AgentCore runtime Amazon Bedrock. Untuk mengamati agen Anda, lihat Melihat data observabilitas untuk agen Amazon Bedrock AgentCore Anda.

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

Kustom Header

Header khusus memungkinkan Anda meneruskan informasi kontekstual dari aplikasi Anda langsung ke kode agen Anda pada koneksi awal. WebSocket Untuk informasi selengkapnya tentang dukungan, konfigurasi, dan batasan header kustom, lihat Meneruskan 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 khusus 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 koneksi menggunakan kode tutup standar untuk komunikasi kesalahan. Kode tutup 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