Skip to content

QuickStart: Your First Agent in 5 Minutes! 🚀

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

The starter toolkit is a Command Line Interface (CLI) toolkit that you can use to deploy AI agents to an 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:

  • AWS Account with credentials configured. To configure your AWS credentials, see Configuration and credential file settings in the AWS CLI.
  • Python 3.10+ installed
  • Boto3 installed
  • AWS Permissions: To create and deploy an agent with the starter toolkit, you must have appropriate permissions. For information, see Use the starter toolkit.
  • Model access: Anthropic Claude Sonnet 4.0 enabled in the Amazon Bedrock console. For information about using a different model with the Strands Agents see the Model Providers section in the Strands Agents SDK documentation.

Step 1: Setup 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

On Windows, use: .venv\Scripts\activate

Upgrade pip to the latest version:

pip install --upgrade pip

Install the following required packages:

  • bedrock-agentcore - The Amazon Bedrock AgentCore SDK for building AI agents
  • strands-agents - The Strands Agents SDK
  • bedrock-agentcore-starter-toolkit - The Amazon Bedrock AgentCore starter toolkit
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

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.

Important: Make sure port 8080 is free before starting.

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 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. Use the default values:

agentcore configure -e my_agent.py
  • The -e or --entrypoint flag specifies the entrypoint file for your agent (the Python file containing your agent code)
  • This command creates configuration for deployment to AWS
  • Accept the default values unless you have specific requirements
  • The configuration information is stored in a hidden file named .bedrock_agentcore.yaml
  • During configuration, you'll be prompted to choose memory options. Memory will be provisioned based on your choice: short-term memory (STM) only, or both short-term and long-term memory (LTM) with automatic extraction of facts, preferences, and summaries.

Note: To continue without memory, use the --disable-memory flag: agentcore configure -e my_agent.py --disable-memory

Using a Different Region

By default, the toolkit deploys to us-west-2. 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 AgentCore Runtime. First enable CloudWatch Transaction Search by following the instructions at Enabling AgentCore runtime observability. To observe your agent, see View observability data for your Amazon Bedrock AgentCore agents.

Step 6: Deploy to AgentCore Runtime

Host your agent in AgentCore Runtime:

agentcore launch

This command:

  • Builds your container using AWS CodeBuild (no Docker required locally)
  • Creates necessary AWS resources (ECR repository, IAM roles, etc.)
  • Deploys your agent to AgentCore Runtime
  • Creates memory resources if you configured memory during the setup
  • Configures CloudWatch logging

In the output from agentcore launch note the following:

  • The Amazon Resource Name (ARN) of the agent. You need it to invoke the agent with the InvokeAgentRuntime operation.
  • The location of the logs in Amazon CloudWatch Logs

If the deployment fails check for Common Issues.

For other deployment options, see Deployment Modes.

Note: Before invoking your agent, you can check the deployment status using agentcore status to verify that all resources including memory (if configured) are provisioned and ready.

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 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 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 <Add your 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 = "<Add your ARN>"
prompt = "Tell me a joke"

# Initialize the 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 AgentCore Runtime.

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, see Authenticate and authorize with Inbound Auth and Outbound Auth.

Step 9: Clean Up

If you no longer want to host the agent in the AgentCore Runtime, use the AgentCore console or the DeleteAgentRuntime AWS SDK operation to delete the AgentCore Runtime.

agentcore destroy

Find Your Resources

After deployment, view your resources in AWS Console:

Resource Location
Agent Logs CloudWatch → Log groups → /aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT
Memory Resources Bedrock AgentCore → Memory (if memory was configured during setup)
Container Images ECR → Repositories → bedrock-agentcore-{agent-name}
Build Logs CodeBuild → Build history
IAM Role IAM → Roles → Search for "BedrockAgentCore"

Common Issues & Solutions

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

Permission denied errors Verify your AWS credentials and permissions: - Verify AWS credentials: `aws sts get-caller-identity` - Check you have the required policies attached - Review caller permissions policy for detailed requirements
Docker not found warnings You can ignore this warning: - **Ignore this!** Default deployment uses CodeBuild (no Docker needed) - Only install Docker/Finch/Podman if you want to use `--local` or `--local-build` flags
Model access denied Enable model access in the Bedrock console: - Enable Anthropic Claude 4.0 in the Bedrock console - Make sure you're in the correct AWS region (us-west-2 by default)
CodeBuild build error Check build logs and permissions: - Check CodeBuild project logs in AWS console - Verify your caller permissions include CodeBuild access
Port 8080 in use (local only) **Symptom**: Error stating port 8080 is already in use when testing locally. **Solution**: - Mac/Linux: `lsof -ti:8080 | xargs kill -9` - Windows: Find and stop the process using port 8080 in Task Manager - Or choose a different port in your configuration
Region mismatch **Symptom**: Resources not found or deployment fails due to region mismatch. **Solution**: - Verify region with `aws configure get region` - Ensure all resources (agent, models, etc.) are in the same region - Use the `-r` flag during configuration to specify the correct region
Memory provisioning still in progress **Symptom**: Error indicating memory is not yet ready when invoking the agent. **Solution**: - Memory provisioning can take 2-5 minutes, especially for long-term memory (LTM) - Check status with `agentcore status` until memory shows as active - Short-term memory (STM) is available immediately; LTM requires additional setup time

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:

Default: CodeBuild + Cloud Runtime (RECOMMENDED)

Suitable for production, managed environments, teams without Docker:

agentcore launch  # Uses CodeBuild (no Docker needed)

Local Development

Suitable for development, rapid iteration, debugging:

agentcore launch --local  # Build and run locally (requires Docker/Finch/Podman)

Hybrid: Local Build + Cloud Runtime

Suitable for teams with Docker expertise needing build customization:

agentcore launch --local-build  # Build locally, deploy to cloud (requires Docker/Finch/Podman)

Note: Docker is only required for --local and --local-build modes. The default mode uses AWS CodeBuild.

Custom Execution Role

Use an existing IAM role:

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

Why ARM64?

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

  • Default (CodeBuild): Builds ARM64 containers in the cloud - no Docker needed
  • Local with Docker: Only containers built on ARM64 machines will work when deployed to agentcore runtime