DEV Community

Scott Peterson
Scott Peterson

Posted on

Start Simple: Deploying Your First Agent with the Amazon Bedrock AgentCore CLI

It can be intimidating to start your journey with AI. The best way to start is by building something simple.

I spent years in DevOps, first as an engineer keeping systems up, then as Director of DevOps at MX, a fintech company, and later leading cloud operations at Wonolo, a California-based company running on AWS. In every one of those roles, the same question came up: how many nines can we guarantee to the customers who depend on our software?

"Nines" is how availability gets measured. 99.9% uptime, or three nines, allows about 8.8 hours of downtime a year. Four nines (99.99%) allows about 53 minutes. Each extra nine cuts your allowed downtime by a factor of ten, and it gets much harder and more expensive to deliver.

AWS has great uptime, and its SLAs reflect that. EC2 commits to 99.99% monthly uptime at the region level. But there's a condition: that commitment applies when you run across two or more Availability Zones. A single instance is covered at 99.5%.

Great uptime metrics don't mean there will never be an occasional issue. That's why you architect your system to operate in multiple Availability Zones, so a problem in one zone doesn't take your application down with it.

Part of designing for it is knowing what's happening. You can't answer the nines question honestly without knowing when your provider is having a problem. Whenever something broke, the first thing I wanted to know was whether it was us or AWS.

So when I wanted to build a simple agent, this one made sense. It has exactly one job: check the public AWS Health Dashboard. Ask it, "Is anything broken in us-east-1?" and it fetches the live feed and tells you.

It runs on Amazon Bedrock AgentCore, uses the Strands Agents SDK, and goes from an empty folder to deployed with the AgentCore CLI.

You can start with something simple that uses good software engineering practices and build on it.

Sample repo: scooteronce/agentcore-first-agent

Before you start

Please read this. Deploying creates real AWS resources in your account. They cost very little at this scale, but they aren't free. The cleanup section at the end removes everything.

You'll need:

  • Node.js 20.12 or later, for the AgentCore CLI
  • uv, for the Python agent
  • AWS credentials with permission to deploy (AdministratorAccess, or PowerUser plus IAM role creation)
  • Amazon Bedrock model access to Claude Haiku 4.5

Step 1: Install the CLI and scaffold the project

Install the CLI, pinned to a specific version:

npm install -g @aws/agentcore@1.0.3
Enter fullscreen mode Exit fullscreen mode

Pinning your version is important for this tutorial. The CLI is moving fast, and a tutorial that works on "latest" today may not work next month. If you're following along, use the same version I did.

Then scaffold the project:

agentcore create --name FirstAgent --template agent-python-strands
Enter fullscreen mode Exit fullscreen mode

Step 2: Understand what you've got

The scaffold gives you a working setup you can easily build on. Here's what's in it:

  • agentcore/agentcore.json is the project spec. It defines one runtime (Python, Bedrock, HTTP) and one memory resource.
  • agentcore/cdk/ is a TypeScript CDK app. agentcore deploy builds and runs it for you.
  • app/agent/ is the Python agent, as a uv project.

Inside the agent:

  • main.py defines the tool and the entrypoint.
  • model/load.py picks the model.
  • memory/session.py wires up AgentCore Memory.

You don't have to touch the CDK to get started. It's worth knowing it's there, because that's what actually creates your infrastructure.

Step 3: Write the tool

The agent's whole point is one custom tool: check_aws_health. It's a plain Python function with a Strands @tool decorator. It fetches the public feed at https://health.aws.amazon.com/public/currentevents, optionally filters by region, and formats the results for the model.

Two things about the feed surprised me.

It's UTF-16 encoded, not UTF-8. If you decode it the usual way, you get garbage.

The region code isn't where you'd expect. Each event has a region_name field, but it holds a human label like "UAE." The actual region code, like me-central-1, lives in the arn and service fields. So the filter looks like this:

events = [
    e for e in events
    if needle in e.get("arn", "").lower() or needle in e.get("service", "").lower()
]
Enter fullscreen mode Exit fullscreen mode

That looks wrong at first glance, but it isn't. I will talk about that more below.

The model is set in model/load.py:

BedrockModel(model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0")
Enter fullscreen mode Exit fullscreen mode

Haiku is plenty for this. Start with the cheapest model that does the job, and move up only when you have a reason.

Step 4: Run it locally

Start the local dev server:

agentcore dev
Enter fullscreen mode Exit fullscreen mode

It prints a port number. Use that port to invoke the agent:

agentcore invoke --runtime agent --local --port NNNN \
  --payload '{"prompt": "Is anything broken in us-east-1?"}'
Enter fullscreen mode Exit fullscreen mode

Locally, the agent runs without memory. memory/session.py reads the memory ID from environment variables that only the deployed runtime sets. If they're missing, it returns None and the agent runs stateless. There are no mocks, flags, or special local config.

Step 5: Deploy

agentcore deploy
Enter fullscreen mode Exit fullscreen mode

Under the hood, this is CDK. The first run records your account and region in agentcore/aws-targets.json and creates the CDK bootstrap stack if your account doesn't have one. After that, deploys are idempotent.

Then check that the deploy succeeded:

agentcore status
Enter fullscreen mode Exit fullscreen mode

Step 6: Invoke and observe

Invoke the deployed agent:

agentcore invoke --runtime agent \
  --payload '{"prompt": "Is anything broken in us-east-1?"}'
Enter fullscreen mode Exit fullscreen mode

Then look at what happened:

agentcore logs
agentcore traces
Enter fullscreen mode Exit fullscreen mode

Traces are where you should spend your time. You can see when the model decided to call the tool, what it passed, and what came back. That's how you learn how agents actually behave, instead of guessing.

The deployed agent also has memory. AgentCore Memory is configured with two strategies: semantic, which stores facts per user, and episodic, which stores what happened per session. You get both without writing any storage code.

Good habits, even on a small project

None of this is AI-specific. It's just good software engineering, and a small project is the cheapest place to practice it.

Keep account details out of git. agentcore/aws-targets.json and agentcore/.cli/ contain your AWS account ID. They're gitignored, and the first deploy regenerates them. The CDK app resolves account and region at deploy time, so nothing is hardcoded.

Pin your versions. The CLI, the CDK construct library, and the Python dependencies are all pinned, and uv.lock is committed. Anyone who clones the repo gets the same build I tested.

Write tests for the code you own. I don't unit test the model's decisions. That's the framework's job, and a local invoke covers it. But the tool, the payload parsing, and the memory wiring are all deterministic code I wrote, so they get tests. There are thirty of them, and they run in half a second with no AWS credentials.

Use tests to record decisions. Remember the region filter that looks wrong? I almost "fixed" it to filter on region_name. That would have meant checking whether "me-central-1" is in "UAE", which is never true. Region filtering would have silently broken.

Now there's a test that feeds the tool a us-east-1 event and a me-central-1 event, filters for me-central-1, and checks that only one comes back. Anyone who "fixes" that line will find out immediately. The mocked feed is UTF-16 too, so nobody can "clean up" the decode line without a test failing.

A test is the one place you can permanently record why code is shaped the way it is.

Gotchas and lessons learned

Import-time environment variables. memory/session.py reads its config when the module loads. That makes it awkward to test, because changing the environment after import does nothing. If you're writing your own, read environment variables inside the function.

The local port changes. agentcore dev picks a port each run. Copy it from the output instead of hardcoding it.

The scaffold README is generic. It's fine to leave, but write your own top-level README. Future you will want to know how to run, deploy, and clean up without rereading the CLI docs.

What it costs

AgentCore Runtime and Bedrock are billed on usage, so a handful of test invocations on Haiku costs very little. Memory and logs add a small amount on top. Nothing runs when nobody's calling it.

Check the AgentCore pricing page for current rates, and clean up when you're done.

Clean up

agentcore remove all --yes
agentcore deploy --yes
git checkout agentcore/agentcore.json
Enter fullscreen mode Exit fullscreen mode

The first command removes the resources from the spec. The second deploys that empty spec, which deletes the stack. The third restores the spec so you can deploy again later.

The shared CDKToolkit bootstrap stack stays. Other CDK projects in your account may depend on it.

Taking it further

This is where starting simple pays off. The agent already works, so you can build on it.

One idea I like is integrating it into a Slack channel for your SREs. When something looks off, they can ask the agent whether AWS is having an issue in their region instead of digging through the Health Dashboard themselves. You could also run it on a schedule and have it post to the channel only when there's an active issue in a region you care about.

That answers "is it us or AWS?" before anyone has to ask.

Wrapping up

  • Start simple. Build one agent with one tool and one clear job. Get that working end to end, then build from there.
  • Let the CLI do the plumbing. Scaffold, run locally, deploy, and observe without writing infrastructure code.
  • Read the traces. That's where you learn how agents actually make decisions.
  • Engineer it like it matters. Pin versions, keep secrets out of git, and test the code you own.

If you're just getting started with agents, I'd like to hear what you're building. Drop a comment, and follow along for more AWS and applied AI posts.

Sources

Top comments (0)