AWS bedrock-agentcore documentation change
Summary
Updated WebSocket documentation with expanded authentication examples, session management details, and improved code samples for bidirectional streaming agents
Security assessment
The changes add documentation for authentication methods (SigV4/OAuth 2.0) and session isolation features. While these are security-related features, there's no evidence of addressing a specific vulnerability. The additions explain security controls rather than patching issues.
Diff
diff --git a/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.md b/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.md index b80e82f9a..db87f696a 100644 --- a//bedrock-agentcore/latest/devguide/runtime-get-started-websocket.md +++ b//bedrock-agentcore/latest/devguide/runtime-get-started-websocket.md @@ -5 +5 @@ -How AgentCore Runtime supports WebSocketUsing WebSocket with AgentCore RuntimeAppendix +How AgentCore Runtime supports WebSocket connectionsUsing WebSocket with AgentCore RuntimeSession managementAppendix @@ -9 +9 @@ How AgentCore Runtime supports WebSocketUsing WebSocket with AgentCore RuntimeAp -Amazon Bedrock AgentCore Runtime lets you deploy agents that support WebSocket streaming for real-time bidirectional communication. This guide walks you through creating, testing, and deploying your first WebSocket streaming agent. +Amazon Bedrock AgentCore Runtime lets you deploy agents that support WebSocket streaming for real-time bidirectional communication. This guide walks you through creating, testing, and deploying your first bidirectional streaming agent using WebSocket. @@ -13 +13 @@ In this section, you learn: - * How AgentCore Runtime supports WebSocket streaming + * How AgentCore Runtime supports WebSocket connections @@ -15 +15 @@ In this section, you learn: - * How to create a WebSocket agent with streaming capabilities + * How to create an agent application with bidirectional streaming capabilities @@ -22,0 +23,2 @@ In this section, you learn: + * How to use sessions with WebSocket connections + @@ -30 +32 @@ For more information about the WebSocket protocol, see [WebSocket RFC 6455](http - * How AgentCore Runtime supports WebSocket + * How AgentCore Runtime supports WebSocket connections @@ -33,0 +36,2 @@ For more information about the WebSocket protocol, see [WebSocket RFC 6455](http + * Session management + @@ -39 +43 @@ For more information about the WebSocket protocol, see [WebSocket RFC 6455](http -## How AgentCore Runtime supports WebSocket +## How AgentCore Runtime supports WebSocket connections @@ -41 +45 @@ For more information about the WebSocket protocol, see [WebSocket RFC 6455](http -AgentCore Runtime's WebSocket support enables persistent, bidirectional streaming connections between clients and agents by acting as a transparent proxy layer. When configured for WebSocket, AgentCore Runtime expects containers to implement WebSocket endpoints on port `8080` at the `/ws` path, which aligns with standard WebSocket server practices. +AgentCore Runtime's WebSocket support enables persistent, bidirectional streaming connections between clients and agents. AgentCore Runtime expects containers to implement WebSocket endpoints on port `8080` at the `/ws` path, which aligns with standard WebSocket server practices. @@ -43 +47 @@ AgentCore Runtime's WebSocket support enables persistent, bidirectional streamin -The service provides enterprise-grade session isolation while maintaining protocol transparency - WebSocket upgrade requests and messages are routed directly to your agent container without modification. This architecture preserves standard WebSocket features like real-time bidirectional communication, while adding enterprise authentication (SigV4/OAuth 2.0) and scalability. +AgentCore Runtime's WebSocket support provides the same serverless, session isolation, identity, and observability capabilities as `InvokeAgentRuntime`. Additionally, it enables low-latency, real-time bidirectional streaming of messages through WebSocket connections using SigV4 or OAuth 2.0 authentication, making it ideal for applications such as real-time conversational voice agents. @@ -45 +49 @@ The service provides enterprise-grade session isolation while maintaining protoc -Key WebSocket characteristics: +### Supported WebSocket libraries @@ -47 +51 @@ Key WebSocket characteristics: -**Port** +Bidirectional streaming using WebSockets on AgentCore Runtime supports applications using any WebSocket language library. The only requirements are that clients connect to the service endpoint with a WebSocket protocol connection: @@ -50 +54 @@ Key WebSocket characteristics: -WebSocket agents run on port 8080 + wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<agentRuntimeArn>/ws @@ -52 +56 @@ WebSocket agents run on port 8080 -**Path** +using one of the supported authentication methods (SigV4 headers, SigV4 pre-signed URL, or OAuth 2.0) and that the agent application implements the WebSocket service contract as specified in [HTTP protocol contract](./runtime-http-protocol-contract.html). @@ -53,0 +58 @@ WebSocket agents run on port 8080 +This flexibility allows you to use your preferred WebSocket implementation across different programming languages and frameworks, ensuring compatibility with existing codebases and development workflows. @@ -55 +60 @@ WebSocket agents run on port 8080 -WebSocket endpoints are mounted at `/ws` +## Using WebSocket with AgentCore Runtime @@ -57 +62 @@ WebSocket endpoints are mounted at `/ws` -**Protocol** +In this getting started tutorial you will create, test, and deploy an agent application that supports bidirectional streaming using the **bedrock-agentcore Python SDK** and the **Amazon Bedrock AgentCore starter toolkit** for deployment. @@ -58,0 +64 @@ WebSocket endpoints are mounted at `/ws` +###### Topics @@ -60 +66 @@ WebSocket endpoints are mounted at `/ws` -Uses persistent WebSocket connections for real-time streaming + * Prerequisites @@ -62 +68 @@ Uses persistent WebSocket connections for real-time streaming -**Authentication** + * Step 1: Set up project and install dependencies @@ -63,0 +70 @@ Uses persistent WebSocket connections for real-time streaming + * Step 2: Create your bidirectional streaming agent @@ -65 +72 @@ Uses persistent WebSocket connections for real-time streaming -Supports SigV4 headers, SigV4 query parameters, and OAuth 2.0 authentication schemes + * Step 3: Test your bidirectional streaming agent locally @@ -67 +74 @@ Supports SigV4 headers, SigV4 query parameters, and OAuth 2.0 authentication sch -## Using WebSocket with AgentCore Runtime + * Step 4: Deploy your bidirectional streaming agent to AgentCore Runtime @@ -69 +76 @@ Supports SigV4 headers, SigV4 query parameters, and OAuth 2.0 authentication sch -In this tutorial you create, test, and deploy a WebSocket streaming agent. + * Step 5: Invoke your deployed bidirectional streaming agent @@ -71 +77,0 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. -###### Topics @@ -73 +78,0 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * Prerequisites @@ -75 +79,0 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * Step 1: Create your WebSocket agent @@ -77 +81 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * Step 2: Test your WebSocket agent locally +### Prerequisites @@ -79 +83 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * Step 3: Deploy your WebSocket agent to AgentCore Runtime +Before you start, make sure you have: @@ -81 +85 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * Step 4: Invoke your deployed WebSocket agent + * **AWS Account** with credentials configured. To configure your AWS credentials, see [Configuration and credential file settings in the AWS CLI.](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) @@ -82,0 +87 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. + * **Python 3.10+** installed @@ -83,0 +89 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. + * **AWS Permissions** : To create and deploy an agent with the starter toolkit, you must have appropriate permissions. For more information, see [Use the starter toolkit](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-starter-toolkit). @@ -86 +91,0 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. -### Prerequisites @@ -88 +92,0 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * Python 3.10 or higher installed and basic understanding of Python @@ -90 +94 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * An AWS account with appropriate permissions and local credentials configured +### Step 1: Set up project and install dependencies @@ -92 +96 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. - * Understanding of WebSocket protocols and real-time communication concepts +Create a project folder and install the required packages: @@ -94,0 +99,4 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. + mkdir agentcore-runtime-quickstart-websocket + cd agentcore-runtime-quickstart-websocket + python3 -m venv .venv + source .venv/bin/activate @@ -95,0 +104 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. +Upgrade pip to the latest version: @@ -97 +105,0 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. -### Step 1: Create your WebSocket agent @@ -99 +107 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. -#### Create your first WebSocket agent + pip install --upgrade pip @@ -101 +109,13 @@ In this tutorial you create, test, and deploy a WebSocket streaming agent. -Create a new file called `websocket_echo_agent.py`: +Install the following required packages: + + * **bedrock-agentcore** \- The Amazon Bedrock AgentCore SDK for building AI agents, the python `websockets` library dependency is included + + + + + + pip install bedrock-agentcore + +### Step 2: Create your bidirectional streaming agent + +Create a source file for your bidirectional streaming agent code named `websocket_echo_agent.py`. Add the following code: @@ -114 +133,0 @@ Create a new file called `websocket_echo_agent.py`: - while True: @@ -118,5 +136 @@ Create a new file called `websocket_echo_agent.py`: - await websocket.send_json({"echo": data, "session": context.session_id}) - - # Exit on close command - if data.get("action") == "close": - break + await websocket.send_json({"echo": data}) @@ -129 +143 @@ Create a new file called `websocket_echo_agent.py`: - app.run() + app.run(log_level="info") @@ -131 +145 @@ Create a new file called `websocket_echo_agent.py`: -##### Understanding the code +Create `requirements.txt` and add the following: @@ -133 +146,0 @@ Create a new file called `websocket_echo_agent.py`: - * **BedrockAgentCoreApp** : Creates an agent application with built-in WebSocket support and automatic session management @@ -135 +148 @@ Create a new file called `websocket_echo_agent.py`: - * **WebSocket Decorator** : The `@app.websocket` decorator automatically handles connections at the `/ws` path on port 8080 + bedrock-agentcore @@ -137 +150 @@ Create a new file called `websocket_echo_agent.py`: - * **Context Object** : Provides automatic session management via `context.session_id` for maintaining conversation state +The python `websockets` library dependency is included @@ -139 +152 @@ Create a new file called `websocket_echo_agent.py`: - * **Echo Logic** : Sends back received data with session information using `{"echo": data, "session": context.session_id}` +#### Understanding the code @@ -141 +154,3 @@ Create a new file called `websocket_echo_agent.py`: - * **Close Command** : Responds to `{"action": "close"}` messages for graceful connection termination + * **BedrockAgentCoreApp** : Creates an agent application that extends Starlette for AI agent deployment, providing WebSocket support, HTTP routing, middleware, and exception handling capabilities + + * **WebSocket Decorator** : The `@app.websocket` decorator automatically handles connections at the `/ws` path on port 8080 @@ -143 +158 @@ Create a new file called `websocket_echo_agent.py`: - * **Error Handling** : Uses try/except/finally structure to ensure proper WebSocket cleanup and error logging + * **Echo Logic** : Sends back received data using `{"echo": data}` @@ -144,0 +160 @@ Create a new file called `websocket_echo_agent.py`: + * **Error Handling** : Uses try/except/finally structure to ensure proper error logging and graceful connection closure. @@ -148 +163,0 @@ Create a new file called `websocket_echo_agent.py`: -### Step 2: Test your WebSocket agent locally @@ -150 +165 @@ Create a new file called `websocket_echo_agent.py`: -#### Start your WebSocket agent +### Step 3: Test your bidirectional streaming agent locally @@ -152 +167,3 @@ Create a new file called `websocket_echo_agent.py`: -Run your WebSocket agent locally: +#### Start your bidirectional streaming agent + +Open a terminal window and start your bidirectional streaming agent with the following command: @@ -157 +174 @@ Run your WebSocket agent locally: -You should see output indicating the server is running on port `8080`. +You should see output indicating the server is running on port 8080. @@ -161 +178 @@ You should see output indicating the server is running on port `8080`. -You can test the WebSocket endpoint using a simple Python client: +Create a local WebSocket client named `websocket_agent_client.py`: @@ -165,0 +183 @@ You can test the WebSocket endpoint using a simple Python client: + import json @@ -167 +185 @@ You can test the WebSocket endpoint using a simple Python client: - async def test_websocket(): + async def local_websocket(): @@ -169,0 +188 @@ You can test the WebSocket endpoint using a simple Python client: + try: @@ -171,2 +190,2 @@ You can test the WebSocket endpoint using a simple Python client: - # Send a test message - await websocket.send("Hello WebSocket!") + # Send a message + await websocket.send(json.dumps({"inputText": "Hello WebSocket!"})) @@ -176,0 +196,2 @@ You can test the WebSocket endpoint using a simple Python client: + except Exception as e: + print(f"Connection failed: {e}") @@ -179,3 +200 @@ You can test the WebSocket endpoint using a simple Python client: - asyncio.run(test_websocket()) - -### Step 3: Deploy your WebSocket agent to AgentCore Runtime