Erste Schritte mit bidirektionalem Streaming mit WebSocket

Mit Amazon Bedrock AgentCore Runtime können Sie Agenten einsetzen, die WebSocket Streaming für bidirektionale Kommunikation in Echtzeit unterstützen. Dieser Leitfaden führt Sie durch die Erstellung, das Testen und die Bereitstellung Ihres ersten bidirektionalen Streaming-Agenten mithilfe von. WebSocket

In diesem Abschnitt lernen Sie:

Weitere Informationen zum WebSocket Protokoll finden Sie unter WebSocket RFC 6455.

Wie AgentCore Runtime Verbindungen unterstützt WebSocket

AgentCore Die WebSocket Unterstützung von Runtime ermöglicht persistente, bidirektionale Streaming-Verbindungen zwischen Clients und Agenten. AgentCore Runtime erwartet, dass Container WebSocket Endpunkte auf dem Port 8080 at the /ws Path implementieren, was den WebSocket Standard-Serverpraktiken entspricht.

AgentCore Die WebSocket Unterstützung von Runtime bietet dieselben serverlosen Funktionen zur Sitzungsisolierung, Identität und Beobachtbarkeit wie. InvokeAgentRuntime Darüber hinaus ermöglicht es bidirektionales Echtzeit-Streaming von Nachrichten mit geringer Latenz über WebSocket Verbindungen mit SigV4- oder OAuth 2.0-Authentifizierung und eignet sich somit ideal für Anwendungen wie Sprachassistenten in Echtzeit.

Unterstützte Bibliotheken WebSocket

Bidirektionales Streaming WebSockets unter AgentCore Runtime unterstützt Anwendungen, die eine beliebige WebSocket Sprachbibliothek verwenden. Die einzigen Voraussetzungen sind, dass Clients über eine WebSocket Protokollverbindung eine Verbindung zum Dienstendpunkt herstellen:

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

unter Verwendung einer der unterstützten Authentifizierungsmethoden (SigV4-Header, vorsignierte SigV4-URL oder OAuth 2.0) und dass die Agentenanwendung den WebSocket Servicevertrag gemäß den Angaben im HTTP-Protokollvertrag implementiert.

Diese Flexibilität ermöglicht es Ihnen, Ihre bevorzugte WebSocket Implementierung in verschiedenen Programmiersprachen und Frameworks zu verwenden und so die Kompatibilität mit bestehenden Codebasen und Entwicklungsabläufen sicherzustellen.

Verwendung mit Runtime WebSocket AgentCore

In diesem Tutorial für die ersten Schritte erstellen, testen und implementieren Sie eine Agentenanwendung, die bidirektionales Streaming unterstützt, indem Sie das Bedrock-agentcore-Python-SDK und die CLI für die AgentCore Bereitstellung verwenden.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

Schritt 1: Projekt einrichten und Abhängigkeiten installieren

Erstellen Sie einen Projektordner und installieren Sie die erforderlichen Pakete:

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

Aktualisieren Sie pip auf die neueste Version:

pip install --upgrade pip

Installieren Sie die folgenden erforderlichen Pakete:

pip install bedrock-agentcore

Schritt 2: Erstellen Sie Ihren bidirektionalen Streaming-Agenten

Erstellen Sie eine Quelldatei für Ihren bidirektionalen Streaming-Agenten mit dem Codenamen. websocket_echo_agent.py Fügen Sie folgenden Code hinzu:

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

Erstellen Sie Folgendes requirements.txt und fügen Sie es hinzu:

bedrock-agentcore

Die websockets Python-Bibliotheksabhängigkeit ist enthalten

Den Code verstehen

Schritt 3: Testen Sie Ihren bidirektionalen Streaming-Agenten lokal

Starten Sie Ihren bidirektionalen Streaming-Agenten

Öffnen Sie ein Terminalfenster und starten Sie Ihren bidirektionalen Streaming-Agenten mit dem folgenden Befehl:

python websocket_echo_agent.py

Sie sollten eine Ausgabe sehen, die darauf hinweist, dass der Server auf Port 8080 läuft.

Verbindung testen WebSocket

Erstellen Sie einen lokalen WebSocket Client mit dem Namenwebsocket_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())

Testen Sie Ihren bidirektionalen Streaming-Agenten lokal, indem Sie ein anderes Terminalfenster öffnen und den Client ausführen:

python websocket_agent_client.py

Erfolgreich: Sie sollten eine Antwort wie Received: {"echo":{"inputText":"Hello WebSocket!"}} sehen. Geben Sie im Terminalfenster, in dem der Agent ausgeführt wird, die Eingabetaste ein, Ctrl+C um den Agenten zu beenden.

Schritt 4: Stellen Sie Ihren bidirektionalen Streaming-Agenten in Runtime bereit AgentCore

Installieren Sie die Bereitstellungstools

Installieren Sie die AgentCore CLI:

npm install -g @aws/agentcore

Installation überprüfen:

agentcore --help

Projekt erstellen und bereitstellen auf AWS

Erstellen Sie ein neues Projekt für Ihren bidirektionalen Streaming-Agenten:

agentcore create

Stellen Sie Ihren Agenten bereit:

agentcore deploy

Nach der Bereitstellung erhalten Sie einen Runtime-ARN für Agenten, der wie folgt aussieht:

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

Speichern Sie diesen ARN, da Sie ihn benötigen, um Ihren bereitgestellten Agenten aufzurufen.

Schritt 5: Rufen Sie Ihren bereitgestellten bidirektionalen Streaming-Agenten auf

Umgebungsvariablen festlegen

Richten Sie die erforderlichen Umgebungsvariablen ein:

Authentifizierungsmethoden

Die InvokeAgentRuntimeWithWebSocketStream API-Aktion stellt eine WebSocket Verbindung her, die bidirektionales Streaming zwischen dem Client und dem Agenten unterstützt. Sie können WebSocket Verbindungen mit den folgenden Methoden authentifizieren:

Connect mit signierten SigV4-Headern her

Das folgende Beispiel zeigt, wie mithilfe von SigV4-signierten Headern eine WebSocket Verbindung hergestellt und mit einer Agenten-Laufzeit kommuniziert wird:

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())

Führen Sie den Client aus, um Ihren bereitgestellten Agenten zu testen:

python websocket_agent_client_sigv4_headers.py

Erfolgreich: Sie sollten eine Antwort wie die folgende sehen:

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

Stellen Sie eine Verbindung über eine vorsignierte URL her (SigV4 über Abfrageparameter)

Das folgende Beispiel zeigt, wie Sie eine WebSocket URL mit SigV4-Abfrageparametern erstellen und eine Verbindung herstellen:

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())

Führen Sie den Client aus, um Ihren bereitgestellten Agenten zu testen:

python websocket_agent_client_sigv4_query_parameters.py

Erfolgreich: Sie sollten eine Antwort wie die folgende sehen:

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

Connect mit OAuth her

AgentCore Runtime unterstützt die Authentifizierung mit OAuth Bearer-Tokens für Verbindungen. WebSocket Um die OAuth-Authentifizierung zu verwenden, müssen Sie Ihre Agenten-Laufzeit mit JWT-Autorisierung konfigurieren, wie im Beispielabschnitt JWT-Autorisierung und ausgehender OAuth-Zugriff unter Authentifizieren und Autorisieren mit eingehender Authentifizierung und ausgehender Authentifizierung beschrieben.

Sobald Sie die OAuth-Einrichtung abgeschlossen und ein Bearer-Token gemäß Schritt 4: Verwenden Sie das Bearer-Token, um Ihren Agenten im OAuth-Handbuch aufzurufen, erhalten haben, können Sie dieses Token verwenden, um WebSocket Verbindungen herzustellen.

Python-Client mit OAuth

Das folgende Beispiel zeigt, wie mit OAuth eine WebSocket Verbindung von Python aus hergestellt wird:

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())

Führen Sie den Client aus, um Ihren bereitgestellten Agenten zu testen:

python websocket_agent_client_oauth.py

Erfolgreich: Sie sollten eine Antwort wie die folgende sehen:

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

JavaScript Browserclient mit OAuth

Die native WebSocket API des Browsers bietet keine Methode zum Festlegen benutzerdefinierter Header während des Handshakes. Um die OAuth-Authentifizierung von Browsern aus zu unterstützen, akzeptiert AgentCore Runtime das beim Handshake in den Header eingebettete Bearer-Token. Sec-WebSocket-Protocol WebSocket

Das Token muss Base64URL-kodiert sein und ein Präfix haben, gefolgt vom Sentinel-Subprotokoll. base64UrlBearerAuthorization. base64UrlBearerAuthorization

Das folgende Beispiel zeigt, wie mithilfe von OAuth eine Verbindung vom Browser aus hergestellt wird: WebSocket JavaScript

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

Verwaltung von Sitzungen

Wenn Sie a session_id (X-Amzn-Bedrock-AgentCore-Runtime-Session-Id) für die WebSocket Verbindung angeben (entweder als URL-Abfrageparameter oder als Anforderungsheader), wird die Verbindung zu einer isolierten Runtime-Sitzung weitergeleitet. Der Agent kann auf den in dieser Sitzung gespeicherten Konversationskontext zugreifen, um die Kontinuität einer Konversation zu gewährleisten, indem er auf frühere Interaktionen verweist. Verschiedene Sitzungs-IDs greifen auf separate isolierte Kontexte zu und sorgen so für eine vollständige Isolierung zwischen Benutzern oder Konversationen.

Eine umfassende Verwaltung des Sitzungslebenszyklus, einschließlich Nachverfolgung, Bereinigung und Fehlerbehandlung, finden Sie unter Isolierte Sitzungen für Agenten verwenden.

Verwenden von Sitzungen mit Verbindungen WebSocket

Um Sitzungen mit WebSocket Verbindungen zu verwenden, generieren Sie für jeden Benutzer oder jede Konversation eine eindeutige Sitzungs-ID und geben Sie diese beim Verbindungsaufbau weiter:

Indem Sie dieselbe Sitzungs-ID für verwandte WebSocket Verbindungen verwenden, stellen Sie sicher, dass der Kontext während derselben Konversation erhalten bleibt, sodass Ihr Agent kohärente Antworten geben kann, die auf früheren Interaktionen aufbauen.

Sitzungslebenszyklus mit WebSocket Verbindungen

Bei WebSocket Verbindungen wird das Leerlauf-Timeout der Sitzung jedes Mal zurückgesetzt, wenn zwischen dem Client und dem Agenten Nachrichtenaktivität besteht. Dies schließt jeden WebSocket Nachrichtenaustausch ein, z. B. das Senden von Daten von Client zu Agent, Empfangen von Antworten von Agent zu Client oder WebSocket ping/pong Frames. Das bedeutet, dass aktive WebSocket Konversationen die Sitzung aufrechterhalten, solange die Nachrichten weiterfließen, wodurch ein vorzeitiger Sitzungsabbruch während laufender Interaktionen verhindert wird.

Weitere Informationen zur Konfiguration der Lebenszykluseinstellungen finden Sie unter AgentCore Lebenszykluseinstellungen von Amazon Bedrock konfigurieren. Eine direktere Steuerung des Sitzungslebenszyklus anhand des Integritätsstatus der Agenten finden Sie unter Runtime-Sitzungslebenszyklusmanagement.

Runtime-Sitzung beenden

Informationen zum Beenden einer laufenden Sitzung vor der konfigurierbaren Sitzung IdleRuntimeSessionTimeout (standardmäßig 15 Minuten) finden Sie unter Beenden einer laufenden Sitzung.

Beobachtbarkeit

Amazon Bedrock AgentCore Observability hilft Ihnen dabei, Agenten, die Sie in Amazon Bedrock Runtime hosten, zu verfolgen, zu debuggen und zu überwachen. AgentCore Aktivieren Sie zunächst die CloudWatch Transaktionssuche, indem Sie den Anweisungen unter Amazon Bedrock AgentCore Runtime Observability aktivieren folgen. Informationen zur Beobachtung Ihres Agenten finden Sie unter Beobachtbarkeitsdaten für Ihre Amazon AgentCore Bedrock-Agenten anzeigen.

Bei WebSocket Verbindungen steht ein Trace für die gesamte Verbindungssitzung und nicht für den Austausch einzelner Nachrichten.

Benutzerdefinierte Header

Mit benutzerdefinierten Headern können Sie bei der ersten Verbindung Kontextinformationen aus Ihrer Anwendung direkt an Ihren Agentencode übergeben. WebSocket Vollständige Informationen zur Unterstützung, Konfiguration und Einschränkungen benutzerdefinierter Header finden Sie unter Übergabe benutzerdefinierter Header an Amazon Bedrock AgentCore Runtime.

Darüber hinaus X-Amzn-Bedrock-AgentCore-Runtime-Custom- können Header mit einem Präfix als URL-Abfrageparameter in Verbindungen übergeben werden. WebSocket

Sie können beispielsweise benutzerdefinierte Header als Abfrageparameter in der URL übergeben: WebSocket

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

Der Container der Agentenanwendung erhält diese als Header:

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

Anhang

Sicherheitsüberlegungen

Fehlerbehebung

Häufig auftretende Probleme WebSocket-specific

Im Folgenden sind häufig auftretende Probleme aufgeführt:

Fehlerbehandlung

WebSocket Verbindungen verwenden standardmäßige Schließcodes für die Fehlerkommunikation. Zu den gängigen Schließcodes gehören:

WebSocket im Vergleich zu anderen Protokollen

Wann sollte verwendet werden WebSocket:

Wann sollte HTTP verwendet werden:

Zusätzliche Beispiele für erste Schritte

Weitere Beispiele für WebSocket bidirektionales Streaming mit AgentCore Runtime finden Sie in den Beispielen für WebSocket bidirektionales Streaming GitHub :