Get started with the Amazon Bedrock AgentCore starter toolkit

This tutorial shows you how to use the Amazon Bedrock AgentCore starter toolkit to deploy an agent to an Amazon Bedrock AgentCore Runtime.

The starter toolkit is a Command Line Interface (CLI) toolkit that you can use to deploy AI agents to an Amazon Bedrock AgentCore Runtime. You can use the toolkit with popular Python agent frameworks, such as LangGraph or Strands Agents. This tutorial uses Strands Agents.

Prerequisites

Before you start, make sure you have:

Step 1: Set up project and install dependencies

Create a project folder and install the required packages:

mkdir agentcore-runtime-quickstart
cd agentcore-runtime-quickstart
python3 -m venv .venv
source .venv/bin/activate

Upgrade pip to the latest version:

pip install --upgrade pip

Install the following required packages:

pip install bedrock-agentcore strands-agents bedrock-agentcore-starter-toolkit

Verify installation:

agentcore --help

Step 2: Create your agent

Create a source file for your agent code named my_agent.py. Add the following code:

from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()

@app.entrypoint
def invoke(payload):
    """Your AI agent function"""
    user_message = payload.get("prompt", "Hello! How can I help you today?")
    result = agent(user_message)
    return {"result": result.message}

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

Create requirements.txt and add the following:

bedrock-agentcore
strands-agents

Step 3: Test locally

Make sure port 8080 is free before starting. See Port 8080 in use (local only) in Common issues and solutions.

Open a terminal window and start your agent with the following command:

python my_agent.py

Test your agent by opening another terminal window and enter the following command:

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

Success: You should see a response like {"result": "Hello! I'm here to help..."}. In the terminal window that's running the agent, enter Ctrl+C to stop the agent.

Step 4: Configure your agent

Configure and deploy your agent to AWS using the starter toolkit. The toolkit automatically creates the IAM execution role, container image, and Amazon Elastic Container Registry repository needed to host the agent in an AgentCore Runtime. By default the toolkit hosts the agent in an AgentCore Runtime that is in the us-west-2 AWS Region.

Configure the agent using the default values:

agentcore configure -e my_agent.py

(Optional) Use a different AWS Region

By default, the starter toolkit deploys to the us-west-2 AWS Region. To use a different Region:

agentcore configure -e my_agent.py -r us-east-1

Step 5: Enable observability for your agent

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

Step 6: Deploy to Amazon Bedrock AgentCore Runtime

Host your agent in AgentCore Runtime:

agentcore launch

This command:

In the output from agentcore launch note the following:

If the deployment fails check for common issues. For other deployment options, see Deployment modes.

Step 7: Test your deployed agent

Test your deployed agent:

agentcore invoke '{"prompt": "tell me a joke"}'

If you see a joke in the response, your agent is now running in an Amazon Bedrock AgentCore Runtime and can be invoked. If not, check for common issues.

Step 8: Invoke your agent programmatically

You can invoke the agent using the AWS SDK InvokeAgentRuntime operation. To call InvokeAgentRuntime, you need the ARN of the agent that you noted in Step 6: Deploy to Amazon Bedrock AgentCore Runtime. You can also get the ARN from the bedrock_agentcore: section of the .bedrock_agentcore.yaml (hidden) file that the toolkit creates. Use the following boto3 (AWS SDK) code to invoke your agent. Replace Agent ARN with the ARN of your agent. Make sure that you have bedrock-agentcore:InvokeAgentRuntime permissions. Create a file named invoke_agent.py and add the following code:

import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

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

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))

Open a terminal window and run the code with the following command:

python invoke_agent.py

If successful, you should see a joke in the response. If the call fails, check the logs that you noted in Step 6: Deploy to Amazon Bedrock AgentCore Runtime.

Step 9: Clean up

If you no longer want to host the agent in the AgentCore Runtime, use the destroy commnand to delete the AWS resources that the starter toolit created for you.

agentcore destroy

Find your resources

After deployment, view your resources in the AWS Console:

Common issues and solutions

Common issues and solutions when getting started with the Amazon Bedrock AgentCore starter toolkit. For more troubleshooting information, see Troubleshoot Amazon Bedrock AgentCore Runtime.

Advanced options (Optional)

The starter toolkit has advanced configuration options for different deployment modes and custom IAM roles. For more information, see Runtime commands for the starter toolkit.

Deployment modes

Choose the right deployment approach for your needs:

Custom execution role

Use an existing IAM role:

agentcore configure -e my_agent.py --execution-role arn:aws:iam::111122223333:role/MyRole

Why ARM64?

Amazon Bedrock AgentCore Runtime requires ARM64 containers (AWS Graviton). The toolkit handles this automatically: