AgentCore Runtime example, using new AgentCore bidirectional streaming (WebSocket) endpoint

.gitignore

@@ -203,7 +203,7 @@ cython_debug/
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
 #  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
-# .vscode/
+.vscode/
 
 # Ruff stuff:
 .ruff_cache/

deployment/aws-agentcore/README.md → deployment/aws-agentcore-webrtc/README.md

@@ -1,4 +1,4 @@
-# Amazon Bedrock AgentCore Runtime Example
+# Amazon Bedrock AgentCore Runtime WebRTC Example
 
 This example demonstrates how to deploy a Pipecat bot to **Amazon Bedrock AgentCore Runtime** using SmallWebRTC for communication.
 
@@ -25,6 +25,7 @@ You can also choose to specify more granular permissions; see [Amazon Bedrock Ag
 To authenticate with AWS, you have two options:
 
 1. Export environment variables:
+
    ```bash
    export AWS_SECRET_ACCESS_KEY=your_secret_key
    export AWS_ACCESS_KEY_ID=your_access_key
@@ -41,25 +42,30 @@ To authenticate with AWS, you have two options:
 ### Virtual Environment Setup
 
 Create and activate a virtual environment:
-   ```bash
-   uv sync
-   ```
+
+```bash
+uv sync
+```
 
 ### Environment Variables Configuration
 
 1. For the agent:
+
    ```bash
    cd agent
    cp env.example .env
    ```
+
    Add your API keys:
+
    - `DEEPGRAM_API_KEY`: Your Deepgram API key
    - `CARTESIA_API_KEY`: Your Cartesia API key
    - `ICE_SERVER_URLS`: Your TCP TURN server urls
    - `ICE_SERVER_USERNAME`: Your TURN server username
    - `ICE_SERVER_CREDENTIAL`: Your TURN server credential
 
    > Important Notes about TURN Server Configuration:
+   >
    > - You must use TURN servers that support TCP connections
    > - UDP connections are not supported within AgentCore runtime environment
    > - If your TURN server only supports UDP, your WebRTC connection will fail
@@ -82,6 +88,7 @@ cd agent
 ```
 
 This script:
+
 1. Configures deployment type as "Container" (required by Pipecat)
 2. Applies necessary patches to the Dockerfile
 3. Adds dependencies required by SmallWebRTC (`libgl1` and `libglib2.0-0`)
@@ -101,6 +108,7 @@ cd agent
 ```
 
 This script:
+
 1. Reads environment variables from `agent/.env`
 2. Deploys to AgentCore
 3. Updates the server's configuration with the agent ARN
@@ -109,6 +117,7 @@ This script:
 ## Running on AgentCore Runtime
 
 1. Start the server:
+
    ```bash
    cd server
    uv run python server.py
@@ -121,6 +130,7 @@ This script:
 ## Monitoring and Troubleshooting
 
 ### View Agent Logs
+
 Use the log-tailing command provided during deployment:
 
 ```bash
@@ -129,12 +139,13 @@ aws logs tail /aws/bedrock-agentcore/runtimes/bot1-0uJkkT7QHC-DEFAULT --log-stre
 ```
 
 ## Test Agent Manually
+
 Test the agent using the AWS CLI:
 
 ```bash
 uv run agentcore invoke \
   --session-id user-123456-conversation-12345679 \
-  '{                                             
+  '{
   "sdp": "YOUR_OFFER",
   "type": "offer"
 }'
@@ -154,9 +165,10 @@ cd agent
 ## Local Development
 
 Run your bot locally for testing:
-   ```bash
-   PIPECAT_LOCAL_DEV=1 uv run python pipecat-agent.py
-   ```
+
+```bash
+PIPECAT_LOCAL_DEV=1 uv run python pipecat-agent.py
+```
 
 ## Additional Resources
 

deployment/aws-agentcore-websocket/.gitignore

@@ -0,0 +1,3 @@
+.bedrock_agentcore.yaml
+.dockerignore
+.bedrock_agentcore

deployment/aws-agentcore-websocket/README.md

@@ -0,0 +1,172 @@
+# Amazon Bedrock AgentCore Runtime WebSocket Example
+
+This example demonstrates how to deploy a Pipecat bot to **Amazon Bedrock AgentCore Runtime** using WebSockets for communication.
+
+## Prerequisites
+
+- Accounts with:
+  - AWS
+  - Deepgram
+  - Cartesia
+- Python 3.10 or higher
+- `uv` package manager
+
+## Environment Setup
+
+### IAM Configuration
+
+Configure your IAM user with the necessary policies for AgentCore usage. Start with these:
+
+- `BedrockAgentCoreFullAccess`
+- A new policy (maybe named `BedrockAgentCoreCLI`) configured [like this](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-starter-toolkit)
+
+You can also choose to specify more granular permissions; see [Amazon Bedrock AgentCore docs](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html) for more information.
+
+### Environment Variable Setup
+
+1. For agent management (configuring, deploying, etc.):
+
+   Either export your AWS credentials and configuration as environment variables:
+
+   ```bash
+   export AWS_SECRET_ACCESS_KEY=...
+   export AWS_ACCESS_KEY_ID=...
+   export AWS_REGION=...
+   ```
+
+   Or use AWS CLI configuration:
+
+   ```bash
+   aws configure
+   ```
+
+2. For the agent itself:
+
+   ```bash
+   cd agent
+   cp env.example .env
+   ```
+
+   Add your API keys:
+
+   - `AWS_ACCESS_KEY_ID`: Your AWS access key ID for the Amazon Bedrock LLM used by the agent
+   - `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key for the Amazon Bedrock LLM used by the agent
+   - `AWS_REGION`: The AWS region for the Amazon Bedrock LLM used by the agent
+   - `DEEPGRAM_API_KEY`: Your Deepgram API key
+   - `CARTESIA_API_KEY`: Your Cartesia API key
+
+3. For the server:
+
+   ```bash
+   cd server
+   cp env.example .env
+   ```
+
+   Add your AWS credentials and configuration, for generating a signed WebSocket URL in the `/start` endpoint:
+
+   - `AWS_ACCESS_KEY_ID`
+   - `AWS_SECRET_ACCESS_KEY`
+   - `AWS_REGION`
+
+### Virtual Environment Setup
+
+Create and activate a virtual environment for managing the agent:
+
+```bash
+uv sync
+```
+
+## Agent Configuration
+
+Configure your Pipecat agent as an AgentCore agent:
+
+```bash
+uv run agentcore configure -e agent/agent.py
+```
+
+Follow the prompts to complete the configuration. It's fine to just accept all defaults.
+
+## ⚠️ Before Proceeding
+
+Just in case you've deployed multiple agents to AgentCore or deployed agents under multiple names, ensure that you have the desired agent selected as "default" in the `agentcore` tool:
+
+```
+# Check
+uv run agentcore configure list
+# Set
+uv run agentcore configure set-default <agent-name>
+```
+
+The following steps act on `agentcore`'s default agent.
+
+## Deploying to AgentCore
+
+Deploy your configured agent to Amazon Bedrock AgentCore Runtime for production hosting.
+
+```bash
+./scripts/launch.sh
+```
+
+You should see commands related to tailing logs printed to the console. Copy and save them for later use.
+
+This is also the command you need to run after you've updated your agent code.
+
+## Running the Server
+
+The server provides a `/start` endpoint that generates WebSocket URLs for the client to connect to the agent.
+
+See [the server README](./server/README.md) for setup and run instructions.
+
+## Running the Client
+
+Once the server is running, you can run the client to connect to your AgentCore-hosted agent.
+
+See [the client README](./client/README.md) for setup and run instructions.
+
+## Testing Locally
+
+To test agent logic locally before deploying to AgentCore Runtime, do the following.
+
+First, run the agent locally:
+
+```bash
+cd agent
+uv run python agent.py
+```
+
+This will make the agent reachable at "ws://localhost:8080/ws".
+
+Then, run the server as usual, but with the `LOCAL_AGENT=1` environment variable:
+
+```bash
+LOCAL_AGENT=1 uv run python server.py
+```
+
+You can then [run your client as usual](#running-the-client).
+
+## Observation
+
+Paste one of the log tailing commands you received when deploying your agent to AgentCore Runtime. It should look something like:
+
+```bash
+# Replace with your actual command
+aws logs tail /aws/bedrock-agentcore/runtimes/foo-0uJkkT7QHC-DEFAULT --log-stream-name-prefix "2025/11/19/[runtime-logs]" --follow
+```
+
+If you don't have that command handy, no worries. Just run:
+
+```bash
+uv run agentcore status
+```
+
+## Agent Deletion
+
+Delete your agent from AgentCore:
+
+```bash
+uv run agentcore destroy
+```
+
+## Additional Resources
+
+For a comprehensive guide to getting started with Amazon Bedrock AgentCore, including detailed setup instructions, see the [Amazon Bedrock AgentCore Developer Guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html).