Amazon Bedrock AgentCore is in preview release and is subject to change.

Get started with the Amazon Bedrock AgentCore Runtime starter toolkit

You can use the starter toolkit to create Amazon Bedrock AgentCore Runtime agents. It is ideal for use with popular agent frameworks. This tutorial shows you how to prepare your agent code, deploy it to Amazon Bedrock AgentCore, and invoke your agent.

In this guide, you'll learn how to:

Prerequisites

Before you start, you need:

Enable observability for your agent

Amazon Bedrock AgentCore Observability helps you trace, debug, and monitor agents that you host in AgentCore Runtime. To observe an agent, first enable CloudWatch Transaction Search by following the instructions at Enabling AgentCore runtime observability.

Preparing your agent

The Amazon Bedrock AgentCore Python SDK provides a lightweight wrapper that helps you deploy your agent functions as HTTP services compatible with Amazon Bedrock AgentCore. It handles all the HTTP server details so you can focus on your agent's core functionality.

To get started, install the bedrock-agentcore package:

pip install bedrock-agentcore

Prepare your agent in 3 simple steps

You can convert your existing agent function into a Amazon Bedrock AgentCore-compatible service with just three steps:

Step 1: Import the runtime

Add this import statement to your Python file:

from bedrock_agentcore.runtime import BedrockAgentCoreApp

Step 2: Initialize the app

Create an instance of the BedrockAgentCoreApp:

app = BedrockAgentCoreApp()

Step 3: Decorate your function

Add the @app.entrypoint decorator to your existing function, and access the JSON object that you plan to use when invoking the agent:

@app.entrypoint
def invoke(payload):
    """Process user input and return a response"""
    user_message = payload.get("prompt", "Hello")
    return {"result": user_message}

Then add the run command at the end of your file:

if __name__ == "__main__":
    app.run()

That's it! Your agent is now ready to be deployed as a Amazon Bedrock AgentCore-compatible service.

Testing locally

After implementing these changes, you can test your service locally:

python my_agent.py

# The server starts at http://localhost:8080

# Test with curl:
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello world!"}'

What happens behind the scenes

When you use BedrockAgentCoreApp, it automatically:

Complete examples

Here's a basic example:

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()

@app.entrypoint
def invoke(payload):
    """Process user input and return a response"""
    user_message = payload.get("prompt", "Hello")
    result = agent(user_message)
    return {"result": result.message}

if __name__ == "__main__":
    app.run()

Here's a Strands example with streaming:

from strands import Agent
from bedrock_agentcore import BedrockAgentCoreApp

app = BedrockAgentCoreApp()
agent = Agent()

@app.entrypoint
async def agent_invocation(payload):
    """Handler for agent invocation"""
    user_message = payload.get(
        "prompt", "No prompt found in input, please guide customer to create a json payload with prompt key"
    )
    stream = agent.stream_async(user_message)
    async for event in stream:
        print(event)
        yield (event)

if __name__ == "__main__":
    app.run()

Deploying your agent

The CreateAgentRuntime operation supports comprehensive configuration options, letting you specify container images, environment variables and execution role. You can also configure protocol settings (HTTP, MCP) and authorization mechanisms to control how your clients communicate with the agent. The operation uses idempotency tokens to ensure that repeated requests don't create duplicate runtimes, and it returns detailed status information to help you track the runtime's lifecycle from creation through readiness.

Before you deploy, you need:

Package your code as container image and push to the ECR repo. You can create your agent using CreateAgentRuntime:

import boto3

# Create the client
client = boto3.client('bedrock-agentcore-control', region_name="us-east-1")

# Call the CreateAgentRuntime operation
response = client.create_agent_runtime(
    agentRuntimeName='hello_agent',
    agentRuntimeArtifact={
        'containerConfiguration': {
            'containerUri': '123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest'
        }
    },
    networkConfiguration={"networkMode":"PUBLIC"},
    roleArn='arn:aws:iam::123456789012:role/AgentRuntimeRole'
)

Using starter-toolkit for quick prototyping

For quick prototyping, you can use starter-toolkit to easily package your artifacts and deploy to runtime.

Start by installing the package:

pip install bedrock-agentcore-starter-toolkit

Create a project folder with the following structure:

## Project Folder Structure

your_project_directory/
├── agent_example.py # Your main agent code
├── requirements.txt # Dependencies for your agent
└── __init__.py # Makes the directory a Python package


### File Contents

#### agent_example.py
from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp

agent = Agent()
app = BedrockAgentCoreApp()

@app.entrypoint
def invoke(payload):
    """Process user input and return a response"""
    user_message = payload.get("prompt", "Hello")
    response = agent(user_message)
    return str(response) # response should be json serializable

if __name__ == "__main__":
    app.run()


#### requirements.txt
strands-agents
bedrock-agentcore

Ensure Docker software or Finch is running before proceeding with deployment. For

Configure your agent with the following command. For YOUR_IAM_ROLE_ARN, you need an IAM role with suitable permissions. For information see Permissions for AgentCore Runtime.

## Deployment Steps

### Step 1: Configure Your Agent

# Run the configuration command to set up your agent:

agentcore configure --entrypoint agent_example.py -er <YOUR_IAM_ROLE_ARN>

# The command will:
##• Generate a Dockerfile and .dockerignore
##• Create a .bedrock_agentcore.yaml configuration file

Launch your agent:

### Step 2: Launch Your Agent to the Cloud

## Local Testing
# For development and testing, you can run your agent locally:
agentcore launch -l

## This will:
### Build a Docker image
### Run the container locally
### Start a server at http://localhost:8080


# Deploy your agent to AWS:
agentcore launch

# This command will:
### Build a Docker image with your agent code
### Push the image to Amazon ECR
### Create a Bedrock AgentCore runtime
### Deploy your agent to the cloud

In the output from agentcore launch note the ARN of the agent. You need it to invoke the agent with the InvokeAgentRuntime operation.

Test your agent:

### Step 3: Test Your Agent
agentcore invoke '{"prompt": "Hello"}'

Invoking your agent

You can invoke the agent using InvokeAgentRuntime operation.

Here's an example of how to use boto3 (AWS SDK) to invoke an agent runtime:

import boto3
import json

# Initialize the Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore', region_name="us-east-1")


# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)

You can use CloudWatch logs to see in real-time what the agent is doing either using AWS CLI or AWS console.

If you plan on integrating your agent with OAuth, you can't use the AWS SDK to call InvokeAgentRuntime. Instead, make a HTTPS request to InvokeAgentRuntime. For more information, Authenticate and authorize with Inbound Auth and Outbound Auth.