Forem: Claudio Guerra

Getting Started with AWS Bedrock AgentCore (preview)

Claudio Guerra — Thu, 02 Oct 2025 06:12:21 +0000

Introduction

Usually software processes data in a predefined way and follows specific steps to complete a task. In contrast, AI agents can perceive, decide, and act, making them a powerful primitive that allows us to take user-defined input, break down a request into multiple tasks, and solve them dynamically. This enables a much more flexible interaction with the user.

Although AI agents offer many benefits and capabilities, and they can be easily prototyped locally using frameworks like LangChain/LangSmith, deploying them to production can be a significant challenge. This is because we need to address aspects such as scaling, session management, tool access, security, and memory management, among others.

AWS Bedrock AgentCore (preview) is a collection of composable services that you can use to build and deploy AI agents securely and at scale. Each AgentCore service addresses different aspects of agents in production, but you can choose not to use all of them. This is useful so that you are not vendor-locked if there is something you want to implement differently or if you already have an agentic solution implemented and have some of these angles already addressed with something different.

⚠️ DISCLAIMER: AgentCore is still in preview, which means that it is not recommended to use with production workloads yet, since things might change once we reach GA, but it is a good opportunity to experiment and learn.

AgentCore services

AgentCore Runtime is where you can deploy and run agents and MCP tools in AWS. Runtime uses Fargate as a backend, meaning that it will scale automatically, and Runtime will manage sessions automatically and, running each session in isolation in a different microVM.

AgentCore Gateway allows agents to discover tools and other agents to interact with. Gateway also allows exposing lambda functions, internal APIs, other AWS services, and external APIs, all as MCP tools, so that they can be accessed by agents in a standard way.

AgentCore Identity provides inbound security, ensuring that only authorized users can use a given agent, and outbound security, making sure that a given agent only uses the tools it is authorized to use.

AgentCore Memory abstracts away short-term and long-term memory management for agents, short-term memory for multi-turn conversations, and long-term memory to allow the agent to learn from conversations, which can be shared amongst multiple agents.

AgentCore Builtin Tools is a set of tools readily available for agents, like Browser Tool and Code Interpreter.

AgentCore Observability is allows for agent instrumentation compatible with OpenTelemetry to be able to trace, debug, and monitor agents in Cloudwatch.

Creating an agent

Here, we will take an incremental approach, allowing you to see how simple it is to start working with agents and how composable each AgentCore service is.

Now we will start by creating an agent

# Install dependencies
python -m venv .venv
source .venv/bin/activate

pip install bedrock-agentcore bedrock-agentcore-starter-toolkit strands-agents strands-agents-tools aws-opentelemetry-distro~=0.10.1
pip freeze > requirements.txt

Here is the agent code where we will be using the Strands Agents SDK, but you could also use other agent frameworks such as LangChain/LangGraph or CrewAI.

# agent.py
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()

@app.entrypoint
def invoke(payload):
    """Agent function"""
    user_message = payload.get("prompt")
    result = agent(user_message)
    return {"result": result.message}

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

Then we can run it locally

# Start agent
python agent.py

# Run it locally
curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello"}'
# {"result": {"role": "assistant", "content": [{"text": "Hello! It's nice to meet you. How are you doing today? Is there anything I can help you with?"}]}}

Now, to deploy our agent to AWS, we will leverage the AgentCore toolkit, which simplifies details regarding configuration and deployment.

AgentCore Runtime uses containers to provide compute capacity for your agents; therefore, the agentcore config command will create a .bedrock-agentcore.yaml file containing all the needed configuration to be used when deploying the agent to AWS, along with a Dockerfile for the container in which the agent will be executed.

Then, the agentcore launch command will use AWS Codebuild to create the agent container image, then push it to an AWS ECR repository, and finally have the agent runtime use this image. AgentCore Runtime will create a new agent version and will use a Runtime Endpoint to point to the right version, allowing for rollback if needed.

# Deploy
agentcore configure -e agent.py -r us-east-1
agentcore launch

Then, almost the same way we did it locally, we can run the agent, but this time using AgentCore Runtime in AWS.

# Run it remotely
agentcore invoke '{"prompt": "tell me a joke"}'
# {"result": {"role": "assistant", "content": [{"text": "Why don't scientists trust atoms?\n\nBecause they make up everything!"}]}}

Here we can see how simple it is to start using the AgentCore Runtime

Full code example here.

Tools

Agents in Runtime can gain additional capabilities quickly by leveraging AgentCore Built-in tools, a set of MCP tools made available by AWS for agents to utilize.

Browser tool

This is a headless browser that agents can use, which runs in an isolated ephemeral environment

# agent.py
from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent
from strands_tools.browser import AgentCoreBrowser

app = BedrockAgentCoreApp()
agent_core_browser = AgentCoreBrowser()
agent = Agent(tools=[agent_core_browser.browser])

@app.entrypoint
def invoke(payload):
    """Agent function"""
    user_message = payload.get("prompt")
    result = agent(user_message)
    return {"result": result.message}

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

Building a CRM with AWS SAM, part 2: Creating a contact

Claudio Guerra — Wed, 23 Jul 2025 16:00:00 +0000

In the previous post we stood up a basic /ping health‑check endpoint to confirm our SAM project was wired correctly.

Today we will build our first real piece of CRM functionality: a POST /contacts endpoint that stores a contact record in Amazon DynamoDB, now powered by AWS Lambda Powertools for structured logging, tracing, and metrics.

The API Contract

Request POST /contacts

{
  "email": "jane.doe@example.com",   // required
  "name": "Jane Doe",                // optional
  "phone": "+11234567890",           // optional
}

Response 201 Created

{
  "id": "c8a5c3d1-2bfe-45d0-b7e3-6d1fb25ce9a7",
  "email": "jane.doe@example.com",
  "name": "Jane Doe",
  "phone": "+11234567890",
  "created_at": 1721340000,
  "updated_at": 1721340000
}

We return the full record, including generated fields such as id, created_at, and updated_at

Designing the Data Model

For now we will use a DynamoDB table named ContactsTable with:

Attribute	Purpose	Key type
`pk`	contact ID (UUID)	PartitionKey
`sk`	static value `METADATA`	SortKey
other attributes	email, name, etc	(projected)

In DynamoDB, the partition key (pk) decides which storage partition the item belongs to, while the sort key (sk) lets us order or group multiple items that share that same partition. By using a fixed sk value like METADATA for the main contact record today, we reserve the option to add related entities—such as notes or tags—under the same pk but with different sk values later on.

Dependency management

We will create a python virtual environment per lambda function, so that we can manage their package versions in isolation.

Create and activate the venv

python -m venv venvs/contacts
source venvs/contacts/bin/activate

Install the dependencies and lock them:

pip install "aws-lambda-powertools[all]"
pip freeze > src/functions/contacts/requirements.txt

sam build will detect requirements.txt and bundle these exact versions into the deployment artifact.

Contacts Lambda function

The lambda function will recieve a payload with the contact data which will be validated with pydantic, then we store the contact data in DynamoDB where we're abstracting away all the data access logic by following the repository pattern, and finally we return the contact in the response, including system generated attributes such as id, created_at, and updated_at.

File structure:

src/functions/contacts/
├─ app/
|  ├─ __init__.py
|  ├─ main.py                # Lambda entry‑point
|  ├─ models.py              # Pydantic models
|  └─ repository.py          # Data‑access abstraction
├─ __init__.py
├─ requirements.txt          # Locked package dependencies
└─ events/
   └─ create_contact.json    # API Gateway payload for testing

models.py

from pydantic import BaseModel, EmailStr
from typing import Optional

class CreateContactRequest(BaseModel):
    email: EmailStr
    name: Optional[str] = None
    phone: Optional[str] = None

class Contact(BaseModel):
    id: str
    email: EmailStr
    name: Optional[str] = None
    phone: Optional[str] = None
    created_at: str
    updated_at: str

repository.py

import os, uuid
from datetime import datetime, timezone
import boto3
from .models import CreateContactRequest, Contact

class ContactRepository:
    def __init__(self):
        self.contacts_table_name: str = os.environ.get("CONTACTS_TABLE_NAME")
        self.contacts_table = boto3.resource("dynamodb").Table(self.contacts_table_name)

    def create(self, create_contact_request: CreateContactRequest) -> Contact:
        now = datetime.now(timezone.utc).isoformat()
        contact_id = str(uuid.uuid4())

        item = {
            "pk": contact_id,
            "sk": "METADATA",
            **create_contact_request.model_dump(),
            "created_at": now,
            "updated_at": now,
        }

        self.contacts_table.put_item(Item=item, ConditionExpression="attribute_not_exists(pk)")

        return Contact(
            id=contact_id,
            **create_contact_request.model_dump(),
            created_at=now,
            updated_at=now
        )

main.py

from aws_lambda_powertools import Logger, Metrics, Tracer
from aws_lambda_powertools.metrics import MetricUnit
from aws_lambda_powertools.event_handler import APIGatewayRestResolver, CORSConfig
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing import LambdaContext
from typing import Dict, Any
from .models import CreateContactRequest, Contact
from .repository import ContactRepository

tracer = Tracer()
logger = Logger()
metrics = Metrics()

contact_repository = ContactRepository()

cors_config = CORSConfig(allow_origin="*", max_age=300)
app = APIGatewayRestResolver(cors=cors_config, enable_validation=True)

@app.post("/contacts")
@tracer.capture_method
def create_contact(create_contact_request: CreateContactRequest) -> Contact:
    contact = contact_repository.create(create_contact_request)
    metrics.add_metric(name="ContactsCreated", unit=MetricUnit.Count, value=1)
    tracer.put_annotation("contact_id", contact.id)
    return contact, 201

@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
@tracer.capture_lambda_handler
@metrics.log_metrics(capture_cold_start_metric=True)
def lambda_handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
    return app.resolve(event, context)

@app.exception_handler(Exception)
@tracer.capture_method
def handle_exception(ex: Exception):
    logger.exception("Internal server error", extra={"error": str(ex)})
    return {"message": "Internal server error"}, 500

Build, test, deploy

In addition to testing the endpoint with curl, we’ll run the Lambda function locally. That requires passing it a mock event. Because the function is invoked by API Gateway in production, the mock event must replicate the JSON payload that API Gateway sends to the Lambda.

// src/functions/contacts/events/create_contact.json
{
    "httpMethod": "POST",
    "path": "/contacts",
    "headers": {
        "Content-Type": "application/json"
    },
    "requestContext": {
        "httpMethod": "POST"
    },
    "body": "{\"email\": \"jane.doe@example.com\", \"name\": \"Jane Doe\", \"phone\": \"+11234567890\"}",
    "isBase64Encoded": false
}

we also need a .env file with the values of the lambda function's environment variables for when we run it locally

// .env
{
    "ContactsFunction": {
        "CONTACTS_TABLE_NAME": "crm-sam-contacts-table"
    }
}

and now we can proceed to build

sam build

run the lambda function locally

sam local invoke ContactsFunction \
  -e src/functions/contacts/events/create_contact.json
  -n .env

{"statusCode": 201, "body": "{\"id\":\"788c7d86-30a6-46da-9550-27e42f7686cd\",\"email\":\"jane.doe@example.com\",\"name\":\"Jane Doe\",\"phone\":\"+11234567890\",\"created_at\":\"2025-07-20T14:59:28.811723+00:00\",\"updated_at\":\"2025-07-20T14:59:28.811723+00:00\"}", "isBase64Encoded": false, "multiValueHeaders": {"Content-Type": ["application/json"]}}

run the API locally

sam local start-api
curl -X POST http://127.0.0.1:3000/contacts \
     -H 'Content-Type: application/json' \
     -d '{"email":"alice@example.com","name":"Alice"}'

{"id":"ac1c51b7-2fe6-495f-8578-70c123c8927f","email":"alice@example.com","name":"Alice","phone":null,"created_at":"2025-07-20T15:11:21.174541+00:00","updated_at":"2025-07-20T15:11:21.174541+00:00"}

and deploy it

sam deploy
curl -X POST https://uywf3xcoej.execute-api.us-east-1.amazonaws.com/prod/contacts \
     -H 'Content-Type: application/json' \
     -d '{"email":"bob@example.com","name":"Bob"}'

{"id":"a7ea3b2c-6b7c-422a-b8eb-36795f39e537","email":"bob@example.com","name":"Bob","phone":null,"created_at":"2025-07-20T15:15:29.276161+00:00","updated_at":"2025-07-20T15:15:29.276161+00:00"}

What did we learn?

Use of AWS Lambda Powertools to simplify the lambda function code
Use of pydantic for data validation
Use of the repository pattern to abstract data access logic
Dependency management for lambda functions

And with that, we already have the first CRM feature. If you want to see the code of the project, you can find it here, and if you have and suggestion or feedback, let me know in the comments.

Coming next

Now that we can create contacts, in part 3 we will retrieve them (GET /contacts), add pagination, and explore query patterns.

Building a CRM with AWS SAM, part 1: ping

Claudio Guerra — Sat, 19 Jul 2025 14:15:55 +0000

Welcome to the first post in a series where I’ll walk through building a CRM (Customer Relationship Management) system using AWS SAM. We’ll progressively create a serverless backend, focusing on clean architecture, scalability, and cost optimization.

In this post, we'll set up our project and create a /ping health check endpoint to make sure everything is working.

Why Serverless and SAM?

One of the biggest benefits of serverless is that you don't need to worry about infrastructure maintenance, instead you assemble your system with serverless primitives that can scale based on demand, and therefore, you pay only for the resources you use.

AWS SAM (Serverless Application Model) simplifies serverless app deployment. SAM consists of the SAM CLI that helps test, build and deploy, and also SAM templates, which offers abstractions on top of the AWS Cloudformation syntax.

Project Setup

Let’s start by creating the simplest piece of functionality: a ping endpoint that returns "pong". This will serve as our health check route and confirm everything is wired correctly.

Folder structure:

├─ src/
│  └─ functions/
│    └─ ping/             # Ping function code
│      ├─ __init__.py
│      └─ app             # Ping function module
│        ├─ __init__.py
│        └─ main.py       # Lambda handler
├─ samconfig.toml         # SAM configuration
└─ template.yml           # SAM template

We'll start with the most important piece of the puzzle, the SAM template, where we define all the infrastructure components our application will have, all defined as code (IaC), that means that we can version and track infrastructure changes in our git repository.

# template.yml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: CRM SAM

Resources:
  ApiGateway:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod

  PingFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/functions/ping/
      Handler: app.main.lambda_handler
      Runtime: python3.13
      Events:
        Ping:
          Type: Api
          Properties:
            RestApiId: !Ref ApiGateway
            Path: /ping
            Method: GET

Outputs:
  PingUrl:
    Description: URL to ping endpoint
    Value: !Sub "https://${ApiGateway}.execute-api.${AWS::Region}.amazonaws.com/prod/ping"

In this template we can see we're defining the Resources we're gonna be using, which in this case are:

ApiGateway: an AWS::Serverless::Api that receives requests to be resolved by a lambda function, and then takes its response and hands it back to the caller.
PingFunction: an AWS::Serverless::Function that will be resolving the ping request and will create the response to be then returned by the API Gateway.

Here we can already notice a common theme, all resources are comprised by a Type which let's us define what kind of resource we're talking about, and Properties which corresponds to the configuration we'll be giving to that particular resource.

At the bottom we can also notice the Outputs section in which we can get different values from the resources that get generated at deployment time, which can be for reference or which can also be passed to other stacks in case we're building something more complex that involves multiple templates, in this case we're outputing the url we can hit to reach the ping function.

Now here's the code of the Lambda function:

# src/functions/ping/app/main.py
def lambda_handler(event, context):
    return {
        "statusCode": 200,
        "headers": {"Content-Type": "application/json"},
        "body": '{"response": "pong"}'
    }

Very minimal, just returns a status code 200 and "pong" in the body.

Finally, we have the samconfig.toml file where we configure parameters for different sam commands.

version = 0.1

[default]
[default.global.parameters]
stack_name = "crm-sam"
region = "us-east-1"

[default.build.parameters]
cached = true
parallel = true

[default.validate.parameters]
lint = true

[default.local_start_api.parameters]
warm_containers = "EAGER"
tags = "application=crm-sam"

[default.local_invoke.parameters]
tags = "application=crm-sam"

[default.logs.parameters]
tail = true

[default.deploy.parameters]
capabilities = ["CAPABILITY_IAM"]
confirm_changeset = false
resolve_s3 = true
s3_prefix = "crm-sam"
image_repositories = []

Running it locally.

Before running anything you always need to build the application:

sam build

Then you can run the project locally by using:

sam local start-api

and then if you curl the endpoint with:

curl http://localhost:3000/ping

you should get the following response

{"response": "pong"}

Finally, you can deploy it to AWS by just running

sam deploy

at the end of the deployment output you should see something like:

CloudFormation outputs from deployed stack
-------------------------------------------------------------------
Outputs                                                                                         
-------------------------------------------------------------------
Key                 PingUrl                                                                     
Description         URL to ping endpoint                                                        
Value               https://uywf3xcoej.execute-api.us-east-1.amazonaws.com/prod/ping            
-------------------------------------------------------------------

which you can also curl

curl https://uywf3xcoej.execute-api.us-east-1.amazonaws.com/prod/ping
{"response": "pong"}

What did we learn?

How to scaffold a minimal SAM project
How to define a Lambda function
How to expose a route using API Gateway
How to test it locally and deploy it

This simple GET /ping endpoint is the starting point of our CRM, from here, we'll expand into real CRM functionality.

I'll keep the code for this series in this repo, and the code for this post can be found here.

Coming Next

In the next post, we will create the first feature of our CRM: a POST /contacts endpoint to store contact information in AWS DynamoDB.

Forem: Claudio Guerra

Getting Started with AWS Bedrock AgentCore (preview)

Introduction

AgentCore services

Creating an agent

Tools

Browser tool

Building a CRM with AWS SAM, part 2: Creating a contact

The API Contract

Designing the Data Model

Dependency management

Contacts Lambda function

Build, test, deploy

What did we learn?

Coming next

Building a CRM with AWS SAM, part 1: ping

Why Serverless and SAM?

Project Setup

Running it locally.

What did we learn?

Coming Next

Building a CRM with AWS SAM, part 2: Creating a contact