122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# Amazon Bedrock AgentCore Runtime Example
|
|
|
|
This example demonstrates how to prepare a Pipecat bot for deployment to **Amazon Bedrock AgentCore Runtime** and enable it to invoke AgentCore tools.
|
|
|
|
## Overview
|
|
|
|
This example shows the set needed to:
|
|
|
|
- Deploy your Pipecat bot to Amazon Bedrock AgentCore Runtime (which hosts and runs your bot)
|
|
- Enable your bot to invoke AgentCore tools while running in the AgentCore Runtime
|
|
|
|
The key additions to a standard Pipecat bot are the AgentCore-specific configurations and tool invocation handling that allow your bot to leverage the full AgentCore ecosystem.
|
|
|
|
## Prerequisites
|
|
|
|
- Accounts with:
|
|
- AWS
|
|
- OpenAI
|
|
- Deepgram
|
|
- Cartesia
|
|
- Daily
|
|
- Python 3.10 or higher
|
|
- `uv` package manager
|
|
|
|
## 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.
|
|
|
|
To simplify the remaining steps in this README, it's a good idea to export some AWS-specific environment variables:
|
|
|
|
```bash
|
|
export AWS_SECRET_ACCESS_KEY=...
|
|
export AWS_ACCESS_KEY_ID=...
|
|
export AWS_REGION=...
|
|
```
|
|
|
|
## Agent Configuration
|
|
|
|
Configure your bot as an AgentCore agent.
|
|
|
|
```bash
|
|
agentcore configure -e bot.py
|
|
```
|
|
|
|
Follow the prompts to complete the configuration.
|
|
|
|
**IMPORTANT:** when asked if you want to use "Direct Code Deploy" or "Container", choose "Container". Today there is an incompatibility between Pipecat and "Direct Code Deploy".
|
|
|
|
> For the curious: "Direct Code Deploy" requires that all bot dependencies have an `aarch64_manylinux2014` wheel...which is unfortunately not true for `numba`.
|
|
|
|
## Deployment to AgentCore Runtime
|
|
|
|
Deploy your configured bot to Amazon Bedrock AgentCore Runtime for production hosting.
|
|
|
|
```bash
|
|
agentcore launch --env OPENAI_API_KEY=... --env DEEPGRAM_API_KEY=... --env CARTESIA_API_KEY=... # -a <agent_name> (if multiple agents configured)
|
|
|
|
# or just use this script, which will read and send all environment variables
|
|
./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 bot code.
|
|
|
|
## Running on AgentCore Runtime
|
|
|
|
Run your bot on AgentCore Runtime.
|
|
|
|
```bash
|
|
agentcore invoke '{"roomUrl": "https://<your-domain>.daily.co/<room-name>"}' # -a <agent_name> (if multiple agents configured)
|
|
```
|
|
|
|
In case we wish to define the session-id, to create a new session each time we invoke:
|
|
```bash
|
|
aws-agentcore % agentcore invoke \
|
|
--session-id user-123456-conversation-12345679 \
|
|
'{"roomUrl": "https://<your-domain>.daily.co/<room-name>"}'
|
|
```
|
|
|
|
## Observation
|
|
|
|
Paste the log tailing command you received when deploying your bot to AgentCore Runtime. It should look something like:
|
|
|
|
```bash
|
|
# Replace with your actual command
|
|
aws logs tail /aws/bedrock-agentcore/runtimes/bot1-0uJkkT7QHC-DEFAULT --log-stream-name-prefix "2025/11/19/[runtime-logs]" --follow
|
|
```
|
|
|
|
## Removing your local agent
|
|
|
|
```bash
|
|
agentcore destroy
|
|
```
|
|
|
|
## Running Locally
|
|
|
|
You can also run your bot locally, using either the SmallWebRTC or Daily transport.
|
|
|
|
First, copy `env.example` to `.env` and fill in the values.
|
|
|
|
Then, run the bot:
|
|
|
|
```bash
|
|
# SmallWebRTC
|
|
PIPECAT_LOCAL_DEV=1 uv run python bot.py
|
|
|
|
# Daily
|
|
PIPECAT_LOCAL_DEV=1 uv run python bot.py -t daily -d
|
|
```
|
|
|
|
> Ideally you should be able to use `agentcore launch --local`, but it doesn't currently appear to be working (even with [this workaround](https://github.com/aws/bedrock-agentcore-starter-toolkit/issues/156) applied), at least not for this project.
|
|
|
|
## 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).
|