Getting started with AWS Bedrock AgentCore: a practical guide

I was building an agent that could analyze customer support tickets and draft responses. I had the Python code working perfectly on my laptop—LangGraph, a couple of tools, a nice system prompt. Then came the question I kept dodging: "How do we actually run this in production?"

I looked at containerizing it, setting up API Gateway, Lambda, ECS... and honestly, the infrastructure overhead felt ridiculous for what was essentially a script that calls an LLM and runs some tools. That's when I stumbled onto AWS Bedrock AgentCore. The pitch? Write your agent code, run a CLI command, and it's deployed to a managed runtime. I was skeptical, but I tried it. Here's what actually happened.

What AgentCore Actually Is

AgentCore is AWS's managed platform for running AI agents. It handles the infrastructure—provisioning, scaling, security—and gives you a runtime where your agent code lives. There are two ways to use it:

Managed Harness: You declare everything in a config file (model, prompt, tools, memory) and AgentCore runs the agent loop for you. Zero orchestration code. Great if you want the fastest path from idea to running agent.
Code-based Agent: You write the agent loop yourself in Python using whatever framework you already know—Strands, LangGraph, CrewAI, LlamaIndex, OpenAI Agents SDK—and deploy it to the AgentCore Runtime. Full control over orchestration.

I went with the code-based approach because I already had LangGraph code. The harness approach is compelling for simpler cases, but I needed control over my agent's logic.

Prerequisites: The Unsexy Stuff First

Before touching AgentCore, make sure you have these sorted:

Node.js 20+ (the CLI is an npm package—yes, even though your agent code is Python)
npm (comes with Node.js)
Python 3.10+ (for your agent code)
AWS credentials configured (via AWS CLI, environment variables, or a profile)
IAM permissions for AgentCore API calls and CDK bootstrap role assumption

Check your versions:

node --version   # Need v20+
python3 --version  # Need 3.10+

If you haven't bootstrapped CDK in your AWS account yet, you'll need to do that too—AgentCore uses CDK under the hood for deployments.

Step 1: Install the AgentCore CLI

The CLI is distributed as an npm package, which surprised me given that the agent code is Python. But it makes sense—the CLI is a scaffolding and deployment tool, not a runtime dependency.

npm install -g @aws/agentcore-cli

Verify it worked:

agentcore --version

No surprises here. Installed cleanly on my machine.

Step 2: Create Your Project

This is where things got interesting. The CLI scaffolds a complete project for you:

agentcore init my-ticket-agent

It walks you through a few choices—which framework, which model, a project name. I picked LangGraph since that's what my existing code used. The CLI generated a project structure that looked like this:

my-ticket-agent/
├── agent/
│   ├── agent.py          # Your agent code lives here
│   └── requirements.txt  # Python dependencies
├── agentcore.yaml        # Configuration file
└── README.md

The agentcore.yaml file is the heart of the configuration. Here's what mine looked like after scaffolding:

name: my-ticket-agent
runtime: python3.12
framework: langgraph
model: us.anthropic.claude-3-5-sonnet-20241022-v2:0
entrypoint: agent.agent_handler

The entrypoint field points to the function AgentCore calls when your agent is invoked. The scaffolded agent.py comes with a working starter agent—you can modify it or replace it entirely.

I adapted my existing LangGraph agent code into the scaffolded structure. The main thing to know: your entrypoint function needs to accept the request payload and return a response in the format AgentCore expects. The starter code shows you the pattern.

Step 3: Test Locally

This is where I expected pain and was pleasantly surprised. You can test your agent locally before deploying:

agentcore dev

This starts a local development server that mimics the AgentCore Runtime environment. It runs your agent code and exposes a local endpoint you can hit with test requests.

I sent a test request:

curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Analyze this support ticket: Customer can't reset password, getting 500 error"}'

And... it failed. The error was a missing dependency—I'd forgotten to add langchain-aws to my requirements.txt. That's the kind of mistake that's easy to catch locally but annoying to discover after deployment. The local dev mode saved me here.

After fixing the requirements, it worked. My agent processed the ticket and returned a structured response. The local testing experience was smooth—changes to your Python code reload automatically, which makes the dev loop fast.

Step 4: Deploy Your Agent

Once I was happy with local testing, deployment was one command:

agentcore deploy

This is where AgentCore earns its keep. Under the hood, it:

Packages your agent code and dependencies
Creates an AgentCore Runtime resource
Sets up the necessary IAM roles and permissions
Deploys everything using CDK

The first deployment took about 3-4 minutes. Subsequent deployments were faster. The CLI outputs the runtime endpoint URL and agent ID when it's done.

One thing that caught me off guard: the first deployment in a region requires CDK bootstrapping, which creates an S3 bucket and a few other resources. If you haven't bootstrapped CDK in that region before, the CLI handles it, but it adds time and you need the IAM permissions for it.

Step 5: Invoke Your Deployded Agent

With the agent deployed, you can invoke it via the AWS SDK. Here's how I called it from Python:

import boto3
import json

client = boto3.client('bedrock-agentcore')

response = client.invoke_agent(
    agentId='my-ticket-agent',
    sessionId='test-session-001',
    inputText='Analyze this support ticket: Customer can\'t reset password, getting 500 error'
)

result = json.loads(response['response'])
print(result)

You can also invoke it via the CLI:

agentcore invoke \
  --agent-id my-ticket-agent \
  --session-id test-session-001 \
  --input "Analyze this support ticket: Customer can't reset password, getting 500 error"

The first real invocation took a few seconds—cold start. Subsequent calls were faster. The response format matches what I saw in local testing, which was a relief.

Adding Capabilities

Once the basic agent is running, AgentCore lets you bolt on additional capabilities through its modular services:

Memory: Persist conversation state across sessions
Gateway: Connect to external APIs and data sources
Browser: Give your agent web browsing capabilities
Code Interpreter: Let your agent execute code in a sandboxed environment
Observability: Log traces and monitor agent performance

I haven't added all of these yet, but the observability integration was straightforward—logs and traces show up in CloudWatch automatically after deployment.

Honest Assessment

What worked well:

The CLI-driven workflow is genuinely fast. I went from zero to a deployed agent in under 30 minutes, including my mistakes.
Local testing with agentcore dev is excellent. Catching that missing dependency locally saved me a deployment cycle.
Framework agnosticism is real. I used LangGraph, but the same workflow works with Strands, CrewAI, or others.
No infrastructure management. I didn't touch ECS, Lambda, or API Gateway.

Limitations I hit:

The CLI requires Node.js even though your agent is Python. It's a minor annoyance, but worth knowing.
Cold starts are noticeable—a few seconds on first invocation. Not terrible, but not instant either.
The harness approach is simpler but less flexible. If your agent logic is non-trivial, you'll want the code-based path.
Documentation is still maturing. I ran into a couple of edge cases with the YAML config that required digging into AWS docs.
You're locked into the AgentCore Runtime abstraction. If you need very specific infrastructure control, this might feel constraining.

Practical tips:

Test locally first. Always. The agentcore dev command saves you from deploying broken code.
Be explicit in requirements.txt. Local Python environments can mask missing dependencies.
Start with the scaffolded code and modify incrementally. Don't try to port a massive existing codebase all at once.
Watch your IAM permissions. The deploy command needs more permissions than you might expect because it creates infrastructure.
Use the observability features early. Traces in CloudWatch are invaluable for debugging agent behavior in production.

AgentCore isn't going to replace hand-crafted infrastructure for every use case. But for getting an agent from your laptop to a production endpoint without writing a single CloudFormation template? It does exactly what it promises.