# Erste Schritte mit bidirektionalem Streaming mit WebSocket
<a name="runtime-get-started-websocket"></a>

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:
+ Wie AgentCore Runtime Verbindungen unterstützt WebSocket 
+ Wie erstellt man eine Agentenanwendung mit bidirektionalen Streaming-Funktionen
+ Wie testen Sie Ihren Agenten lokal
+ Wie setzen Sie Ihren Agenten ein AWS 
+ Wie rufen Sie Ihren eingesetzten Agenten auf
+ Wie verwendet man Sitzungen mit Verbindungen WebSocket 

Weitere Informationen zum WebSocket Protokoll finden Sie unter [WebSocket RFC 6455](https://tools.ietf.org/html/rfc6455).

**Topics**
+ [Wie AgentCore Runtime Verbindungen unterstützt WebSocket](#websocket-support-overview)
+ [Verwendung mit Runtime WebSocket AgentCore](#using-websocket-with-runtime)
+ [Verwaltung von Sitzungen](#websocket-session-management)
+ [Beobachtbarkeit](#websocket-observability)
+ [Benutzerdefinierte Header](#websocket-custom-headers)
+ [Anhang](#websocket-appendix)

## Wie AgentCore Runtime Verbindungen unterstützt WebSocket
<a name="websocket-support-overview"></a>

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
<a name="websocket-supported-libraries"></a>

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.](runtime-http-protocol-contract.md)

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
<a name="using-websocket-with-runtime"></a>

**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.**

**Topics**
+ [Voraussetzungen](#websocket-prerequisites)
+ [Schritt 1: Projekt einrichten und Abhängigkeiten installieren](#setup-websocket-project)
+ [Schritt 2: Erstellen Sie Ihren bidirektionalen Streaming-Agenten](#create-websocket-agent)
+ [Schritt 3: Testen Sie Ihren bidirektionalen Streaming-Agenten lokal](#step-2-test-websocket-locally)
+ [Schritt 4: Stellen Sie Ihren bidirektionalen Streaming-Agenten in Runtime bereit AgentCore](#step-3-deploy-websocket-to-aws)
+ [Schritt 5: Rufen Sie Ihren bereitgestellten bidirektionalen Streaming-Agenten auf](#step-4-invoke-deployed-websocket)

### Voraussetzungen
<a name="websocket-prerequisites"></a>

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:
+  ** AWS Konto** mit konfigurierten Anmeldeinformationen. Informationen zur Konfiguration Ihrer AWS Anmeldeinformationen finden Sie unter [Konfiguration und Einstellungen für Anmeldeinformationsdateien in der AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). 
+  **Python 3.10\+ installiert**
+  ** AWS Berechtigungen**: Um einen Agenten mit der AgentCore CLI zu erstellen und bereitzustellen, benötigen Sie die entsprechenden Berechtigungen. Weitere Informationen finden Sie unter [Verwenden der AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli).

### Schritt 1: Projekt einrichten und Abhängigkeiten installieren
<a name="setup-websocket-project"></a>

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:
+  **bedrock-agentcore** — Das Amazon Bedrock AgentCore SDK zum Erstellen von KI-Agenten, die `websockets` Python-Bibliotheksabhängigkeit ist enthalten

```
pip install bedrock-agentcore
```

### Schritt 2: Erstellen Sie Ihren bidirektionalen Streaming-Agenten
<a name="create-websocket-agent"></a>

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

#### Implementierung eines bidirektionalen Streaming-Agents (websocket\_echo\_agent.py)
<a name="websocket-agent-code"></a>

```
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
<a name="understanding-websocket-code"></a>
+  **BedrockAgentCoreApp**: Erstellt eine Agentenanwendung, die Starlette für die Bereitstellung von KI-Agenten erweitert und Funktionen für WebSocket Support, HTTP-Routing, Middleware und Ausnahmebehandlung bereitstellt
+  **WebSocket Decorator**: Der `@app.websocket` Decorator verarbeitet automatisch Verbindungen am Pfad auf Port 8080 `/ws`
+  **Echo Logic**: Sendet empfangene Daten zurück mit `{"echo": data}` 
+  **Fehlerbehandlung**: Verwendet die Struktur try/except /finally, um eine korrekte Fehlerprotokollierung und ein ordnungsgemäßes Schließen der Verbindung sicherzustellen.

### Schritt 3: Testen Sie Ihren bidirektionalen Streaming-Agenten lokal
<a name="step-2-test-websocket-locally"></a>

#### Starten Sie Ihren bidirektionalen Streaming-Agenten
<a name="start-websocket-server"></a>

Ö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
<a name="test-websocket-connection"></a>

Erstellen Sie einen lokalen WebSocket Client mit dem Namen`websocket_agent_client.py`:

##### Lokaler WebSocket Client (websocket\_agent\_client.py)
<a name="websocket-test-client"></a>

```
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
<a name="step-3-deploy-websocket-to-aws"></a>

#### Installieren Sie die Bereitstellungstools
<a name="install-deployment-tools"></a>

Installieren Sie die AgentCore CLI:

```
npm install -g @aws/agentcore
```

Installation überprüfen:

```
agentcore --help
```

#### Projekt erstellen und bereitstellen auf AWS
<a name="configure-and-deploy"></a>

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

```
agentcore create
```

Stellen Sie Ihren Agenten bereit:

```
agentcore deploy
```

**Anmerkung**  
Führen Sie diese Befehle in Ihrem Projektverzeichnis (`agentcore-runtime-quickstart-websocket`) aus, in dem sich Ihre Agentendateien befinden.

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
<a name="step-4-invoke-deployed-websocket"></a>

#### Umgebungsvariablen festlegen
<a name="setup-environment-variables"></a>

Richten Sie die erforderlichen Umgebungsvariablen ein:

1. Exportieren Sie Ihren Agenten-ARN:

   ```
   export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:accountId:runtime/websocket_echo_agent-xyz123"
   ```

1. Wenn Sie OAuth verwenden, exportieren Sie Ihr Bearer-Token:

   ```
   export BEARER_TOKEN="your_oauth_token_here"
   ```

#### Authentifizierungsmethoden
<a name="websocket-authentication-methods"></a>

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:
+  ** AWS Signatur-Header der Version 4**: Signieren Sie die Header der WebSocket Handshake-Anfrage mit Ihren Anmeldeinformationen AWS 
+  AWS URL der **Signaturversion 4: Erstellen Sie eine vorsignierte Pre-signed WebSocket URL** mit einer SigV4-Signatur, die als Abfrageparameter bereitgestellt wird
+  **OAuth-Bearer-Token: Übergeben Sie ein OAuth-Token** im Authorization-Header für die Integration eines externen Identitätsanbieters

**Tipp**  
Stellen Sie sicher, dass Sie über die erforderlichen Berechtigungen verfügen. `bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream`

#### Connect mit signierten SigV4-Headern her
<a name="websocket-sigv4-headers"></a>

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

##### WebSocket Client mit SigV4-Headern (websocket\_agent\_client\_sigv4\_headers.py)
<a name="websocket-sigv4-example"></a>

```
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)
<a name="websocket-sigv4-presigned"></a>

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

##### WebSocket Client mit vorsignierter URL (websocket\_agent\_client\_sigv4\_presigned\_url.py)
<a name="websocket-presigned-example"></a>

```
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
<a name="websocket-oauth"></a>

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](runtime-oauth.md#oauth-sample-overview) Authentifizierung beschrieben.](runtime-oauth.md)

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](runtime-oauth.md#oauth-invoke-agent), erhalten haben, können Sie dieses Token verwenden, um WebSocket Verbindungen herzustellen.

##### Python-Client mit OAuth
<a name="websocket-oauth-python"></a>

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

##### WebSocket Client mit OAuth-Authentifizierung (websocket\_agent\_client\_oauth.py)
<a name="websocket-oauth-example"></a>

```
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
<a name="websocket-oauth-browser"></a>

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 

##### WebSocket Browserclient mit OAuth (index.html)
<a name="websocket-oauth-browser-example"></a>

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

**Anmerkung**  
Diese Authentifizierungsmethode ist für browserbasierte Clients vorgesehen, bei denen das Festlegen benutzerdefinierter Header nicht möglich ist. Verwenden Sie für Nicht-Browser-Clients (Python, Node.js Server usw.) die OAuth-Header-Authentifizierung, die im [Python-Client](#websocket-oauth-python) mit OAuth angezeigt wird.

**Anmerkung**  
Andere Unterprotokolle als die, die noch nicht unterstützt werden. `base64UrlBearerAuthorization`

**Wichtig**  
Dies ist ein Referenzbeispiel. Es wird nicht empfohlen, Token im Produktionscode fest zu codieren.

## Verwaltung von Sitzungen
<a name="websocket-session-management"></a>

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](runtime-sessions.md).

### Verwenden von Sitzungen mit Verbindungen WebSocket
<a name="websocket-with-sessions"></a>

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:

**Example**  

1. 

   ```
   from bedrock_agentcore.runtime import AgentCoreRuntimeClient
   import websockets
   import asyncio
   import json
   import os
   
   async def websocket_with_session():
       client = AgentCoreRuntimeClient(region="us-west-2")
       session_id = "user-123-conversation-456"
       runtime_arn = os.getenv('AGENT_ARN')
   
       ws_url, headers = client.generate_ws_connection(
           runtime_arn=runtime_arn,
           session_id=session_id
       )
   
       try:
           async with websockets.connect(ws_url, additional_headers=headers) as ws:
               await ws.send(json.dumps({"inputText": "Hello!"}))
               response = await ws.recv()
               print(f"Response: {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}")
   
   asyncio.run(websocket_with_session())
   ```

1. 

   ```
   from bedrock_agentcore.runtime import AgentCoreRuntimeClient
   import websockets
   import asyncio
   import json
   import os
   
   async def websocket_with_session():
       client = AgentCoreRuntimeClient(region="us-west-2")
       session_id = "user-123-conversation-456"
       runtime_arn = os.getenv('AGENT_ARN')
   
       presigned_url = client.generate_presigned_url(
           runtime_arn=runtime_arn,
           session_id=session_id,
           expires=300
       )
   
       try:
           async with websockets.connect(presigned_url) as ws:
               await ws.send(json.dumps({"inputText": "Hello!"}))
               response = await ws.recv()
               print(f"Response: {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}")
   
   asyncio.run(websocket_with_session())
   ```

1. 

   ```
   from bedrock_agentcore.runtime import AgentCoreRuntimeClient
   import websockets
   import asyncio
   import json
   import os
   
   async def websocket_with_session():
       client = AgentCoreRuntimeClient(region="us-west-2")
       session_id = "user-123-conversation-456"
       runtime_arn = os.getenv('AGENT_ARN')
       bearer_token = os.getenv('BEARER_TOKEN')
   
       ws_url, headers = client.generate_ws_connection_oauth(
           runtime_arn=runtime_arn,
           session_id=session_id,
           bearer_token=bearer_token
       )
   
       try:
           async with websockets.connect(ws_url, additional_headers=headers) as ws:
               await ws.send(json.dumps({"inputText": "Hello!"}))
               response = await ws.recv()
               print(f"Response: {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}")
   
   asyncio.run(websocket_with_session())
   ```

**Tipp**  
Um optimale Ergebnisse zu erzielen, verwenden Sie eine UUID oder eine andere eindeutige Kennung für Ihre Sitzungs-IDs, um Kollisionen zwischen verschiedenen Benutzern oder Konversationen zu vermeiden.

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
<a name="websocket-session-lifecycle"></a>

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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-settings.html). Eine direktere Steuerung des Sitzungslebenszyklus anhand des Integritätsstatus der Agenten finden Sie unter [Runtime-Sitzungslebenszyklusmanagement](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-long-run.html#runtime-long-run-session-lifecycle).

### Runtime-Sitzung beenden
<a name="websocket-stop-session"></a>

Informationen zum Beenden einer laufenden Sitzung vor der konfigurierbaren Sitzung `IdleRuntimeSessionTimeout` (standardmäßig 15 Minuten) finden Sie unter [Beenden einer laufenden](runtime-stop-session.md) Sitzung.

## Beobachtbarkeit
<a name="websocket-observability"></a>

 [Amazon Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin) folgen. Informationen zur Beobachtung Ihres Agenten finden Sie unter [Beobachtbarkeitsdaten für Ihre Amazon AgentCore Bedrock-Agenten anzeigen](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html).

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

## Benutzerdefinierte Header
<a name="websocket-custom-headers"></a>

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-header-allowlist.md) 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
<a name="websocket-appendix"></a>

**Topics**
+ [Sicherheitsüberlegungen](#security-considerations)
+ [Fehlerbehebung](#websocket-troubleshooting)
+ [WebSocket im Vergleich zu anderen Protokollen](#websocket-vs-other-protocols)
+ [Zusätzliche Beispiele für erste Schritte](#websocket-additional-examples)

### Sicherheitsüberlegungen
<a name="security-considerations"></a>

**Tipp**  
Eine konsolidierte Übersicht aller Runtime-Sicherheitsempfehlungen finden Sie unter [Bewährte Sicherheitsmethoden für AgentCore Runtime](runtime-security-best-practices.md).

Authentifizierung  
Alle WebSocket Verbindungen erfordern eine korrekte AWS Authentifizierung über Sigv4 oder OAuth 2.0

Isolierung von Sitzungen  
Jede Sitzung wird in isolierten Ausführungsumgebungen mit dedizierten Ressourcen ausgeführt

Übertragungssicherheit  
Alle Verbindungen verwenden WSS (WebSocket Secure) über HTTPS für die verschlüsselte Kommunikation

Zugriffskontrolle  
IAM-Richtlinien steuern die WebSocket Verbindungsberechtigungen und den Zugriff auf bestimmte Agenten

### Fehlerbehebung
<a name="websocket-troubleshooting"></a>

#### Häufig auftretende Probleme WebSocket-specific
<a name="common-websocket-issues"></a>

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

Verbindungsfehler  
Stellen Sie sicher, dass Ihre Agentenanwendung Verbindungsanfragen unter verarbeitet `/ws` 

Die Authentifizierungsmethode stimmt nicht überein  
Stellen Sie sicher, dass Ihr Client dieselbe Authentifizierungsmethode (OAuth oder SigV4) verwendet, mit der der Agent konfiguriert wurde

Die Verbindung wurde geschlossen, da das Limit überschritten wurde  
Verbindungen werden automatisch geschlossen, wenn Grenzwerte wie Grenzwerte für die Nachrichten-Frame-Rate oder die Nachrichten-Frame-Größe überschritten werden. Vollständige Informationen zu den Limits finden Sie unter [Kontingente für Amazon Bedrock AgentCore](bedrock-agentcore-limits.md) 

Die Größe des Nachrichtenrahmens wurde überschritten  
Konfigurieren Sie die Fragmentierung von Nachrichtenframes oder implementieren Sie Chunking, um unter der Framegrößenbeschränkung von 32 KB zu bleiben. Teilen Sie große Nachrichten vor dem Senden in kleinere Teile auf

Fehlschläge bei der Gesundheitsprüfung  
Stellen Sie sicher, dass Ihr Agent-Container den `/ping` Endpunkt wie im [HTTP-Protokollvertrag](runtime-http-protocol-contract.md) angegeben implementiert. Dieser Endpunkt überprüft, ob Ihr Agent betriebsbereit und bereit ist, Anfragen zu bearbeiten, und ermöglicht so die Dienstüberwachung und automatische Wiederherstellung

#### Fehlerbehandlung
<a name="websocket-error-handling"></a>

WebSocket Verbindungen verwenden standardmäßige Schließcodes für die Fehlerkommunikation. Zu den gängigen Schließcodes gehören:
+  `1000`- Normaler Verschluss
+  `1001`- Geht weg
+  `1008`- Richtlinie verletzt (Limit überschritten)
+  `1009`- Nachricht zu groß (Größenbeschränkung für Nachrichtenrahmen überschritten)
+  `1011`- Serverfehler

### WebSocket im Vergleich zu anderen Protokollen
<a name="websocket-vs-other-protocols"></a>

 **Wann sollte verwendet werden WebSocket**:
+ Real-time Sprachgespräche mit sofortigem Audiostreaming für einen natürlichen Gesprächsfluss
+  audio/textBidirektionaler/binärer Datenfluss (Streamen von Datenblöcken vom Client zum Agenten und umgekehrt)
+ Behandlung von Unterbrechungen (der Benutzer kann den Agenten während einer Konversation unterbrechen)

 **Wann sollte HTTP verwendet werden**:
+ HTTP für Anfrage-Antwort-Muster ohne bidirektionales Streaming

### Zusätzliche Beispiele für erste Schritte
<a name="websocket-additional-examples"></a>

Weitere Beispiele für WebSocket bidirektionales Streaming mit AgentCore Runtime finden Sie in den Beispielen für [WebSocket bidirektionales Streaming GitHub ](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials/01-AgentCore-runtime/06-bi-directional-streaming):
+  **Sonic-Implementierung (Python)**: Native Amazon Nova WebSocket Sonic-Implementierung mit Audiokonversationen in Echtzeit, Sprachauswahl und Unterstützung für Unterbrechungen
+  **Strands-Implementierung (Python)**: Framework-based Implementierung unter Verwendung von Strands BidiAgent für vereinfachte Audiokonversationen in Echtzeit mit automatischem Sitzungsmanagement und Toolintegration
+  **Echo-Implementierung (Python)**: Einfacher Echo-Server zum Testen von WebSocket Konnektivität und Authentifizierung