AWS Builder Center

Builder Center

Your First Agent with Amazon Bedrock AgentCore

Build and deploy your first AI agent with Amazon Bedrock AgentCore. Use the AgentCore CLI to create a Python Strands agent, test it locally, add a tool, deploy it to AgentCore Runtime, invoke it, read its logs and clean up.

Series: Amazon Bedrock (13 articles)

  1. 1
    Choosing a Foundation Model on Amazon Bedrock: A Practical Comparison
  2. …
  3. 9
    Your First Agent with Amazon Bedrock AgentCore This article
  4. 10
    Giving an AI Agent a Tool Through AWS Lambda
From an empty folder to a deployed agent you can call from the command line, using the AgentCore CLI and a Strands agent in Python.
In the last article we defined what an agent is. Now let's build one. We'll use the AgentCore CLI to scaffold a small Python agent, test it on your machine, deploy it to AgentCore Runtime, call it, check its logs and then clean everything up.
The tooling around AgentCore has changed quickly, and AWS now recommends its npm-based CLI as the way to create, develop and deploy agents. This walkthrough follows the current AWS getting-started guide, so if you've seen older tutorials using a Python "starter toolkit," the commands here will look different.


What you need

  • An AWS account with credentials configured (through the AWS CLI, environment variables or a profile)
  • Node.js 20.12 or later and npm. The CLI is distributed as an npm package, so check with  node --version .
  • Python 3.10 or later, checked with  python3 --version 
  • uv, the Python package manager that the generated project uses
  • IAM permissions to make AgentCore API calls and to assume the CDK bootstrap roles used during deployment. The AgentCore documentation lists the exact permissions under its CLI permissions page.
  • Model access. Amazon Bedrock enables access to foundation models by default, though some models need extra steps. Check the model access page for the one you plan to use.
About forty-five minutes, most of it waiting for the first deployment.
A note before you start. Deploying creates real AWS resources, including a Runtime and, with this template, a Memory resource, and it bootstraps your account for CDK on the first run. Check the current AgentCore pricing page, use a test account if you can, and follow the cleanup step at the end.

Step 1: Install the CLI

Bash
npm install -g @aws/agentcore
agentcore --version
If the second command reports an error instead of a version number, an older Python  agentcore  command may be shadowing the npm one. This happens if you previously installed the  bedrock-agentcore-starter-toolkit  pip package, and it's most common on Windows. The AWS guide says to run  pip uninstall bedrock-agentcore-starter-toolkit , open a new terminal and try again.
Run  agentcore  with no arguments to browse the available commands interactively.

Step 2: Create the project

Bash
agentcore create --name MyProject --template agent-python-strands
This scaffolds a code-based Python agent that uses the Strands Agents SDK and Amazon Bedrock. The command also:
  • creates a Runtime called  agent , along with its application code
  • adds an AgentCore Memory resource
  • installs the dependencies
  • initialises a Git repository
Here's the layout it generates:
Plain text
MyProject/
├── agentcore/
│   ├── .env.local
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── agent/
        ├── main.py
        ├── memory/
        ├── model/
        ├── parse.py
        └── pyproject.toml
The files worth knowing:
File
What it's for
 agentcore/agentcore.json 
The project specification: your runtimes, memory, gateways and other resources
 agentcore/aws-targets.json 
Which AWS account and Region you deploy to
 agentcore/.env.local 
Local secrets, such as API keys for some model providers. Never commit it.
 app/agent/main.py 
The Runtime entrypoint and the agent itself
 app/agent/model/load.py 
The model the agent uses
 app/agent/memory/session.py 
How the agent uses AgentCore Memory
If you run  agentcore create  with no options, an interactive wizard walks you through the choices, including the model provider. Note that passing only  --name  creates a managed harness project instead, in which you describe the agent in a config file and AgentCore runs the loop for you. For a code-based agent like this one, include  --template .

Step 3: Test it locally

Bash
cd MyProject
agentcore dev --mode browser
This starts the Runtime on your machine with hot reload and opens the agent inspector in your browser. Chat with your agent, try a few prompts, and look at the local traces to see what it did on each turn.
Without  --mode browser , the command runs headless and streams output to your terminal. If the default port is already in use, use  --port  to choose another.
This is the cheapest place to find problems, so spend some time here.

Step 4: Give it a tool

An agent with no tools is just a chat model. Open  app/agent/main.py  and look at how the Strands agent is created. In Strands, a tool is an ordinary Python function marked with a decorator, and you pass the functions to the agent. The idea looks like this:
Python
from strands import Agent, tool

@tool
def business_hours(day: str) -> str:
    """Return the opening hours for a given day of the week."""
    hours = {"saturday": "9am to 1pm", "sunday": "closed"}
    return hours.get(day.lower(), "9am to 5pm")

# In the generated file, add your tool to the agent's tools list.
agent = Agent(tools=[business_hours])
The exact layout of  main.py  depends on the template version, so don't paste this over the generated file. Follow the pattern that's already there and add your tool to the agent's tool list. The docstring matters, because the model reads it to decide when to use the tool.
Run  agentcore dev --mode browser  again and ask, "When are you open on Sunday?" In the trace, you should see the model decide to call the tool and use the result.

Step 5: Build and deploy

Bash
agentcore build
agentcore deploy
 agentcore build  validates the project and builds the deployable artifacts.  agentcore deploy  then:
  1. packages your code into a zip
  1. uses AWS CDK to provision the resources
  1. creates an AgentCore Runtime endpoint for your agent
  1. configures CloudWatch logging and observability
The first deploy takes a few minutes because CDK bootstraps your account. Later deploys are faster. Check on it with:
Bash
agentcore status

Step 6: Call your deployed agent

Bash
agentcore invoke --runtime agent --payload '{"prompt":"When are you open on Sunday?"}'
If you get a sensible answer back, your agent is running on AgentCore Runtime.
The edit, test and deploy cycle from here is simple: change  app/agent/main.py , test with  agentcore dev --mode browser , run  agentcore deploy , and invoke it again.

Step 7: See what it did

The CLI can show you logs and traces from the deployed agent:
Bash
agentcore logs runtime
agentcore logs runtime --since 30m --level error
agentcore traces runtime list --since 30m
Get in the habit of reading a trace after every run during development. It shows the model's choices, the tool calls and the time each step took. We'll look at this in more depth in a later article on logging and tracing.

When something goes wrong

Permission denied. Run  aws sts get-caller-identity  to confirm which identity you're using, and check that it has the AgentCore and CDK permissions from the AWS guide.
Model access denied. Some models need extra access steps. Check the model access page for the one in your template.
Port already in use. Use  agentcore dev --port 8081 , and pass the same port when you invoke locally.
A deployment error. Rerun with  agentcore build --debug  and  agentcore deploy --debug  to see more detail.
The  agentcore  command is wrong or missing. Check for the older pip-installed toolkit shadowing the npm command, as described in Step 1.

Clean up

When you're finished experimenting, remove what you created:
Bash
agentcore remove all --yes
agentcore deploy --yes
The first command removes every resource from the project specification. The deploy that follows notices the empty project and tears down the deployed stack. Then check your account for leftovers, such as the CDK bootstrap resources, and look at your bill after a day or two.

What to keep in mind

  • Every agent step is a model call. More tool calls and longer conversations mean higher cost. Watch token usage while you test.
  • Keep permissions small. Your agent can only do what its role allows. Start narrow, and widen only when you have to.
  • Treat tool inputs as untrusted. The model chooses the arguments, so validate them inside your tool.
  • Don't commit secrets. Keep  agentcore/.env.local  out of Git.
  • Things change. AgentCore and its CLI are evolving quickly, so check the current documentation if a command doesn't match.

Where we go next

A tool defined inside your agent's code is a good start. In the next article we'll give an agent a tool that lives in an AWS Lambda function, so the same capability can be reused, secured and updated separately from the agent.
AgentCore features, CLI commands, templates, Regions and pricing change often. Check the current Amazon Bedrock AgentCore documentation before you follow any step here.
# agentic-ai# amazon-bedrock# generative-ai# python

Series: Amazon Bedrock (13 articles)

  1. 1
    Choosing a Foundation Model on Amazon Bedrock: A Practical Comparison
  2. …
  3. 9
    Your First Agent with Amazon Bedrock AgentCore This article
  4. 10
    Giving an AI Agent a Tool Through AWS Lambda
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article