Introducing Amazon AgentCore Local Blocks — build and test before you deploy
What if you could run Amazon Bedrock AgentCore Memory, Gateway, and Identity on your laptop, for a **$0 bill** — and ship the *same code* to real AWS unchanged?
Introducing Amazon AgentCore Local Blocks — build and test before you deploy
What if you could run Amazon Bedrock AgentCore Memory, Gateway, and Identity on your laptop, for a $0 bill — and ship the same code to real AWS unchanged?
🚀 It's live as a Pull Request — try it today➡️aws-devtools-labs/aws-blocks— PR #122 : feat(agentcore): add AgentCore Memory, Gateway, and Identity Building BlocksThree new Building Blocks + two demo apps. Passes the full CI gate suite, and isverified end-to-end on real Amazon Bedrock AgentCore (all fiveAWS::BedrockAgentCore::*resources deployed and round-tripped). Clone the branch andnpm test— no AWS account needed for the local loop.Status: 🟢 Open · ✅ Mergeable (no conflicts) · 👀 Awaiting review · 🧪 Local gate
suite green —build·test:unit(34 tests) ·lint:deps·check:exports-consistency
·check:api· +4,635 / −102 across 69 files, 1 commit.
TL;DR — I built three custom AWS Blocks that bring Amazon Bedrock AgentCore into
a local-first development loop:AgentCoreMemory,AgentCoreGateway, andAgentCoreIdentity. Locally they simulate AgentCore in-process (no AWS account, no
Docker, no bill). In production, the exact same lines of code talk to realAWS::BedrockAgentCore::*resources. It's tested end-to-end — 27 unit tests and a
real deploy to AWS — and it's up as a pull request you can try today.
Join AWS User Group Madurai and learn about AWS Blocks with hands-on demos: https://www.meetup.com/aws-user-group-madurai/events/315458595/?eventOrigin=group_upcoming_events
The problem: agent infrastructure has a slow inner loop
Amazon Bedrock AgentCore is a fantastic set of primitives for production agents —
Memory (short-term events + long-term semantic recall), Gateway (turn your APIs
and Lambdas into MCP tools), and Identity (workload identity + outbound
credentials). But the development loop for agent infrastructure tends to look like
this:
Memory (short-term events + long-term semantic recall), Gateway (turn your APIs
and Lambdas into MCP tools), and Identity (workload identity + outbound
credentials). But the development loop for agent infrastructure tends to look like
this:
1
2
3
edit code ──▶ cdk deploy ──▶ wait 2–4 min ──▶ invoke ──▶ read logs ──▶ repeat
▲ │
└──────────────────── 💸 and a real AWS bill ◀──────────┘Every iteration on "does my agent remember the right thing?" or "is this tool wired
correctly?" costs minutes and money. You want to be in the agent loop, not in the
deploy loop.
correctly?" costs minutes and money. You want to be in the agent loop, not in the
deploy loop.
What if the inner loop looked like this instead?
1
edit code ──▶ npm test ──▶ 0.3s ──▶ repeat ($0, offline, deterministic)…and the code you tested that way deployed to real AgentCore with zero changes.
That's the idea.
The foundation: AWS Blocks
AWS Blocks is a backend toolkit where
each "Block" is a self-contained capability that bundles three implementations behind
one class name, selected automatically by the execution context using Node.js
conditional exports:
each "Block" is a self-contained capability that bundles three implementations behind
one class name, selected automatically by the execution context using Node.js
conditional exports:
1
2
3
4
5
6
7
8
┌──────────────────────────────────────────┐
new AgentCoreMemory(scope, 'mem', {...}) │
│ │
npm test ─────┼─▶ index.mock.ts in-process sim ($0)│
cdk deploy ────┼─▶ index.cdk.ts CloudFormation │
Lambda ────┼─▶ index.aws.ts real AWS SDK calls │
browser ────┼─▶ index.browser.ts server-only stub │
└──────────────────────────────────────────┘The same
table at deploy, and SDK calls in production. AWS Blocks proves the local-to-cloud
"same code" model works. AgentCore was missing from the catalog — so I added it.
new KVStore(scope, 'todos') line is an in-memory store in dev, a DynamoDBtable at deploy, and SDK calls in production. AWS Blocks proves the local-to-cloud
"same code" model works. AgentCore was missing from the catalog — so I added it.
The idea conceived: AgentCore as Blocks
AgentCore already ships a local development story (a Docker-based runtime + CLI). The
insight here is to take that spirit — "develop the whole agent loop offline" — and
express it as first-class AWS Blocks, so AgentCore composes with the rest of your
backend and needs no Docker at all for the inner loop.
insight here is to take that spirit — "develop the whole agent loop offline" — and
express it as first-class AWS Blocks, so AgentCore composes with the rest of your
backend and needs no Docker at all for the inner loop.
Three blocks, one contract each:
🧠 AgentCoreMemory — your agent remembers, locally
Short-term events and long-term semantic memory (facts, preferences, summaries),
organized by
organized by
actorId / sessionId / namespace — exactly the AgentCore data model.1
2
3
4
5
6
7
8
9
const memory = new AgentCoreMemory(scope, 'assistant-memory', {
strategies: [
{ type: 'semantic', name: 'facts' },
{ type: 'userPreference', name: 'preferences' },
],
});
await memory.createEvent({ actorId, sessionId, role: 'USER', text: 'I use Python.' });
const hits = await memory.retrieveMemories({ namespace: `/facts/${actorId}`, query: 'language?' });Locally, "extraction" and "retrieval" run with deterministic heuristics (lexical
similarity). On AWS, the same calls hit the AgentCore data plane and retrieval becomes
truly semantic — the API, namespaces, and data model are identical.
similarity). On AWS, the same calls hit the AgentCore data plane and retrieval becomes
truly semantic — the API, namespaces, and data model are identical.
🔌 AgentCoreGateway — your functions become MCP tools
1
2
3
4
5
6
7
8
9
10
11
12
const gateway = new AgentCoreGateway(scope, 'tools', {
tools: {
get_weather: {
description: 'Get the current weather for a city.',
inputSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
handler: async ({ city }) => fetchWeather(city as string),
},
},
});
await gateway.listTools(); // MCP tools/list
await gateway.callTool('get_weather', { city: 'Berlin' }); // MCP tools/callLocally it simulates the aggregated MCP server in-process. On AWS it provisions a real
Gateway + Lambda target and exposes the same tools at a real MCP endpoint for
external agents.
Gateway + Lambda target and exposes the same tools at a real MCP endpoint for
external agents.
🔑 AgentCoreIdentity — credentials without handling secrets
Workload identity (inbound) plus outbound API-key / OAuth2 credential providers, so your
tools reach downstream services without your code ever touching raw secrets.
tools reach downstream services without your code ever touching raw secrets.
How a Block flows from laptop to cloud
1
2
3
4
5
6
7
8
9
10
11
aws-blocks/index.ts (you write this once)
│
├── npm test ──────▶ index.mock.ts ──▶ .bb-data/ (local JSON) $0
│
└── cdk deploy ────▶ index.cdk.ts ──▶ CloudFormation
├─ AWS::BedrockAgentCore::Memory
├─ AWS::BedrockAgentCore::Gateway (+Target)
├─ AWS::BedrockAgentCore::WorkloadIdentity
└─ IAM + env-var injection
│
request time ──▶ index.aws.ts ──▶ real AgentCore APIsThe CDK layer injects resource handles (memory id, gateway URL, workload name) into the
Lambda's environment; the runtime layer reads them back. You never wire that plumbing by
hand.
Lambda's environment; the runtime layer reads them back. You never wire that plumbing by
hand.
Putting it together: a memory-augmented, tool-using assistant
One of the example apps (
that ties Memory + Gateway together — the loop AgentCore Runtime gives you, simulated
locally so it's fully testable offline:
test-apps/ai-support-assistant) is a small "agent runtime"that ties Memory + Gateway together — the loop AgentCore Runtime gives you, simulated
locally so it's fully testable offline:
1
2
3
4
5
user turn ─▶ remember (Memory.createEvent)
─▶ recall (Memory.retrieveMemories: facts + preferences)
─▶ plan (intent → Gateway.callTool)
─▶ respond (tool results + recalled memory)
─▶ remember (Memory.createEvent, assistant turn)A fact stated in one session is recalled in a later session — and isolated per user.
In production, the rule-based planner is exactly where the first-party
block drops in; the Memory/Gateway wiring is unchanged.
In production, the rule-based planner is exactly where the first-party
Agent (LLM)block drops in; the Memory/Gateway wiring is unchanged.
How it was tested
I held the work to two bars: fast local correctness and real cloud reality.
1. Unit tests — 27 of them, offline, deterministic
Every block has behavior tests and a cross-layer parity test asserting that
promise can't silently drift.
mock / aws / cdk expose the same public surface — so the "same code everywhere"promise can't silently drift.
2. Real deployment — the blocks must be actual AWS resources
A mock that lies is worse than no mock. So I deployed a minimal stack
(
CloudFormation create every
(
test-apps/agentcore-blocks-smoke) that instantiates all three blocks and watchedCloudFormation create every
AWS::BedrockAgentCore::* resource.This is also where the local-vs-cloud honesty got enforced: the first deploy failed
because the service rejected my resource name (
the name sanitizers and the tool-schema translation, and redeployed green. That's the
value of testing against reality, not just a mock.
because the service rejected my resource name (
Name must match^[a-zA-Z][a-zA-Z0-9_]{0,47}$). I pulled the authoritative CloudFormation schemas, fixedthe name sanitizers and the tool-schema translation, and redeployed green. That's the
value of testing against reality, not just a mock.
3. Live runtime — the deployed Lambda must talk to real AgentCore
Finally I invoked the deployed API and watched the
against the live service: the Gateway returned a real MCP endpoint URL, Identity returned
a real KMS-encrypted workload access token, and Memory made a real data-plane call. Then
I tore the whole stack down — clean.
aws-runtime layers round-tripagainst the live service: the Gateway returned a real MCP endpoint URL, Identity returned
a real KMS-encrypted workload access token, and Memory made a real data-plane call. Then
I tore the whole stack down — clean.
On top of that, a high-effort code review caught (and I fixed) seven issues before the PR
— including a CI-breaker and a real AWS-only bug where an OAuth call omitted a required
parameter that a type-cast had been hiding.
— including a CI-breaker and a real AWS-only bug where an OAuth call omitted a required
parameter that a type-cast had been hiding.
The one honest difference
Local AgentCore Memory extraction/retrieval is lexical (bag-of-words similarity);
real AgentCore is LLM- and vector-backed. So locally, semantic recall needs lexical
overlap between query and stored text. The API, data model, and namespaces are
identical, so code written against the mock runs unchanged on AWS — where retrieval
becomes genuinely semantic. This is documented in each block's
under the rug.
real AgentCore is LLM- and vector-backed. So locally, semantic recall needs lexical
overlap between query and stored text. The API, data model, and namespaces are
identical, so code written against the mock runs unchanged on AWS — where retrieval
becomes genuinely semantic. This is documented in each block's
DESIGN.md, not sweptunder the rug.
Try it yourself
The work is up as PR #122
against AWS Blocks — three packages under
consistency, API reports), and a changeset. Spin up the local loop in seconds:
against AWS Blocks — three packages under
packages/, two demonstrative apps undertest-apps/, the repo's full gate suite (build, unit tests, dependency lint, exportsconsistency, API reports), and a changeset. Spin up the local loop in seconds:
1
2
3
4
# from the branch
npm install && npm run build
npm test -w @aws-blocks/bb-agentcore-memory # 10/10, offline, $0
npm test -w example-ai-support-assistant # the full agent loop, offlineWhat's next
The same pattern extends naturally to the rest of AgentCore:
- AgentCore Runtime — run an agent behind the HTTP contract (
POST /invocations,GET /pingon:8080) locally, package it for the managed runtime. - Code Interpreter and Browser sandboxed-tool blocks (each a natural Gateway
target). - Observability via the existing
Tracer/Metricsblocks.
Why this matters
Production agent infrastructure shouldn't require a production bill to develop. By
expressing AgentCore Memory, Gateway, and Identity as AWS Blocks, you get a tight,
free, offline inner loop — and the confidence that the code you tested on your laptop is
the code that runs in the cloud. Build and test, then deploy.
expressing AgentCore Memory, Gateway, and Identity as AWS Blocks, you get a tight,
free, offline inner loop — and the confidence that the code you tested on your laptop is
the code that runs in the cloud. Build and test, then deploy.
👉 Read the code, kick the tires, leave a review
aws-devtools-labs/aws-blocks — PR #122 — Memory, Gateway, and Identity AgentCore Building Blocks. Open · mergeable · awaiting review.1
2
3
gh pr checkout 122 --repo aws-devtools-labs/aws-blocks
npm install && npm run build
npm test -w @aws-blocks/bb-agentcore-memory # 10/10, offline, $0Built on AWS Blocks . Memory, Gateway,
and Identity blocks verified end-to-end on real Amazon Bedrock AgentCore.
and Identity blocks verified end-to-end on real Amazon Bedrock AgentCore.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article