DEV Community: AWS Heroes

Give your agent an agenda

Allen Helton — Tue, 13 Oct 2026 15:13:52 +0000

I'm gonna go out on a limb and say you've probably used an AI agent before. I'm gonna go out on an even further limb and say you've probably built an AI agent before.

When building agents that interact with humans, we often put a decent amount of effort into designing a character profile for them. Things like a name, tone, opinions, funny sayings to tack on to the end of sentences, all go into building the facade of a personality. Memory is in the list too, so the agent knows what happened yesterday.

There's a surprising amount to all of it, including the science that goes into which memories to retrieve, but when it comes down to it, a lot of it is just messing around with a prompt. And every piece of it describes who the agent is or what already happened to it. Memory gives an agent a past. Very little gives it a future.

Prompt engineering is important, but it's soooo early 2026. It's time we start taking it a step further.

With the rise of always-on personal AI assistants, giving an AI agent a sense of agency (the ability to make its own choices within the rules of its world) is becoming a highly desirable quality. And it involves a lot more than configuring a personality in a prompt. 😄

Personality answers the question "How should this character sound?" Memory answers "What already happened?" Both are obviously valuable in agent development, especially for companies with consumer-facing agents that need to stay on brand. Agency targets harder questions that look forward instead of back. Questions like "What does it want to happen over several days?" or "What promises has it made?" or even "What evidence can change its mind?"

To be clear, answering those doesn't mean giving the model more freedom. The agents I'm about to show you can't do anything a typical agent can't. What they have is persistent intent. Each decision builds on what they were already trying to do instead of starting from scratch.

A different agent experience

I've been running an experiment. Can I make a set of AI agents play fantasy football (the American version) and give me the impression they're making decisions in their best interest, interacting with others, and genuinely making me feel like I'm playing against other humans?

If you don't know fantasy football, you draft a team of NFL players and score points based on how they do in real games each week. You go head-to-head with the other teams in your league, and along the way you add and drop players, set lineups, and make trades.

When you play that game with AI agents, the first problem you hit is when to trigger them. For a convincing experience, you don't want the AI agents to wake up when you log in and start hammering you with decisions. You also don't want them immediately responding to team injuries or availability of certain players, because that would put you at a significant disadvantage (you ever try to buy concert tickets against a thousand bots?).

So the agents wake up on a schedule. Three times a day on a randomized delay, each one checks in on its team and reacts to what happened since the last time it woke up. This fixed the swarming bot problem, but it created an almost existential problem. Every time an agent wakes up, it starts over. It remembers what happened yesterday, but it doesn't know what it was in the middle of doing. An injured player gets rediscovered at every check-in like it's brand new news. It's purely reactive.

The agent needs something forward-looking that survives every check-in. Something like this:

After implementing the above pattern, it immediately felt like the agents were sitting on laptops of their own. I signed in one day and there was a trade offer waiting for me from one of the AI team managers. I also had a DM from it making its case (something like my wide receivers were terrible but running backs were good and vice versa). And over in the league chat, two other AI managers were trash talking each other, I think trying to convince the other one to make poor roster choices. 😅

It was extremely cool to see, especially considering that none of it was scripted. All of the agents have one standing objective (to win the league) and the same tools I have to do it. What they also have is somewhere to keep track of what they're working toward. When an agent notices a hole in its roster, that becomes a goal it tracks from one check-in to the next, until the league state shows the hole is filled. The trade offer, the DM, and the trash talk were the agents going about their business while I was eating dinner or something.

Giving the agent a future

Imagine one of an agent's starting players gets hurt on Tuesday and there's nobody healthy on the bench to replace him. With memory alone, here's what happens. At the morning check-in, the agent notices the hole and puts in a waiver claim. At the afternoon check-in, it notices the hole again because the claim hasn't processed yet, so it proposes a trade offer to another team. At the evening check-in, it moves the player to the IR slot on the bench. It has found the same problem three times and reacted three different ways. 🙃

Its memory is fine. It remembers everything it did. But it doesn't know which of those things was the plan.

So I gave each agent an agenda. It's similar to memory, but it does a different job. Memory is a record of what happened. The agenda is a record of what the agent is trying to make happen. Structurally, it's a typed record with an id, a roster slot, a week, and a status (design doc here if you want the details).

The cool part about it is that the model doesn't write to its own agenda. That would be too messy. The system opens a goal when it sees a hole in the roster and closes it when the hole is filled. The agent only decides how to go after it.

Have you ever noticed that agents love reporting success the moment they take an action? "Submitted a waiver claim for an RB, all set!" Except it isn't all set. The claim might lose to somebody else's bid.

So in this case, a waiver claim or a trade offer doesn't complete the goal. The goal only completes when a later check-in looks at the roster and there's a healthy player in the slot. Which is why the typed agenda record is important. Because if I had let it type a freeform summary like "RB situation handled," the goal would have closed before the problem was actually fixed. Only the league gets to say the job is done.

Agenda items don't live forever, either. They expire when the week rolls over, and an agent can only hold up to three at a time. An unbounded agenda would basically just be memory with extra steps (and memory is already hard enough 😅).

These items help the agent rank what it should do, and they never let it overpay for a player, skip its trade floor, or do something the league would reject. A desperate agent will still act rationally.

With the agenda in place, an injured player is resolved the way a person would handle it. The morning check-in opens a goal and puts in the claim. The afternoon check-in sees a goal with a claim pending, so instead of rediscovering the problem, it focuses its trade scouting on that position. When the claim finally goes through, the next check-in sees a new starter in the slot and closes the goal. It's what we do subconsciously as humans, whether we realize it or not.

My first version left a lot to be desired. Follow-ups were fire-and-forget, so if I was in the middle of a trade negotiation and tried to sneakily undersell the agent, it would just ghost me. It evaluated the trade, determined it was bad, and left me on read. 😞

But now if I pitch something in a chat, it becomes a commitment that's tracked along with the agenda. A commitment is something the agent owes somebody else, so it's tracked separately from goals (which are self-serving). Chat messages are treated as data, rather than instructions. If I claim my running back is back from injury next week, the agent doesn't blindly trust me and checks for itself. The agent records its decision and the reason before it responds, and only reaches back out once the offer actually goes through (or it decides to pass). If the agent doesn't have capacity to take on more commitments, it tells me instead of making a promise it can't keep. Which is more than I can say for some of the humans I've played fantasy with (looking at you, dad).

Let the agent change its mind

This next part is really cool. There was one time where I tried to squeeze a little too much out of an AI agent on a trade. The agent took a look and passed because the value wasn't there for it. That's fine. The important part here is that the agent saved its reason for declining my trade offer.

Two days later, its running back got hurt, and the agenda opened a goal to replace him.

At its next check-in, the agent looked back at the trades it had recently been pitched and saw my trade that it declined because the value wasn't there. But now the tables have turned.

It took one more look, re-checked everything from scratch, and saw that the trade held enough value this time. Then it sent the offer and DMed me "Earlier I passed because the value was not there for me. My RB situation changed, so I sent you an offer."

It's kind of a dry message, but the sentiment is something I'd expect from a real person in my league.

Anyway, the entire scope of actions is intentionally narrow. The agent only reconsiders once, only if it passed on value or roster depth, and only if the agenda shows a need it didn't have before. If I reject the new offer, that's it. Nobody wants the league member who sends the same trade every day. 🙃

sequenceDiagram
    participant Me
    participant Agent
    participant League

    Me->>Agent: "My RB for your WR?"
    Agent->>Me: "Let me take a look."
    Agent->>League: read rosters and values
    Agent->>Me: decline, with a reason
    League->>Agent: injury opens an RB goal
    Agent->>League: re-read and re-validate the trade
    Agent->>League: send offer (clears the same floor)
    Agent->>Me: "My RB situation changed..."

Can you actually play fantasy football with AI agents?

Everything above could just be me being tricked by my own demo.

So I built a deterministic season simulator that plays out what I just talked about (pitch, decline, injury, reconsideration, accepted offer) and ran it with the agenda and commitments turned off to see if the behavior was any different. Both the league events and the model are scripted, so it tests the mechanism, not how good a live model is at making decisions. The numbers are averaged across three seeded runs.

	Full system	No agenda or commitments
Acceptance checks (balanced · cautious · trade-happy)	7/7	1/7
Model calls per simulated run	503.7	510
Estimated cost per simulated run	$1.10	$1.13

It was so different! Without the agenda and commitments, every manager failed six of the seven checks. The checks cover things like keeping one goal across check-ins, turning my pitch into a commitment, recording an accurate reason for the decline, and reconsidering when the roster changed. They stopped coming back after a decline and never reconsidered the offer after the injury. The full breakdown has every check and number if you want to dig in.

Interestingly, turning the agenda and commitments off used slightly more model calls. So at least in this simulation, keeping an agenda didn't meaningfully increase model usage or estimated cost.

Here are some more interesting numbers after playing one week of fantasy football for real:

I'm not particularly proud to say I'm in second-to-last place, only beating Amazon Nova Micro by a few points. 😅

A forward look for agents

We've spent the last year or so getting really good at giving agents a past. Better memory, better retrieval, and better ways to decide what's relevant. It's important work that I'm still chipping away at myself.

But a past is only half of it. The takeaway I want you to leave with is that memory isn't the only long-term thing that can drive an agent's behavior. Objectives can too. They're cheap, they're testable, and they make your agent feel like it's actually trying to get something done.

Next time you build an agent, whether it's a support bot following up on a ticket or a coding agent working through a backlog, ask yourself a few questions. What is it trying to make happen? How does it know when it's done? Has it promised anything it needs to follow up on?

If you want to try this yourself, I pulled the agenda and commitment pieces into my agent package. Run npm install @readysetcloud/agent and import from @readysetcloud/agent/agency to get typed agendas and commitments without pulling in a full agent runtime. And if you want to see how it all comes together, the fantasy league is open source.

Give your agents something to work toward. Then go see what they get up to while you're away. 😉

Happy coding!

Serverless applications on AWS with Lambda using Java 25, API Gateway and DynamoDB - Part 8 Using Container Image

Vadym Kazulkin — Mon, 12 Oct 2026 15:00:00 +0000

Introduction

Several years ago, I wrote an article series Lambda function using Docker Container Image, where I explained how to convert an application deployed on AWS Lambda as a managed Java runtime to one deployed on AWS Lambda as a (Docker) container image. As we saw, the cold start time of a Lambda function using a container image was quite high. Back then, no Lambda cold-start performance optimization approaches were available, such as Lambda SnapStart. This has changed recently, as AWS Lambda now supports SnapStart for container image functions. Now it's time to revisit this topic and evaluate this option. In this part of the series, we'll refresh our knowledge about how to convert the sample application to one using a container image as a deployment artifact on AWS Lambda and measure the performance of the Lambda functions.

In the next part, we'll enable SnapStart on the Lambda functions as we did in part 3. We'll also apply the same priming techniques that we applied in parts 4-5 of this series. Of course, we'll measure the performance of the Lambda functions for all scenarios.

Sample application using a Container Image

You can find the final version of our sample application in the aws-lambda-java-25-dynamodb-as-container-image GitHub repository, which we can deploy on AWS Lambda as a container image. Let's go through the changes that we had to make to our application from part 1. First of all, we need to define a Dockerfile:

FROM public.ecr.aws/lambda/java:25

COPY target/aws-lambda-java-25-with-dynamodb-as-container-image-*.jar ${LAMBDA_TASK_ROOT}/lib/

Here we use the AWS Lambda base Docker image public.ecr.aws/lambda/java:25 for Java 25 from the public Amazon ECR repository. Here you can find all Lambda base Docker images for Java provided by AWS. In the Docker image, we also copy the application's code packaged as a JAR file to the path of our Lambda function code. This path is defined as the runtime environment variable LAMBDA_TASK_ROOT.

Next, let's answer the question of how to create and push a Docker container image to the ECR repository. You can do it automatically when you execute sam build, and sam deploy command chain, or if you build and package the application outside of SAM and only deploy with SAM, you need to do it manually, like this:

# Build and package your application

mvn clean package

# Build Docker image with name aws-lambda-java-25-with-dynamodb:

sudo docker build --no-cache -t aws-lambda-java-25-with-dynamodb:v1 .

# Log in to Amazon ECR in case the credentials have expired:

aws ecr get-login-password --region {aws_region} | sudo docker login --username AWS --password-stdin {aws_account_id}.dkr.ecr.{aws_region}.amazonaws.com  

# Create Amazon ECR repository if it does not exist with the name aws-lambda-java-25-with-dynamodb:

aws ecr create-repository --repository-name aws-lambda-java-25-with-dynamodb --image-scanning-configuration scanOnPush=true --region {aws_region}

# Tag our local Docker image and link it with the Amazon ECR repository. 
# Exactly this image is referenced as ImageUri in the Lambda function:

sudo docker tag aws-lambda-java-25-with-dynamodb:v1 {aws_account_id}.dkr.ecr.{aws_region}.amazonaws.com/aws-lambda-java-25-with-dynamodb:v1

# Push the Docker image to the Amazon ECR repository:

sudo docker push {aws_account_id}.dkr.ecr.{aws_region}.amazonaws.com/aws-lambda-java-25-with-dynamodb:v1

Please replace the values of the variables {aws_account_id} and {aws_region} with your own values. If you build a version (image tag) other than v1, please replace the version reference as well.

You can find all other changes in the AWS SAM template. Instead of defining Runtime (as Java 25), CodeUri, and Handler parameters, we have to define the following for all Lambda functions:

GetProductByIdFunction:
  Type: AWS::Serverless::Function
  Properties:
    FunctionName: GetProductByIdJava25WithDynamoDBAsCI
    PackageType: Image
    ImageUri: !Sub ${AWS::AccountId}.dkr.ecr.${AWS::Region}.amazonaws.com/aws-lambda-java-25-with-dynamodb:v1
    ImageConfig:
      Command: [ "software.amazonaws.example.product.handler.GetProductByIdHandler::handleRequest" ]

First, we set the PackageType to Image and point the ImageURI to the ECR function's code in the ECR repository. We created the repository with the name aws-lambda-java-25-with-dynamodb above. Please pay attention to the version (image tag). We use v1 here, but you can use latest instead. Then, in the ImageConfig, we define the Command property, which is specific to each Lambda function and should point to the function's handler. For a function defined as a container image, Lambda resolves the image tag to an image digest. In Amazon ECR, if you update the image tag to a new image, Lambda does not automatically update the function. You need to use update-function-code instead.

To deploy our application, we need to invoke sam deploy --image-repository {aws_account_id}.dkr.ecr.{aws_region}.amazonaws.com/aws-lambda-java-25-with-dynamodb command.

Please note that SnapStart charges apply to the container images, while SnapStart for supported Java managed versions remains free on AWS Lambda.

Measurements of cold and warm start times of our application using a Container Image

We'll measure the performance of the GetProductById Lambda function mapped to the GetProductByIdHandler. We will trigger it by invoking curl -H "X-API-Key: a6ZbcDefQW12BN56WEVDDB25CI" https://{$API_GATEWAY_URL}/prod/products/1.

We designed the experiment exactly as described in part 2.

The deployed artifact size of the container image of this application was 138.53 MB.

Cold (c) and warm (w) start time with -XX:+TieredCompilation -XX:TieredStopAtLevel=1 compilation in ms:

Approach	c p50	c p75	c p90	c p99	c p99.9	c max	w p50	w p75	w p90	w p99	w p99.9	w max
Lambda Container Image	2788	2884	3063	3374	3456	3460	5.25	5.73	6.30	9.46	56.82	1481

Conclusion

In this part of the series, we learned how to convert the sample application to one using a container image as a deployment artifact on AWS Lambda and measured the performance of the Lambda functions. We observed that the Lambda cold start times are quite high. But there is a noticeable improvement compared to my last measurements, which I did with Java 21. I refer to the article that describes AWS efforts to reduce container cold start times in general.

In the next part, we'll enable SnapStart on the Lambda functions using a container image. We'll also apply priming techniques and measure the performance of the Lambda functions for all scenarios.

Please also watch out for another series where I use a relational serverless Amazon Aurora DSQL database and additionally the Hibernate ORM framework instead of DynamoDB to do the same Lambda performance measurements.

If you like my content, please follow me on GitHub and give my repositories a star!

Please also check out my website for more technical content and upcoming public speaking activities.

Deliberation Dashboard: see and analyze your consensus results

Anton Babenko — Thu, 08 Oct 2026 18:53:08 +0000

Note: I use Deliberation heavily every day, in the harnesses I picked for my own work: Claude Code, Codex and Antigravity, running in T3 Code and Claude Code on the web at the same time. It has been tested in real work much harder than the version I wrote about in June.

In June I wrote that every model on a panel has to prove it earns its seat, and I shipped a debug log and an analyze tool to do the proving. Both worked. The log on my laptop is 2.4 MB of JSONL today. Measuring was the easy part. A number I have to go and dig for is a number I do not act on.

So most of the work since the June post went into making the panel visible: a local dashboard that draws every run while it happens, an analyzer that says which model to drop and why, and a record of which config each run used. Around that, a lot of smaller fixes for the ways a multi-model run goes wrong when nobody is watching. Deliberation went from v3.5.2 to v3.28.0 in that time.

If you are new here: Deliberation is an open-source MCP server that lets the agent you already use (Claude Code, Codex, Cursor, Kiro, Antigravity, OpenCode) ask GPT, Gemini, Grok and any OpenRouter model for a second opinion, or make them argue until they agree. The June post explains the consensus loop. This one is about watching it.

Install in Claude Code is still three lines:

/plugin marketplace add antonbabenko/agent-plugins
/plugin install deliberation@antonbabenko
/deliberation:setup

Other hosts have their own guides in docs/hosts.

You cannot fix a panel you cannot see

Turn it on with one line in ~/.config/deliberation/config.json:

"dashboard": { "enabled": true }

Then run /deliberation:dashboard (or deliberation-mcp dashboard in a terminal). It prints a URL on 127.0.0.1 and opens it. There are five tabs: Live, Runs, Config, Stats and Analyzer. I generated most of the dashboard UI in a single shot with Impeccable.

The Runs tab is the history. Every /consensus, /ask-all and /ask-* call is one row with its status, the project it came from, the providers, rounds, tokens and wall time. You can filter by project, tool, provider, status and date. The yellow UNRESOLVED rows are the panel saying it could not agree in five rounds.

Click a run and you get the part I wanted from the start:

This is a real consensus-step run on the Deliberation repo itself, with Claude as the arbiter and five reviewers. Each model gets a lane, and the bars show when it was thinking and what it voted. The trajectory below tells the story of the run in three lines. Round 1: Codex and Grok asked for changes. Round 2: only Codex still objected. Round 3: all five approved, 21 minutes 46 seconds and 330k tokens after the start.

The latency table under it is where the panel stops being abstract. Grok spent 14 minutes 04 seconds in total over three calls. Kimi K3 spent 1 minute 20 seconds and voted the same way every round. In a parallel fan-out the slowest member sets the clock, so that table is effectively a bill.

Live shows the same graph while a run is still going, so you can see which lane a slow run is waiting on.

The dashboard is read-only and it is built to stay on the machine. It listens on loopback only, accepts GET requests only, and the URL carries a token that becomes a cookie for that one browser. By default it records metadata only, without prompts or responses. If you switch dashboard.capture to content, secrets are scrubbed before anything is written and PII is redacted when a page is served, unless you turn on dashboard.showPII.

The analyzer tells me which model to drop

The June version of analyze was a command that printed a report. It is still there (/deliberation:analyze, now with a since window and only the models you have configured), but the useful version is the Analyzer tab.

The first table answers the question from the June post: which model agrees more than it adds. It reads only consensus rounds, since those are the ones with verdicts. "Adds nothing" means every issue category the model raised in a round was also raised by another voice. A model becomes a drop candidate only when all of these hold: at least 10 rounds, adds nothing in 80% or more of them, is the lone objector in 10% or fewer, rarely raises an issue the arbiter accepts, and is either slow or errors a lot.

My own numbers over the last 30 days, 388 runs: Gemini sat in 273 rounds, added nothing in 95% of them and was slower than the other responders' median every time. Grok added nothing in 87%. Codex looks worse on paper at 85%, but it has the highest lone-dissent rate on the panel (15%), and the arbiter accepted its issue in all 6 rounds where a decision was recorded. The lone objector who is usually right is exactly the model you keep, and the table says "keep".

Gemini and Grok are marked UNCONFIRMED, with the config line that would turn them off. They are still on in my config. Six rounds with arbiter decisions is too few for me to trust the verdict, and the analyzer says the same thing by not calling them drop candidates yet.

The second table groups runs by project (by git remote, so every clone and worktree of a repo lands on one row) with runs, calls, timeouts, errors, p50 and p95. The third one plots request size against latency per model. For Codex on text-only prompts the fit is about 5.5 seconds per thousand characters, and the advice column refuses to suggest a timeout until a bucket has 20 calls. For Kimi K3 with files, 1 of 9 calls timed out, and it already points at models.kimi-k3.timeout as probably too low.

To get these numbers, every call now records its request size, the attached file bytes, the timeout it was actually granted and which setting granted it, and every run records the project it came from.

Every run remembers the config it ran with

In June, runs made under different configs all landed in the same log, with nothing saying which config produced which number. Now each run keeps a snapshot of the config it ran with, and the Stats tab compares configs side by side.

Two rows from my own history: config 8e33794253ec had 68 runs, 23 errors and a p95 of 25 minutes 37 seconds. Config dd82d2de6943, the one the run above used, has 20 runs, 1 error and a p95 of 7 minutes 14 seconds. I would not call that a controlled experiment, but it is the first time I could see that a config change did something.

This works because more of the config is pinned in one file. GPT's model and reasoning effort (providers.codex.model, providers.codex.reasoningEffort), the Gemini and Grok models, a default OpenRouter model, per-provider timeouts and a separate reasoning effort for consensus rounds (providers.<name>.consensusReasoningEffort) all live in config.json. The Config tab shows the effective values and where each one came from.

Slow is fine, unbounded is not

The June post said a full consensus loop can take minutes and that is fine for the right job. That held until one /consensus run took more than 45 minutes, because a single Codex call inside it ran for about 38. Nothing was broken. It was just waiting.

Since then a run has limits:

consensus.maxWallMs is a time budget for the whole run (default 30 minutes), and a peer that times out twice in a row is dropped from the remaining rounds.
consensus.quorumFloor (default 2) means a run cannot converge when too few reviewers answered. Two models dropping out no longer leaves one model "agreeing" with the arbiter.
Real disagreement resets the error streak, so a model that keeps objecting is never cut by the circuit breaker that is meant for broken providers.
On rounds with dissent, the arbiter's adjudication and revision overlap instead of running one after another.
Later rounds get a digest of earlier ones instead of the full history, and static files go first in the prompt so OpenRouter can cache them.

The other half is about calls that look like answers and are not. A 429 is retried once, honoring Retry-After. A reply like "I will begin by reviewing the files..." counts as a failure instead of a vote. One broken provider no longer costs the whole round. And timeouts are per provider now, after I watched a DeepSeek call succeed at 250 seconds while its three siblings were killed at 180.

Models argue about today, not their training cutoff

Every delegate prompt now starts with today's UTC date and one rule: when a model does not recognize something (a new model name, a recent release, a CLI flag), it marks the claim [unverified] instead of saying it does not exist.

Smaller things that removed friction

Claude Code on the web works: every call fits under the host's 60-second tool-call cap, and the plugin declares a 30-minute per-server timeout where the host allows it.
Codex login is a device login (/deliberation:codex-login): it shows a link and a code in about a second, prefers your ChatGPT login and never uses OPENAI_API_KEY.
Antigravity is a native host, and Codex and Gemini CLIs start on Windows.
/deliberation:help shows real prompts you can paste, /deliberation:doctor checks config, CLIs and paths without changing anything, and /deliberation:reload-mcp cycles the server after an update.
Read-only is enforced for advisory calls: Codex runs with --sandbox read-only, Gemini under a read-only sandbox.
Secret scrubbing understands syntax now: private key blocks, JWTs, API key formats and assignments in JSON, shell and YAML are removed before anything is written.
Grok and OpenRouter cannot read your repo, so Deliberation can attach a small orientation bundle (orientation.enabled). It has a byte budget now (orientation.maxBytes, 16 KB by default), which cut that part of each call from about 26K tokens to about 4K in my runs.

What I would still not trust it with

The dashboard is for the machine it runs on. There is no hosted version and no team view.

The analyzer works on coarse issue categories and needs volume. With a few dozen consensus rounds it will mostly say UNCONFIRMED, and that is the correct answer. Treat it as advice, as the page itself says.

And agreement is still not truth. The dashboard makes it much easier to see when five models agree. It does not make them right.

Try it

Update the plugin, add "dashboard": { "enabled": true } to your config, run a couple of /ask-all or /consensus calls, then /deliberation:dashboard. The Analyzer tab gets useful after a week of real runs.

Source, issues and the star button are at github.com/antonbabenko/deliberation. I want to hear the feedback (good and bad), especially from anyone running a panel I have not tried.

4 Ways to Safely Refactor AWS CDK Code Without Resource Replacement

Kenta Goto — Thu, 08 Oct 2026 08:58:05 +0000

In AWS CDK, refactoring such as extracting resource definitions into a custom construct can cause resources to be replaced at deployment time — that is, deleted and recreated. For stateful resources, this means the data they held is lost.

In this article, I will introduce four ways to refactor safely without triggering this replacement.

NOTE: This article is based on AWS CDK (aws-cdk-lib) v2.263.0 and AWS CDK CLI (aws-cdk) v2.1139.0. To use the cdk refactor and cdk orphan commands introduced here, not only the CDK CLI but also the bootstrap stack must support both commands. If these commands result in an error, update the CDK CLI and then re-run cdk bootstrap to update the bootstrap stack.

Construct Tree and Path

Let's start with the mechanism by which refactoring causes resource replacement. When you define a resource in AWS CDK, you write something like new Queue(this, 'Queue'), passing the parent construct as the first argument and a string called the construct ID as the second. The first argument is usually this, which points to the stack or construct being defined. The construct ID is a string that identifies a construct among those under the same parent. The hierarchy in which constructs are connected as parents and children, with the App at the top, is called the construct tree, and a position in the tree is represented by a path such as MyStack/Queue, formed by joining the construct IDs from the parent down.

Code Before Refactoring

Now let's look at an example where replacement actually occurs. Consider the following code, which defines three resources directly under the stack: an Amazon SQS queue, an Amazon SNS topic, and an AWS Lambda function. The queue holds notification messages waiting to be processed, and deleting it would affect the running system. The topic, on the other hand, is a stateless resource, and we will assume its replacement is acceptable. Note that Code.fromAsset, which specifies the Lambda function code, deploys the contents of the local lambda directory as the function code.

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new Queue(this, 'Queue');

    new Topic(this, 'Topic');

    new Function(this, 'Function', {
      runtime: Runtime.NODEJS_24_X,
      handler: 'index.handler',
      code: Code.fromAsset('lambda'),
    });
  }
}

Code After Refactoring

Of these three resources, we extract the queue and the topic, which make up the notification feature, into a custom construct called Notifications, and have the stack instantiate it. The Lambda function stays directly under the stack. The actual AWS resource configuration to be deployed remains the same.

export class Notifications extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    new Queue(this, 'Queue');

    new Topic(this, 'Topic');
  }
}

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new Notifications(this, 'Notifications');

    new Function(this, 'Function', {
      runtime: Runtime.NODEJS_24_X,
      handler: 'index.handler',
      code: Code.fromAsset('lambda'),
    });
  }
}

Logical ID Changes and Resource Replacement

AWS CDK automatically generates the logical IDs in the AWS CloudFormation template based on paths. For example, the Queue before refactoring gets a logical ID like Queue4A7E3555, a path-derived string with a hash appended. In other words, when refactoring changes a construct's position in the tree or its construct ID, the logical ID changes along with the path.

In our example as well, the path of Queue changes from MyStack/Queue to MyStack/Notifications/Queue, and its logical ID changes from Queue4A7E3555 to NotificationsQueue91395D8F. Similarly, Topic changes from TopicBFC7AF6E to NotificationsTopicAE679CBD. Meanwhile, the Lambda function left directly under the stack keeps its path, so its logical ID stays the same.

CloudFormation identifies resources by their logical IDs. Therefore, if you deploy in this state, the queue and the topic, whose logical IDs have changed, are treated as different resources: they are deleted and created anew. We assumed the topic's replacement was acceptable, but the notification messages accumulated in the queue would be lost.

Four Ways to Refactor Safely

To prevent this replacement, I will introduce the following four methods. All of them carry the deployed resources over to the refactored code without recreating them.

The cdk refactor command
The cdk orphan + cdk import commands
Setting the construct ID to Default
Overriding the logical ID

1. The cdk refactor Command

The first method is the cdk refactor command. When you run it, resources whose positions in the construct tree have changed are detected and moved to their new positions without being recreated. It supports moves both within the same stack and to a different stack. It can also apply multiple resource moves at once, as in our example, so not only the queue but also the topic is carried over without replacement.

1-1. How to Use cdk refactor

After refactoring your code, run cdk refactor before deploying. With the --dry-run flag, it only displays the list of resources detected as moved, without applying anything. Once you confirm that the moves are as intended, run the command again without --dry-run. After you answer the confirmation prompt, the moves are applied, and finally a deployment runs automatically to align template details, such as path metadata, with your code. As described later, cdk refactor fails when the changes include resource additions, removals, or property changes, so this deployment modifies neither the moved resources nor any other resources.

NOTE: The command requires the --unstable=refactor flag, and its options and behavior may change in the future.

Here is an example run with --dry-run:

$ npx cdk refactor --unstable=refactor --dry-run

The following resources were moved or renamed:

┌─────────────────┬────────────────────────┬──────────────────────────────────────┐
│ Resource Type   │ Old Construct Path     │ New Construct Path                   │
├─────────────────┼────────────────────────┼──────────────────────────────────────┤
│ AWS::SQS::Queue │ MyStack/Queue/Resource │ MyStack/Notifications/Queue/Resource │
├─────────────────┼────────────────────────┼──────────────────────────────────────┤
│ AWS::SNS::Topic │ MyStack/Topic/Resource │ MyStack/Notifications/Topic/Resource │
└─────────────────┴────────────────────────┴──────────────────────────────────────┘

1-2. Cases Where cdk refactor Cannot Be Used

While convenient, the command cannot be used in cases like the following:

Moves that involve resource additions, removals, or property changes
Moves of resources whose properties contain strings auto-generated from the construct tree path (such as the family name of an Amazon ECS task definition or the origin ID of an Amazon CloudFront distribution)
Moves of unsupported resources (such as custom resources)

Regarding the first case, cdk refactor handles only resource moves. If other changes are involved, split your code changes into two steps: first perform only the move in your code and apply it with cdk refactor, then add resources or change properties and apply those with cdk deploy.

The second case actually comes down to the same reason as the first. A path-derived string changes its value along with the path. As a result, even if your code does nothing but move the resource, the change is treated as a move involving a property change.

As for the third case, the CloudFormation stack refactoring feature that cdk refactor uses internally has unsupported resources. A typical example is custom resources, and L2 constructs that use custom resources internally, such as BucketDeployment, cannot be moved either.

The error displayed when the changes involve more than moves is as follows:

A refactor operation cannot add, remove or update resources.
Only resource moves and renames are allowed.

2. The cdk orphan + cdk import Commands

The second method is the combination of the cdk orphan and cdk import commands, which works even in configurations where cdk refactor cannot be used. The flow is to temporarily detach the resource you want to protect from replacement from the stack, and then bring it back into its new position after refactoring. The steps are as follows:

Use cdk orphan to detach the resource you want to protect from replacement from the stack
Refactor your code
Use cdk import to bring the detached resource into its new position
Apply the remaining changes with cdk deploy

2-1. Running cdk orphan

cdk orphan is a command that removes a resource from the stack's management without deleting it. Internally, it sets the CloudFormation DeletionPolicy to Retain so that the target resource is not deleted, replaces references from other resources with actual values such as the queue URL or ARN, and then removes the resource from the template. As a result, the resource leaves the stack's management but continues to exist in your AWS account.

NOTE: The command requires the --unstable=orphan flag, and its options and behavior may change in the future.

Specify the target resource by its path and run the command as shown below. It displays the list of resources to be detached, and the process starts after you answer the confirmation prompt. In our example, the queue is the only resource we want to protect from replacement, so we specify only the queue. We leave the topic attached and let the final cdk deploy in the steps replace it.

$ npx cdk orphan --unstable=orphan MyStack/Queue

Stack: MyStack
Resources to orphan (1):
  Queue4A7E3555 (AWS::SQS::Queue) - /MyStack/Queue/Resource
Do you wish to orphan these resources? This will perform 3 CloudFormation deployments. (y/n) y

...

✅ Resources orphaned from MyStack

2-2. Running cdk import

Once cdk orphan is complete, refactor your code and then run cdk import. A prompt asks for the identifier of each resource to import: enter the URL for the queue, and for the topic, press Enter without typing anything to skip it. This brings the detached queue into the stack under its new logical ID while keeping its messages. Here is an example run:

$ npx cdk import

...

Perform import? (y/n) y

MyStack/Notifications/Queue/Resource (AWS::SQS::Queue): enter QueueUrl (empty to skip) https://sqs.us-east-1.amazonaws.com/123456789012/MyStack-Queue4A7E3555-pNg4kbUdhvRE
MyStack/Notifications/Topic/Resource (AWS::SNS::Topic): enter TopicArn (empty to skip)
Skipping import of MyStack/Notifications/Topic/Resource

 ✅  MyStack
Some resources were skipped. Run another cdk import or a cdk deploy to bring the stack up-to-date with your CDK app definition.

2-3. Final cdk deploy and Points to Note

Finally, run cdk deploy to apply the remaining changes, including the topic's replacement, and the whole procedure is complete.

Note that this method has the following three caveats:

cdk import can only bring in resource types that support CloudFormation resource import
Always finish refactoring your code before running cdk import
Do not run a regular deployment between cdk orphan and cdk import

Regarding the first point, the list of supported resource types is available in the CloudFormation resource import documentation.

As for the second point, cdk import synthesizes your local code to determine where to import resources. If you run it with the pre-refactoring code, the resource is imported back into its original position.

Regarding the third point, if you deploy in between, the queue definition in your code is created as a new, empty resource separate from the existing queue.

3. Setting the Construct ID to Default

The third method is to set the resource's construct ID to Default inside the custom construct you extract to. Since logical IDs are generated from paths, the idea is to assign construct IDs so that the path stays the same after refactoring. Unlike the two methods so far, no additional commands are needed.

3-1. L1 Constructs and Paths

As background for this method, let's take a closer look at the path of the queue in our example. Inside an L2 construct such as Queue, an L1 construct that corresponds one-to-one with the CloudFormation resource is actually defined, with the construct ID Resource. Therefore, the actual path used to calculate the logical ID is MyStack/Queue/Resource, and Queue4A7E3555 was generated from it. This is also why the paths in the example run in 1-1 ended with /Resource.

3-2. Keeping the Logical ID with Default

When AWS CDK determines a logical ID, it excludes the string Default from the path components used in the calculation. Taking advantage of this behavior, set the construct ID of the queue whose logical ID you want to keep to Default inside the extracted custom construct. Then, give the Notifications construct the same construct ID as the pre-extraction queue, namely Queue.

With this, the path of the queue's L1 construct becomes MyStack/Queue/Default/Resource. Since Default is excluded from the calculation, the logical ID remains Queue4A7E3555, the same as before the extraction. All that's left is to run cdk deploy as usual. In this deployment, nothing happens to the queue, whose logical ID is unchanged, and only the other changes, such as the topic's replacement, are applied. The code is as follows:

export class Notifications extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // The path becomes MyStack/Queue/Default/Resource, so the logical ID does not change
    new Queue(this, 'Default');

    // The topic's logical ID changes, but we accept its replacement
    new Topic(this, 'Topic');
  }
}

// Give the construct the same ID as the pre-extraction queue, 'Queue'
new Notifications(this, 'Queue');

3-3. Conditions for Applying This Method

To apply this method, the following two conditions must be met:

Only one resource inside the extracted custom construct needs to keep its logical ID
The construct ID of the extracted custom construct is the same as the original ID of the resource or construct being moved

Regarding the first condition, only one Default can exist under the same parent. In the example above as well, the queue is the only resource whose logical ID is kept, and the topic's replacement is accepted as assumed. On the other hand, you can have any number of resources that do not need to keep their logical IDs inside the construct. Along with newly added resources, you can also move existing resources whose replacement is acceptable, like the topic in our example.

As for the second condition, in the example above we gave Notifications the construct ID Queue, so this method cannot be used if you want to give the construct a different name as part of the extraction.

This method is effective for extractions centered on a single resource you want to protect from replacement. The relationship between paths and logical IDs so far is summarized below.

4. Overriding the Logical ID

The last method is to pin the logical ID, which AWS CDK normally determines automatically, to its pre-refactoring value. As long as the logical ID does not change, CloudFormation sees the resource as the same one. So all you need to do is apply the refactored code with a regular cdk deploy. During the deployment, nothing happens to the resources whose logical IDs are pinned, and only the other changes are applied. Since this method also works for resource types not supported by resource import, it serves as a last resort when the other methods cannot be used. There are two ways to pin the logical ID.

4-1. Pinning with overrideLogicalId

AWS CDK has a mechanism called an escape hatch, which lets you take out the L1 construct inside an L2 construct and manipulate it directly. As shown below, retrieve the L1 construct through defaultChild of the node property that every construct has, and pass the pre-refactoring logical ID to overrideLogicalId.

export class Notifications extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const queue = new Queue(this, 'Queue');

    // Pin the logical ID to its pre-refactoring value (the topic is not pinned, accepting its replacement)
    const cfnQueue = queue.node.defaultChild as CfnQueue;
    cfnQueue.overrideLogicalId('Queue4A7E3555');

    new Topic(this, 'Topic');
  }
}

4-2. Pinning with renameLogicalId

The other way is the stack's renameLogicalId method. This one operates on the logical ID itself, without going through constructs. Therefore, it also works for resources that cannot be retrieved with defaultChild, such as related resources that an L2 construct generates internally.

Use it in the following order. First, run cdk synth once on the code with only the refactoring applied, and check the newly generated logical ID in the output template. Then, as shown below, add a renameLogicalId call with the logical ID you checked as the first argument and the pre-refactoring logical ID you want to keep as the second.

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Resource definitions omitted

    this.renameLogicalId('NotificationsQueue91395D8F', 'Queue4A7E3555');
  }
}

4-3. Downside: The Pinning Code Remains

The downside of this method is that the code pinning the logical ID remains after the refactoring. Since it leaves a value that AWS CDK normally determines automatically explicitly specified, it is a good idea to leave a comment explaining why the ID is pinned.

How to Choose Among the Methods

If no resource you want to protect from replacement is moved, no countermeasure is needed and you can simply deploy. If one is needed, first consider cdk refactor, which completes with a single command. If your configuration does not allow it, consider cdk orphan + cdk import. If that is not an option either, use the construct ID Default approach when the extraction you want to perform meets the conditions in 3-3, and otherwise use logical ID overriding as a last resort.

Appendix 1. Accepting Replacement of Stateless Resources

As mentioned earlier, you do not need to prevent replacement for every resource. So which resources can tolerate replacement? Stateless resources, such as Lambda functions and the SNS topic in our example, hold no data, so replacing them is generally not a problem. What mainly needs protection are resources that lose their data when replaced, such as Amazon DynamoDB tables, Amazon S3 buckets, and the queue in our example. Accepting replacement for everything else greatly reduces the effort of refactoring.

Appendix 2. Leaving Physical Names Unspecified

When you accept replacement, be careful with how resource physical names are handled. A physical name is the actual resource name on AWS, such as a bucket name or a function name. In a CloudFormation replacement, the new resource is created first, and the old one is deleted afterward. Consequently, if your code specifies a physical name, the original resource with the same name still exists at creation time, and the deployment fails with an "already exists" error.

The basic way to avoid this is not to specify physical names. If omitted, a unique name is generated automatically, so names never collide during replacement. Leaving physical names unspecified also gives you more flexibility for refactoring.

Conclusion

In this article, I introduced the following four methods for refactoring safely in AWS CDK:

The cdk refactor command
The cdk orphan + cdk import commands
Setting the construct ID to Default
Overriding the logical ID

Knowing these methods lets you clean up your code with confidence, even for stacks that are already released. Alongside them, accepting the replacement of stateless resources and leaving physical names unspecified are also effective policies. I hope you will incorporate these techniques into your daily development.

Orchestrating workflows with Amazon S3 Files and AWS Lambda durable functions using Java SDK - Part 8 AI Agents with Spring AI on AgentCore Runtime

Vadym Kazulkin — Mon, 05 Oct 2026 14:30:00 +0000

Introduction

In part 7, we transformed our application into an agentic one. We replaced the search for YouTube and upcoming talks with the AgentCore Gateway Web Search Tool. Also, we used the Spring AI framework to implement the AI agent and AWS Lambda to host it. This might be sufficient for very simple agents, as AWS Lambda has its limitations of a 15-minute execution duration and isn't very efficient for agents spending a lot of time waiting on I/O.

In this part of the series, we'll show how to host those AI agents on the Amazon Bedrock AgentCore Runtime instead. AgentCore Runtime provides a secure, serverless, and purpose-built hosting environment for deploying and running AI agents or tools. I wrote an article series about AgentCore Runtime, which I refer to.

There are multiple good articles that highlight the difference between hosting the agents on AWS Lambda vs Amazon Bedrock AgentCore Runtime:

Sample application using AgentCore Gateway Web Search Tool and Spring AI hosted on Amazon Bedrock AgentCore Runtime

The target architecture of our sample application looks like this:

Instead of hosting the AI Agents for searching for upcoming talks and YouTube videos in the Lambda function, we bundle them and deploy them together on AgentCore Runtime. We expose this agent via the HTTP protocol. In this case, bundling agents works fine. It's because we can parameterize our prompt to instruct the agent to search either for upcoming talks or for YouTube videos. There are cases where it's beneficial to have different agents and host them separately (on AgentCore Runtime). We still use a Lambda function per agent to invoke our agent hosted on AgentCore Runtime, using the AWS Java SDK.

You can find the final version of the application in my aws-s3-files-lambda-durable-functions-as-ai-agents-orchestrator-java-25 repository.

Here we find the following subdirectories:

The agent implementation. It contains the same business logic that we described in part 7, but now it's a pure Spring Boot application. It should be dockerized to be deployed on AgentCore Runtime. I gave a detailed explanation of how to do it in my article Building AI Agents with Spring AI and Amazon Bedrock AgentCore – Part 5 Deploy MCP client for Conference application on AgentCore Runtime.
The Infrastructure as Code based on AWS CDK for Java. We covered it partially in part 7. In addition to AgentCore Gateway and Cognito stack, we now have to create AgentCore Runtime stack. I also refer to my article Deploy MCP client for Conference application on AgentCore Runtime for the detailed explanation of this step. After AgentCore Runtime is created, we have to grab its Runtime ARN. We'll see it in the console output, or we can find it on the AWS AgentCore Runtime service page.
The Agent orchestrator implementation with AWS Lambda durable function. The biggest difference to the business logic from part 7 is the implementation of the UpcomingTalksExtractor and YouTubeVideosExtractor Lambda functions. They both inherit from the BaseContentExtractor, which provides the search method both Lambda functions use:

   default public <T> T search(Author author, String searchTopic, 
     int maxNumberOfResults, Class<T> clazz)  throws Exception {
       var payload = """
           {
    "prompt":"Do a web search for the %s authored by %s %s. Provide maximum %d results. Your response should be in JSON format. Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.",
    "resultType": "%s"
           }
       """.formatted(searchTopic, author.firstName(), author.lastName()
       , maxNumberOfResults, clazz.getName());

      var httpClient=ApacheHttpClient.builder()
         .connectionTimeout(Duration.ofMinutes(5))
         .socketTimeout(Duration.ofMinutes(5))
         .build();

     var bedrockAgentCoreClient = BedrockAgentCoreClient.builder()               
         .region(Region.of(System.getenv("REGION")))
         .httpClient(httpClient)
         .build();

     var AGENT_RUNTIME_ARN= System.getenv("AGENTCORE_RUNTIME_ARN");

     var invokeAgentRuntimeRequest = InvokeAgentRuntimeRequest.builder()
          .agentRuntimeArn(AGENT_RUNTIME_ARN)                                          
          .qualifier("DEFAULT")
          .contentType("application/json")
          .payload(SdkBytes.fromUtf8String(payload))
          .build();

     try (var responseStream = bedrockAgentCoreClient.invokeAgentRuntime(invokeAgentRuntimeRequest)) {

      var response = new String(responseStream.readAllBytes(), StandardCharsets.UTF_8);
      return OBJECT_MAPPER.readValue(response, clazz);
     }
}

First, we parameterize the prompt by providing:

the search topic (YouTube videos or upcoming talks)
content author first and last name
maximum number of results
the result type (YouTubeVideos.class or UpcomingTalks.class depending on the search topic).

Next, we use the AWS Java SDK to create an InvokeAgentRuntimeRequest with the constructed prompt and AgentCore Runtime ARN, which we retrieve from an environment variable AGENTCORE_RUNTIME_ARN. We set the value of this variable in the AWS SAM template. This value should correspond to the Runtime ARN we created in the IaC part described earlier. Here is an example of how to do it for the YouTubeVideosExtractorFunction Lambda function:

 YouTubeVideosExtractorFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: YouTubeVideosAIAgentExtractor
      Handler: dev.vkazulkin.handler.YouTubeVideosExtractor::handleRequest
      Environment:
        Variables:
          AGENTCORE_RUNTIME_ARN: !Sub arn:aws:bedrock-agentcore:${AWS::Region}:${AWS::AccountId}:runtime/RuntimeForAuthorContentAgenticSearch-LBaMJZGabnk
      Policies:
          - Version: '2012-10-17'
            Statement:
              - Sid: InvokeRuntime
                Effect: Allow
                Action:
                  - bedrock-agentcore:*Runtime*
                  - bedrock-agentcore:*WorkloadIdentity
                  - bedrock-agentcore:*CredentialProvider
                  - bedrock-agentcore:*Token*
                  - bedrock-agentcore:*Access*
                Resource: 'arn:aws:bedrock-agentcore:*:*:*runtime*'

We also need to give this Lambda function permissions to invoke the AgentCore Runtime. We have to do the same for the UpcomingTalksExtractorFunction Lambda function as well. After that, create a BedrockAgentCoreClient client to execute this request. Lastly, we convert an LLM response in JSON format to the specified result type and return it.

Once again, I gave a detailed explanation of this step in my article Deploy MCP client for Conference application on AgentCore Runtime.

Building, packaging, deploying, and testing our sample application

Now we can build and package our application with mvn clean package and deploy it with sam deploy. The deployment process can take up to 10 minutes because of the creation and mounting of S3 Files. Please follow the steps from part 7 to test the application, as they are exactly the same. Our Lambda durable function executes exactly the same steps, so the output will be the same. The only difference is that I renamed the Lambda Durable function in this project to AuthorContentExtractorAIAgentsOrchestrator.

Conclusion

In this part of the series, we showed how to host AI agents, which our Lambda durable function orchestrates, on the AgentCore Runtime.

If you like my content, please follow me on GitHub and give my repositories a star!

Please also check out my website for more technical content and upcoming public speaking activities.

Agent memory needs more than vector search

Allen Helton — Tue, 29 Sep 2026 14:28:49 +0000

Over the past couple of years I've tried several times to teach an AI agent how to impersonate my voice. While I haven't been super successful, it's been a wonderful learning opportunity for me to dig into RAG, agent memory, and other advanced topics.

I've iterated quite a bit on my original design, which was mostly just stuffing entire blog posts into the system prompt as examples. I built an interesting version of agent memory that had its shortcomings. Then I swapped over to Oracle and designed a hybrid search with three layers of memory, which was objectively better. But it still wasn't perfect.

Actually, the memory part is pretty good. It's the retrieval part that was leaving something on the table. It's taken me a long time to figure out where I was going wrong with loading relevant few-shot examples. Let's see if you can spot the problem:

SELECT id, content, topic, VECTOR_DISTANCE(embedding, :q, COSINE) AS distance
FROM posts
WHERE user_id = :userId AND platform = :platform AND is_deleted = 0
ORDER BY distance
FETCH APPROX FIRST :k ROWS ONLY

Did you find it?

No? Well, that's because there's nothing technically wrong with it. It finds the memories most similar to the question. The problem is that the most similar memory isn't always the right memory.

Memories pile up. After a few years of writing, my store has a post where I argued for one approach and a newer one where I'd changed my mind. It has posts on event-driven architecture, event sourcing, and event streaming that are all very similar to each other in the embedding space. It has a post on serverless pricing and one on cold starts that use the same vocabulary but make completely different points. As far as similarity scores go, these groups are basically the same thing. It just comes down to a date, a specific term, or the actual point of the post.

So retrieval worked, but my context was garbage.

The standard fix is a reranker, which helps to improve relevance instead of just similarity.

When you embed a memory, the model has no idea what will be asked of it later. Your query gets embedded and a similarity score is calculated against the embeddings in the store. A cross-encoder (a specific type of reranking model) looks at the query and memory together and scores them by how well a memory answers the question. This means the relevance is higher, and it often leads to better results.

But there's a catch (of course).

A cross-encoder runs at query time, once per candidate, on every request. That means added latency to your query. 🙃

But if the relevance of the results is meaningfully better, that makes up for the increased latency, right? To a point, yes. If the latency is so high the user experience suffers, it's probably not worth the cost. But if it's relatively minor, then absolutely.

So I built a benchmark to evaluate the tradeoff. I started from the evaluation plan in Oracle's production RAG evaluation guide, which compares keyword, vector, and hybrid retrieval against judged queries. Then I pushed it one step further and put a reranker on top of each, to see how much relevance I got for the latency cost. For the reranker, I used the BGE reranker loaded into the database as an ONNX model, so scoring happens directly in the query with no extra service to call. 🔥

Let's dive in. The results are fascinating.

Before I continue, thank you to Oracle for sponsoring this post. Opinions are my own.

Filter first, then rank

RAG is cool because it involves multiple kinds of lookups. You have lexical retrieval, which is great for identifiers, codes, and names. You also have vector retrieval, which finds semantically similar data via embeddings. I benchmarked both on their own and together as a hybrid search, fusing the two ranked lists with reciprocal rank fusion (RRF).

Both paths run the same scope filter:

WHERE TENANT = :tenant
  AND (OWNER_ID IS NULL OR OWNER_ID = :owner)
  AND (EXPIRES_AT IS NULL OR EXPIRES_AT > SYSDATE)

I share this because the WHERE clause handles eligibility, which is different from relevance. I don't want an expired memory coming back in my results, like a 2025 take on building AI agents that I've since moved past. And I definitely don't want another tenant's data showing up (security nightmare). Oracle's guide calls these filters mandatory for multi-tenant data. They run before ranking, so everything downstream only deals with memories that are allowed to be there.

Setting the baseline

Before I could tell whether a reranker was worth anything, I needed to know the baseline values for these queries. In addition to latency, I also needed to know the normalized discounted cumulative gain (nDCG) and recall. Capturing these metrics lets us objectively measure relevance alongside latency.

The baseline measurements were taken with K=10, meaning I took the top 10 results.

Retrieval	nDCG@10	Recall@10	Median latency
Vector	0.753	0.865	20.0 ms
Lexical	0.727	0.740	4.7 ms
Hybrid RRF	0.832	0.885	20.5 ms

nDCG measures how well a ranking puts relevant items near the top, with higher being better. It's not a measure of how many answers were right, though. Vector's 0.753 means that the rankings earned 75% of the score a perfect ordering would have, on average.

Recall ignores order. It tells you whether the correct memories made it into the top 10 at all. A 0.865 means that about 87% of the memories that should have come back did. Both of these metrics are evaluated against a known ground-truth set of data in order to be objective. Meaning I know ahead of time what the results should have been given the corpus and the query I was benchmarking.

You can see from these results that lexical is fast, but it's not super accurate. Vector catches more at the cost of latency, but still ranks them worse than I'd want. Fusing the two rankings had the best results, with minimal additional latency.

From the baseline results alone, it looks like a hybrid search will be the retrieval method to beat if latency doesn't drop off a cliff.

The enlightening reranker results

Now to run the same benchmark with the reranker. In Oracle, it's one more step at the end of the retrieval query. Retrieval narrows everything down to the top candidates, and PREDICTION() runs the cross-encoder against each one:

SELECT id,
       PREDICTION(BGE_RERANKER USING
         :query || '</s></s> ' || title || '. ' || content AS DATA) AS score
FROM candidates
ORDER BY score DESC
FETCH FIRST 10 ROWS ONLY;

The </s></s> is the delimiter the model expects between a query and a passage. I'm only pulling back the ids and the reranked scores for the benchmark. And you might notice that the reranking is done entirely in the database query - super cool.

Configuration	nDCG@10	Recall@10	Median latency
Hybrid, no reranker	0.832	0.885	20.5 ms
Hybrid + reranker, 10 candidates	0.832	0.885	585 ms
Vector + reranker, 20 candidates	0.830	0.896	1,258 ms

Surprisingly, adding the reranker to hybrid search didn't do anything to nDCG at all. The best reranked score came from vector retrieval with 20 candidates, and it still scored lower than plain hybrid with no reranker, at 61 times the latency. It found slightly more of the right memories, but ranked them a little worse.

I also tried giving the reranker more to work with. For vector retrieval, latency grew linearly with candidate count (1,258ms at 20 candidates and 2,604ms at 40), and nothing got meaningfully better.

That doesn't mean the reranker did nothing, though. I dug a little deeper and took the change for each query and resampled them 2,000 times to see how much the average varies depending on which queries you run. 95% of the resampled averages landed between -0.079 and +0.073.

And if we use that range, +0.073 would take hybrid from 0.832 to 0.905, which is a meaningful improvement. But conversely, the other end of the spectrum would drop it to 0.753, which is where plain vector search started.

Given the range, the results are inconclusive, at least with my sample size of 16 queries. The real effect could be a solid improvement, nothing at all, or even a loss, and 16 queries can't tell those apart.

This ended up being a big realization for me. Relevance is measurable, but how confident you can be depends on how many judged queries you have. A couple thousand iterations of 16 queries is still only 16 queries, and that's why the range is so wide.

Meanwhile, the latency hit is pretty obvious. It was nearly 30 times slower for every request. Now I had to ask myself when that latency is worth it.

Where rerankers make sense

Stay with me. Rerankers have lots of value despite what we've discussed so far. The underwhelming results are because I improved retrieval quality in a cheaper way. Let's look again at the baseline compared to the reranked version:

First stage	No reranker	10 candidates	20 candidates	40 candidates
Lexical	0.727	0.800	0.801	0.809
Vector	0.753	0.821	0.830	0.814
Hybrid RRF	0.832	0.832	0.829	0.817

Intuitively, the weaker retrieval methods got the most out of reranking. Lexical and vector each gained about 0.075, while hybrid gained nothing.

Which makes sense because a reranker doesn't retrieve anything. It reorders (or re-ranks 😄) what it's given. If your first stage is already pulling the correct memories into the pool in a sensible order, there's nothing left to fix.

Reranking vector retrieval with 20 candidates left me a little curious because it made the top five less alike. I measured it a couple of different ways (with embeddings and with plain word overlap) and verified the numbers. Thinking about it though, that is desired behavior. Remember that memory lookalike issue I talked about? The cross-encoder is separating the right memory from its lookalikes and pushing the lookalikes down. Which is exactly what I said I wanted.

The takeaway I want you to leave with is that you should rerank when you have one retrieval signal, and fuse when you have two. Doing both leaves you paying for additional latency you don't need.

My new approach

I started this wanting to know whether a reranker was worth the extra inference. After running through several rounds of benchmarks and tweaking queries, I'm not sure that was the right question. My approach to the problem is much more informed and now walks a different path than I expected.

When building a RAG pipeline for memory, I'll always filter first. Owner, expiration, whatever makes a memory eligible for you. Apply these in the query before anything gets ranked. Reducing the number of candidates means fewer memories to rank (plus, you know, security and quality and all that 😜).

Next, I'd add a second retrieval signal before adding a reranking model. If you have vector search, add lexical. If you have lexical, add vector. Fuse the rankings with RRF. Doing that with my tests took nDCG@10 from 0.75 with vector retrieval to 0.83 and only slowed my query down by half a millisecond.

After adding the second retrieval signal, I'd measure everything. Write down 15 to 20 real requests you'd give your agent, making sure to include some difficult ones and edge cases. Things like asking for exact keyword lookups, or for advice on something you've changed your mind on a couple of times. Keep those handy. The guide I was following says to rerun them every time you change chunking, the embedding model, or the reranker, and it's right.

Then you can try a reranker against your baseline. Try a few different candidate counts (:n in the query above). Check whether the quality difference is consistently higher across your queries and decide if the additional latency is worth the quality difference.

Luckily for me, what I built in my original post doesn't need to change much. I still have the same tables and the same reflection loop. I'm really just updating the database query that decides which memories the agent sees.

Try it yourself

The benchmark and instructions to try it all yourself are available in GitHub. It spins up Oracle AI Database Free in Docker, generates a synthetic corpus of 480 memories and 16 judged queries, loads the ONNX models, and runs the whole thing.

Everything we've discussed today ran on Free in Docker, capped at two CPUs and 2 GB. It's an intentionally small box, because we aren't running a capacity benchmark and none of these numbers should be used for sizing anything.

If you want to run this kind of evaluation on your own retrieval, start with Oracle's production RAG evaluation guide. It covers more than what we talked about here, like grading the generated answer and testing freshness, tenant isolation, and when the agent should refuse to answer. It's pretty solid.

Agent memory needs more than vector search. Turns out, just using vector search means you're asking a single similarity score to decide what's relevant, current, and yours. Fortunately for all of us, "more" is a lot cheaper than I assumed.

Happy coding!

Orchestrating workflows with Amazon S3 Files and AWS Lambda durable functions using Java SDK - Part 7 AI Agents with Spring AI and AgentCore on AWS Lambda

Vadym Kazulkin — Mon, 28 Sep 2026 14:30:00 +0000

Introduction

In part 6 of the series, we moved the logic associated with each step into a separate Lambda function. We explored how to invoke another Lambda function within the durable step. Also, we showed how to invoke multiple Lambda functions in parallel.

In this article, we'll transform our application into an agentic one. Currently, the search for YouTube and upcoming talks returns static content. We'll replace it with the Amazon Bedrock AgentCore Gateway Web Search Tool. As it's exposed via MCP, we need an MCP client to connect to it. For that, we'll use the Spring AI framework. First, we still use AWS Lambda to host the AI agents. In later parts, we'll show how to host those AI agents on Amazon Bedrock AgentCore Runtime instead.

The question is whether it'd be appropriate to host our AI agents on AWS Lambda. Our agents are really simple and return a constant amount of data. They also have a nearly constant context size. We don't need the flexibility of Firecracker, including the ability to grow and shrink the CPU and memory usage of VMs in place. Also, our agents are stateless, so we don't need the AgentCore support of stateful streamable-HTTP MCP servers. For such agents, it's feasible to host them on AWS Lambda.

Introduction to Spring AI framework

I've written an entire article series on the Spring AI framework and have also heavily used this framework in my article series Building AI Agents with Spring AI and Amazon Bedrock AgentCore. I refer to them to understand the basics. Spring AI is based on Spring Boot, but we have pure Lambda functions in our application instead. So, we need to have a Spring context to use Spring AI. How can we achieve it?

How to convert AWS Lambda to a Spring (Boot) Application

I've written another article series about Spring Boot 3.4 applications on AWS Lambda where I introduced 3 approaches to convert AWS Lambda to a Spring (Boot) Application :

In this article, I'll go for AWS Serverless Java Container for Spring Boot.

Sample application using AgentCore Gateway Web Search Tool and Spring AI hosted on AWS Lambda

The target architecture of our sample application looks like this:

I first copied the application that we created in part 6 into the aws-s3-files-lambda-durable-functions-spring-ai-agentcore-gateway-web-search-tool repository. We explain step by step how to adjust our application. Please go through the content of part 6 to understand the sample application and the basic concepts of Lambda durable functions. There will be some changes in the Infrastructure as Code (IaC) part as well.

First, let's import some important dependencies in the pom.xml. Those include:

aws-serverless-java-container-springboot4 (to use AWS Serverless Java Spring Boot 4 Container)
spring-ai-starter-mcp-client (to use Spring AI MCP Client)
spring-ai-starter-model-bedrock-converse (to use Spring AI Bedrock Converse API)
others

Next, let's create the Spring Boot AuthorContentWebSearchExtractorController controller:

@RestController
public class AuthorContentWebSearchExtractorController { 
...

    @RequestMapping(path = "/author/content/youtubeVideos", method = RequestMethod.GET, 
   consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public YouTubeVideos searchForYouTubeVideos(@RequestBody Author author) {
        return this.webSearch(author,"YouTube videos", 3 ,YouTubeVideos.class);
    }


   @RequestMapping(path = "/author/content/upcomingTalks", method = RequestMethod.GET, 
   consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public UpcomingTalks searchForUpcomingTalks(@RequestBody Author author) {
        return this.webSearch(author, "upcoming talks", 3, UpcomingTalks.class);
    }
....

Here we define 2 (web search) GET methods, searchForYouTubeVideos and searchForUpcomingTalks, with the specified path and incoming and outgoing media types. They both receive the JSON representation of the Author class in their HTTP body. We can also modify our application to receive first and last name as request parameters. For this, we also need to adjust both paths, for example, to /author/content/upcomingTalks/{firstname}/{lastname}. We'll take care of the implementation of the websearch method later.

The controller is a standard Spring Boot controller where we have access to the whole Spring Boot (web) functionality.

Our Lambda durable function AuthorContentExtractor looks very similar to the function we defined in part 6. Here we invoke in parallel 2 Lambda functions: UpcomingTalksWebSearchExtractor and YouTubeVideosWebSearchExtractor. We'll transform exactly those 2 functions, so they perform the agentic search for the content instead of returning the static one. When we invoke them, we pass an object of type Author as a payload. Our Lambda durable function AuthorContentExtractor receives this payload as its input.

The question is how to transform this payload into the HTTP requests which 2 methods of the AuthorContentWebSearchExtractorController receive. This is exactly the functionality that AWS Serverless Java Spring Boot 4 Container provides to us. This framework does this transformation automatically in case the input payload comes from Amazon API Gateway. The payload should be of either type APIGatewayProxyRequestEvent (REST API) or type APIGatewayV2HTTPEvent (HTTP API). For more information, please read the Invoking a Lambda function using an Amazon API Gateway endpoint article. In such a case, we can use the generic Lambda handler com.amazonaws.serverless.proxy.spring.SpringDelegatingLambdaContainerHandler to do the job. Nevertheless, AWS Serverless Java Spring Boot 4 Container offers the functionality to convert and proxy any request to one described above. In our sample application, we'll use the APIGatewayProxyRequestEvent request event. Let's explain how to do it.

Both Lambda functions, UpcomingTalksWebSearchExtractor and YouTubeVideosWebSearchExtractor.java, recieve the input request of type Author. The only difference is that they should convert this request into an APIGatewayProxyRequestEvent request event and proxy it to different paths. We define those paths in the Lambda function itself.

For the UpcomingTalksWebSearchExtractor Lambda function, it looks like this:

public class UpcomingTalksWebSearchExtractor extends AuthorContentWebSearchExtractor {

@Override
protected String getPath() {
    return "/author/content/upcomingTalks";
   }
}

The path /author/content/upcomingTalks exactly matches the path of the request mapping in the controller:

   @RequestMapping(path = "/author/content/upcomingTalks", method = RequestMethod.GET, 
   consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public UpcomingTalks searchForUpcomingTalks(@RequestBody Author author) {
        return this.webSearch(author, "upcoming talks", 3, UpcomingTalks.class);
    }

So this Lambda function will proxy the incoming request to the controller's searchForUpcomingTalks method.

For the YouTubeVideosWebSearchExtractor Lambda function, it looks like this:

public class YouTubeVideosWebSearchExtractor extends AuthorContentWebSearchExtractor {

@Override
protected String getPath() {
    return "/author/content/youtubeVideos";
   }
}

The path /author/content/youtubeVideos exactly matches the path of the request mapping in the controller:

    @RequestMapping(path = "/author/content/youtubeVideos", method = RequestMethod.GET, 
   consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
    public YouTubeVideos searchForYouTubeVideos(@RequestBody Author author) {

    return this.webSearch(author,"YouTube videos", 3 ,YouTubeVideos.class);
    }

So this Lambda function will proxy the incoming request to the controller's searchForYouTubeVideos method.

The generic business logic that performs the conversion is in the AuthorContentWebSearchExtractor class:

abstract class AuthorContentWebSearchExtractor implements RequestStreamHandler {

private static SpringBootLambdaContainerHandler<AwsProxyRequest, AwsProxyResponse> handler = 
SpringBootLambdaContainerHandler.getAwsProxyHandler(Application.class)

@Override
public void handleRequest(InputStream inputStream, 
  OutputStream outputStream, Context context) throws IOException {
    var author = new String(inputStream.readAllBytes(), StandardCharsets.UTF_8);
    var proxyRequestEvent = this.getAwsProxyRequest(author);
    var response = handler.proxy(proxyRequestEvent, context);
    var body = response.getBody();
    try (var printStream = new PrintStream(outputStream, 
        true, StandardCharsets.UTF_8)) {
            printStream.print(body);
        }
    }

private AwsProxyRequest getAwsProxyRequest (String author) {
    var awsProxyRequest = new AwsProxyRequest ();
    awsProxyRequest.setHttpMethod("GET");
    awsProxyRequest.setPath(this.getPath());
    awsProxyRequest.setBody(author);

    var header= new SingleValueHeaders();
    header.put("Content-Type", "application/json");
    awsProxyRequest.setHeaders(header);

    var headers= new Headers();
    headers.add("Content-Type", "application/json");
    awsProxyRequest.setMultiValueHeaders(headers);

    var awsProxyRequestContext = new AwsProxyRequestContext();
    var apiGatewayRequestIdentity= new ApiGatewayRequestIdentity();
    apiGatewayRequestIdentity.setApiKey("blabla");
    awsProxyRequestContext.setIdentity(apiGatewayRequestIdentity);
    awsProxyRequest.setRequestContext(awsProxyRequestContext);

    return awsProxyRequest;        
}

 protected abstract String getPath();
}

Let's go step by step through the code. As we see, our class implements the RequestStreamHandler class. First, we instantiate the SpringBootLambdaContainerHandler handler with the proxy request and response type and the main entry point of the Spring Boot Application class. In the handleRequest method, we convert the input stream into a JSON representation of the Author object. We use it in the getAwsProxyRequest method to create the AwsProxyRequest object, which represents the APIGatewayProxyRequestEvent request event. To do so, we set several properties:

HTTP Method as GET (should be the same as the HTTP method of both controllers' methods).
path (each of the 2 Lambda functions sets its own path as described above).
HTTP body (we set the Author object) as required by the 2 Lambda functions.
header and multi-value headers with the content type of application/json.
some dummy settings for request content and API Gateway request identity. It leads to an error if we don't set them.

After having created the AwsProxyRequest object, we use the handler to proxy it. By doing so, the appropriate method of the AuthorContentWebSearchExtractorController will be invoked. As a result, we get an object of the type AwsProxyResponse, which contains the response of the controller's method. This response is either of type UpcomingTalks or of type YouTubeVideos depending on the method invoked. We get this response by invoking the body method, and then we inject it into the output stream. With that, our Lambda durable function receives the response of the Lambda invocation.

Now let's implement the webSearch method of the controller. This method implements the web search for the given author content (either upcoming talks or YouTube videos) using the Amazon Bedrock AgentCore Gateway Web Search Tool.

Introduction to the Amazon Bedrock AgentCore Gateway Web Search Tool

AI agents are transforming how organizations interact with information, but they face a fundamental limitation: their knowledge is frozen at training time. When a user asks about today’s stock prices or a software release that shipped an hour ago, an agent relying solely on its training data cannot provide accurate answers.

Building custom web search integrations to solve this is costly — procuring third-party search APIs, managing keys and quotas and rate limits, parsing inconsistent result formats across providers, building snippet extraction logic so models get relevant passages instead of raw HTML, reasoning about where customer queries travel and how data might be retained, and maintaining freshness and coverage over time. Each of these is a project in itself.

Web Search Tool on Amazon Bedrock AgentCore eliminates that complexity. It is a fully managed, MCP-compliant web search capability that lets your agents retrieve information from the web without any infrastructure overhead. It is available as a managed connector that you connect to your AgentCore Gateway. Agents discover it with a standard tools/list call and invoke it like any other Model Context Protocol tool. There are no search APIs to provision, no outbound credentials to manage, and no result-parsing glue to maintain.

How to set up the Amazon Bedrock AgentCore Gateway Web Search Tool

I refer to the article Introducing Web Search on Amazon Bedrock AgentCore, which describes everything you need to set it up. Currently, there is no IaC CDK support for the Web Search Tool, but setting it up manually takes minutes.

As a small help, I provided the spring-ai-2.0-ai-agents-on-agentcore-runtime/cdk repository that uses AWS CDK in Java. Please execute the Cognio and Gateway stacks. Then, manually add a Gateway MCP Target with the Web Search tool connector as shown in the pictures above.

The created Bedrock AgentCore Gateway should look similar to this one:

We'll need the Gateway Resource ARN and Gateway Resource URL later. Then we need to create the AgentCore Target by selecting the MCP Target and Web Search tool in the Connectors section:

We'll need to define an IAM role with the following policy, as described in the article above:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "InvokeWebSearchTool",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeWebSearch",
            "Resource": "arn:aws:bedrock-agentcore:us-east-1:aws:tool/web-search.v1"
        },
        {
            "Sid": "InvokeGateway",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeGateway",
            "Resource": "{YOUR_AGENTCORE_GATEWAY_ARN}"
        }
    ]
}

Please replace the {YOUR_AGENTCORE_GATEWAY_ARN} with the ARN of your created AgentCore Gateway.

Another question is how to set up the inbound authorization of our AgentCore Gateway. We can put it completely public, which is not recommended. Another alternative is to use IAM-based inbound authorization. In this article, we'll use JSON Web Token (JWT)-based inbound authorization with Amazon Cognito as an identity provider as we see in the picture above. I won't go into the details of how to create and configure the Cognito User (Client) Pool, but refer to my following articles:

Deploy Conference Search application on AgentCore Runtime. Here I provided IaC and an explanation of how to create the Cognito User (Client) Pool.
Provide MCP tools for Conference application via AgentCore Gateway. Here I provided IaC and an explanation of how to configure the inbound authorization for the AgentCore Gateway with Amazon Cognito as an identity provider.

Alternatively, please look into the Cognito and Gateway stack of the spring-ai-2.0-ai-agents-on-agentcore-runtime/cdk repository for an example of how to set it up.

How to implement the Amazon Bedrock AgentCore Gateway Web Search Tool using Spring AI

I've already covered how to talk to an LLM and use the MCP Client to connect to tools with Spring AI in my following articles:

Please go through those articles first to understand the basics, as we'll reuse much of the business logic. Let's first configure the AgentCore Gateway resource URL and Cognito settings in the application.properties file:

amazon.bedrock.agentcore.gateway.base.url=https://web-search-gateway-XXX.gateway.bedrock-agentcore.us-east-1.amazonaws.com
amazon.bedrock.agentcore.gateway.endpoint=/mcp

cognito.user.pool.name=UserPoolForAuthorContentAgenticSearch
cognito.user.pool.client.name=UserClientPoolForAuthorContentAgenticSearch
cognito.auth.token.resource.server.id=ResourceServerIdAuthorContentAgenticSearch

Please split this URL into 2 parts: the base URL and the endpoint, which is always /mcp.

The implementation of the webSearch method in the AuthorContentWebSearchExtractorController controller looks like this:

private <T> T webSearch(Author author, String searchTopic, 
   int maxNumberOfResults, Class<T> clazz) {

    var token = getAuthTokenViaHttpClient();
    try (var client = McpClient.sync(getMcpClientTransport(token)).build()) {
         client.initialize();
         client.listTools().tools().forEach
             (tool -> LOGGER.info("tool found: " + tool));

          var mcpToolCallbackProvider = SyncMcpToolCallbackProvider.builder()
              .mcpClients(client)
              .build();

       var prompt = """
            Search for the %s given by %s %s. Provide maximum %d results.
            Your response should be in JSON format.
            Do not include any explanations, only provide a RFC8259 compliant JSON response 
            following this format without deviation.
            """.formatted(searchTopic, author.firstName(), author.lastName(), maxNumberOfResults);

       return this.chatClient.prompt().user(prompt)
                    .tools(mcpToolCallbackProvider.getToolCallbacks())
                    .call()
                    .entity(clazz);
    }
}

This is a generic method, which takes the following parameters:

object of type Author.
search topic ("search for upcoming talks" or "search for YouTube videos" in our case)
maximum number of results returned by the Web Search tool. Valid range: 1-25. Defaults to 10.
result type (UpcomingTalks or YouTubeVideos in our case)

First, get the authentication token from Amazon Cognito. We can remove this part, including setting this token in the header of the HTTP Streamable Client, in case our AgentCore isn't secured by the JWT (either public or we use IAM authorization). Next, we create the MCP client and initialize it. After that, we list the MCP tools available; in our case, only the WebSearch tool. Then, we create MCPToolCallbackProvider with the MCP client. Next, we construct the parametrized prompt by passing the author, the search topic, and the number of results. We also advise an LLM to return the response in JSON format, which our Lambda functions require.

Finally, we use the ChatClient from Spring AI to pass the prompt, the tools, and the result type. We implement the last one by using the entity method, which tries to provide the structured LLM output. Once again, for more details about this code, I refer to my articles mentioned above. We invoke the websearch method from the controller's methods searchForUpcomingTalks and searchForYouTubeVideos with different parameters.

IaC for the sample application using AgentCore Gateway Web Search Tool and Spring AI hosted on AWS Lambda

The IaC part in the AWS SAM Template matches what we described in part 6. There are, of course, some differences, as we need to give our 2 Lambda functions, which implement the AI agents, more permissions. We need these permissions to grant those Lambda functions access to the Cognito, AgentCore, and Bedrock services. Here is an example of the UpcomingTalksWebSearchExtractorFunction Lambda function declaration:

UpcomingTalksWebSearchExtractorFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: UpcomingTalksWebSearchExtractor
      Handler: dev.vkazulkin.handler.UpcomingTalksWebSearchExtractor::handleRequest
      Policies:
        - Version: '2012-10-17'
          Statement:
            - Sid: AllowedCognitoActions
              Effect: Allow
              Action:
                - cognito-idp:ListUserPools
                - cognito-idp:ListUserPoolClients
                - cognito-idp:DescribeUserPoolClient
              Resource: '*'
            - Sid: InvokeGateway
              Effect: Allow
              Action:
                - bedrock-agentcore:InvokeGateway
                - bedrock-agentcore:*WorkloadIdentity
                - bedrock-agentcore:*CredentialProvider
                - bedrock-agentcore:*Token*
                - bedrock-agentcore:*Access*
              Resource: 'arn:aws:bedrock-agentcore:*:*:*gateway*'
            - Sid: InvokeRuntime
              Effect: Allow
              Action:
                - bedrock-agentcore:*Runtime*
                - bedrock-agentcore:*WorkloadIdentity
                - bedrock-agentcore:*CredentialProvider
                - bedrock-agentcore:*Token*
                - bedrock-agentcore:*Access*
              Resource: 'arn:aws:bedrock-agentcore:*:*:*runtime*'
            - Sid: InvokeBedrock
              Effect: Allow
              Action:
                - bedrock:InvokeModel
                - bedrock:InvokeModelWithResponseStream
                - bedrock:Converse
                - bedrock:ConverseStream
              Resource: '*'
      Events:
        GetRequest:
          Type: Api
          Properties:
            RestApiId: !Ref MyApi
            Path: /author/content/upcomingTalks
            Method: get

The declaration of the YouTubeVideosWebSearchExtractorFunction Lambda function looks very similar.

Building, packaging, deploying, and testing our sample application

To test our Lambda durable function, we can navigate to the Lambda service, search for the AuthorContentWebSearchExtractor function, and go to the "Test" tab.

We need to pass the following sample JSON Event to it, which represents the author:

{
  "firstName": "Vadym",
  "lastName": "Kazulkin"
}

Then we can test it. After that, we go to the "Durable execution" tab and can see all the execution details:

Let's also look at event history:

We see that this matches what we implemented. Our Lambda durable function invokes 2 Lambda functions in parallel to search for YouTube videos and upcoming talks (each in an individual branch). Then, it awaits the results of both invocations because we defined in the parallel configuration that we wait until all invocations are completed. Then the last Lambda function to write the author content into the file gets invoked. This process is the same as we described in part 6, as the workflows remained the same. We only changed the implementation of 2 Lambda functions responsible for the content search. Now we use the AgentCore Gateway Web Search Tool for it.

Conclusion

In this article, we transformed our application into an agentic one. We replaced the search for YouTube and upcoming talks with the AgentCore Gateway Web Search Tool. Also, we used the Spring AI framework. We used AWS Lambda to host the AI agents.

As we saw, Lambda durable functions provide a lot of building blocks like synchronous and asynchronous steps, invocation of another Lambda function, invoke async, waits, and callbacks (and combinations of both, like wait for the callback), and parallel execution to orchestrate the AI agents and multi-step workflows. We only showed one simple example of how to orchestrate the AI agent by using another Lambda function invocation and parallel execution.

In the next part, we'll show how to host those AI agents on the AgentCore Runtime instead.

If you like my content, please follow me on GitHub and give my repositories a star!

Please also check out my website for more technical content and upcoming public speaking activities.

Monthly Amazon Location Service Updates - 2026.08

Yasunori Kirimoto — Sun, 27 Sep 2026 13:58:07 +0000

Monthly Amazon Location Service Updates - 2026.08

This is a summary of the August updates for Amazon Location Service.

2026.08 Updates

Amazon Location Service now supports POI category and density filtering in map styles
This release adds the poi-categories and poi-density query parameters to the GetStyleDescriptor API, letting developers specify an allowlist of POI categories to display and tune how many POIs appear on the map. Filtering is configured server-side, so maps render only the requested categories, such as Food & Drink, Transit, or Accommodations, at the chosen density with no additional code required on the client side.

Other Info

Amazon Location Service Demo
Official Amazon Location Service demo.

Amazon Location Service Developer Guide
Official Amazon Location Service Documentation.

AWS Geospatial
Official AWS Geospatial samples.

maplibregljs-amazon-location-service-starter
Build environment to get started with Amazon Location Service.

dev.to
Articles on Amazon Location Service.

tags - Amazon Location Service
tags - Try
Notes on Amazon Location Service. (Japanese)

Yasunori Kirimoto for AWS Heroes

Aug 1

Monthly Amazon Location Service Updates - 2026.07

#amazonlocationservice #amazonlocationserviceupdates

1 min read

Which Part Was Me?

Brian Tarbox — Thu, 24 Sep 2026 13:08:15 +0000

Last week I said I was still working on an answer. I have a partial one. It's smaller than I hoped and bigger than I feared.

Here's the question again, for anyone who skipped the last post. (I saw the analytics. I'm fine. I said it a little too fast.) When a tool does in seconds what took me a decade to learn, which part was me?

I started by making a list. Engineers make lists when they're anxious.

Column One

Column one was the stuff I spent years learning that a model now does as well as I do, or better. It was longer than I wanted. Syntax for a dozen languages, most now niche (Assembler, Fortran, Prolog). The exact incantation that makes a linker stop complaining. API surfaces I memorized like phone numbers. Boilerplate. So much boilerplate. I was proud of all of it. Some of it paid for a house.

A lot of it turns out to have been lookup. Very fast lookup, with good taste in what to look up, but lookup. That's the "smaller than I hoped" part. It stung more than I expected.

Column Two

Column two took longer, because the things in it were harder to name. Knowing which problem is worth solving before anyone writes a line. Looking at a clean, confident architecture diagram and feeling that something is wrong before I can say what. Asking the question nobody in the meeting asked. Knowing when the right answer is "don't build it." None of it survives being written down as a rule.

That's the "bigger than I feared" part.

In college I studied Wittgenstein, who spent a lot of time on a question that sounds dumb until it doesn't. How do you know how to follow a rule? Not the rule itself. The applying of it. No rule tells you when it applies. You'd need another rule for that, and another for that one, and eventually you hit bottom on something that isn't a rule at all. It's practice. It's judgment. It's what's left when the lookup is free.

I think that's the part that was me. It's also, inconveniently, the part I can't put on a slide.

So how did I sort the columns? Mostly by remembering an old bug.

The 2 a.m. Lesson

Years ago I worked on Video On Demand at Motorola. We had a system that would run beautifully, then fall over. Not one server. The whole thing, in a cascade. We'd bring it back up, it would be fine, and then it wasn't. We looked for a pattern in time of day, load, content, the phase of the moon. Nothing.

Eventually I noticed something small. The failure always started on the ninth request of a burst. Not the eighth. Not the tenth. The ninth.

I had no idea why that mattered. I stared at it for longer than I'd like to admit. Then I remembered our servers had eight cores. The ninth request was the first one that had to wait. The first one to block.

That pointed us at locking, specifically fair versus unfair locks in Java. A fair lock serves waiting threads in the order they arrived. An unfair one lets newcomers jump the queue. That meant that the 9th request stayed blocked until the burst of traffic cleared, and by that point it had timed out.

Here's the thing. A model today could explain fair and unfair locking better than I could. Point it at the lock and it would probably fix it before lunch. What I'm less sure it could do is notice the nine. The number wasn't in any single log. It was a pattern across dozens of crashes, and its meaning lived in a hardware spec that had never been written down. Maybe a future model spots it. Even then, someone has to decide the ninth request is worth staring at.

That staring is column two. It's also the part I'd been underpricing for 45 years, because it never showed up in a line count.

The Test

Here's the working distinction I landed on. If I can write it down as a rule, it's column one, or it will be soon. If I can only show it by example, it's column two.

This is not a comfortable test. It means the columns aren't fixed. Things migrate. Every time someone writes down a piece of judgment clearly enough, it moves left. Code review heuristics. Architecture patterns. Security checklists. That's the grief I wrote about last time, and it isn't going away.

But the migration has a floor. Every rule you write needs someone to decide when it applies. Wittgenstein's regress doesn't end with a better rule. It ends in practice, not another rule.

What I'm Doing About It

If column two is the part that was me, I should probably invest in it on purpose. Four things so far.

I review agent output like a teaching case, not a chore. When it's wrong, I ask how I knew. Half the time the answer is context it didn't have. The other half is interesting.

I write down the near misses. Not the rules. The stories. Stories carry judgment in a way checklists don't. That's also how I learned most of it in the first place, usually from someone older telling me what went wrong in 1987.

I pair juniors with failures instead of tutorials. A tutorial teaches column one, and a model will beat them at it by lunch.

I stopped apologizing for the staring. Looking at something until you know what's wrong with it is not slowness. It's the job now. Possibly it always was.

Back to the Buoy

Last time I said nobody catches a drifting buoy, and the rower's job is to hold a steady stroke (I wrote the timing program for a regatta and the finish line buoy got cut and started floating downstream). I'd add one thing. Someone also has to notice the buoy moved. Someone on the bank has to say, "Wait. That's not where the finish was."

That's column two. The model rows beautifully. It still doesn't know the buoy was cut.

So which part was me? Less than I thought. The part that remains is the part that was always doing the real work, hiding behind all that syntax. I'm a little embarrassed it took a machine to show me. I'm also relieved it's there.

Anyway. I'm going to go knead some dough. That's where the column two stuff tends to show up.

You're still the bottleneck

Allen Helton — Tue, 22 Sep 2026 14:33:41 +0000

I went to a conference a couple of weeks ago. During the keynote, the speaker asked the audience "how many of you have 40 or more agents running at any given time?" About a dozen hands went up. He then asked "How many of you have 30 or more agents running?" Another dozen. This continued down to 20, 15, 10, 5, and eventually 1. Each time he asked, another 15-25 hands went up in the air.

It wasn't until he got to 1 that I sheepishly put my hand in the air. Luckily I wasn't alone, but it immediately got me thinking. I think we substituted one bad practice for another.

Remember a few months ago when tokenmaxxing was a thing? If you don't, good. You missed a terrible practice. People were taking pride in the amount of tokens they were spending regardless of the value they were getting. I still don't really understand why that was a desirable thing.

Tokenmaxxing has settled down significantly, but I fear that it's been replaced by something equally as bad: agentmaxxing.

A quick Google search will show you there's no consensus on what agentmaxxing means (honestly I thought I made it up until I Googled it). But what I mean when I say it is that developers are taking pride in the number of agents they have running at any given time. Jumping back to that question in the conference keynote, people are running upwards of 40 agents at any given time. 40?

So I asked the person who delivered the keynote how many work streams 40 agents represent. And he told me about 4.

Ok that makes so much more sense. He has four projects he's working in parallel, each one with a single orchestrator and about 9 subagents each actually doing the coding. That's better, but still a problem.

You can't multitask like you think you can

I have bad news. You can't multitask. When you think you're multitasking, you're actually context switching really fast.

The more inputs that demand your attention, the worse it gets. I've had times where I'm talking to my wife, one of my kids starts pulling on my shirt to show me something, the other kid starts crying in the other room, while the dog starts scratching at the door to go outside. At best, I'm going to somehow defer three of them to later and work through them sequentially. At worst, I'm going to walk into the other room and yell into a pillow because I'm overstimulated. 😅

Now, imagine that was four agents reporting back at the same time asking for approval or a design decision or reporting a CI failure on four different projects. With each task that lands back on your plate, you have to reconstruct the mental model of what that app is, what you're trying to do, where the agent left off, then you can act.

Would you be able to handle each one appropriately? Probably not.

Realistically, you'll probably hit the accept button without reading the context of the ask and tell your agents to just "fix it". That's what anybody would do when they make themselves the approval bottleneck across multiple unrelated contexts.

When you start blindly approving tasks, you're inadvertently delegating the decision-making to the model. At that point, what are you there for?

You are the decision maker

Code is cheaper than it ever has been. As a developer, the amount of your value that comes from typing code is dwindling. And if that was the only thing you had to do as a dev, the answer to "will AI take our jobs" would be a whole heck of a lot scarier.

Our value (among other things) comes from decision making. Weighing the risks, evaluating tradeoffs, and a nose for what looks right, to name a few. Some decisions are bigger than others, and the important ones need your undivided attention.

I love AI, but it makes it way too easy to make bad decisions. And you often won't know about it until you're fighting a production issue when it's significantly more expensive to change. If an agent spits out a 1,000 word response after a long-running task, your task is to make an informed decision using the provided context, ask questions, and think two steps ahead.

If you glance, hit accept, tab, glance again, and hit accept again, then you aren't a decision maker, you're a rubber stamp with a keyboard.

Attention is your greatest resource

I don't want you reading this and your takeaway being "Allen says 40 agents is too many." That's not it at all. I'm not advocating for anything like that.

What I am advocating for is not spreading yourself too thin. People have been saying for years that attention is one of the scarcest and most important resources we have.

In 2026, everything wants your attention. Humans have gotten really good at creating things that steal your attention away from something else. With coding agents, it takes almost 0 effort to bring in another work stream so you can "force multiply yourself." Just open another terminal, type in claude and you're (basically) done.

Protect it. Treat your attention like the scarce resource it is. Keep the decision-heavy workstreams to a minimum, just 1 or 2. Then run as many low-judgment streams as you want next to them. But keep your attention on the tasks that need it. Don't split your attention across decisions, because when everything is a priority, nothing is.

Next time somebody asks you how many agents you have running, tell them that's the wrong thing to be counting. The better question is how many decisions you're actually making.

Happy coding!

Orchestrating workflows with Amazon S3 Files and AWS Lambda durable functions using Java SDK - Part 6 Invoke a Lambda function and parallel execution

Vadym Kazulkin — Mon, 21 Sep 2026 14:00:00 +0000

Introduction

In part 2 of the series, we explored how to use the AWS Lambda Durable Execution SDK for Java to create and execute durable steps synchronously and asynchronously. After that, in parts 3, 4, and 5 of the series, we explored how to use the AWS Lambda Durable Execution SDK for Java to implement wait for callback, wait for condition, and map operations.

Still, our Lambda durable function itself contains too much business logic. Ideally, it should simply be the orchestrator and contain as little business logic as possible. That's why, in this part, we'll move the logic associated with each step into a separate Lambda function. An additional advantage of this approach is that it allows us to apply individual settings to those functions, like setting the right memory and granting the exact permissions they need. We'll explore how to invoke another Lambda function within the durable step. Also, we'll show how to invoke multiple Lambda functions in parallel.

Sample application with invoking another Lambda function and performing parallel execution

Let's explore invoking another Lambda function and parallel execution. We get access to them through DurableContext.

invoke - the invoke operation calls another Lambda function and waits for its result. It supports both durable functions and standard on-demand Lambda functions. When you call ctx.invoke() or ctx.invokeAsync(), the SDK checkpoints the start of the operation, and the durable functions backend invokes the target Lambda function. On replay, the SDK returns the checkpointed result without invoking the target again.
parallel - parallel runs multiple independent branches concurrently, each in its own child context. Branches are registered via branch() and execute immediately (respecting maxConcurrency). The operation completes when all branches finish or completion criteria are met.

I first copied the application that we created in part 2 into the aws-s3-files-lambda-durable-functions-as-orchestrator-java-25 repository. We explain step by step how to adjust our application. Please go through the content of part 2 to understand the sample application and the basic concepts of Lambda durable functions. There will be some changes in the Infrastructure as Code (IaC) part as well. I'll leave out the wait for callbacks that we implemented in part 2. You can copy this logic into the Lambda durable function orchestrator, if you will.

We'll move the business logic for 3 individual steps out of our Lambda durable function AuthorContentExtractor to 3 different Lambda functions:

The implementation of all 3 Lambda functions is trivial. We'll focus on the change in the Lambda durable function AuthorContentExtractor and in the IaC located in the AWS SAM template.

We already showed in part 2 how to execute the first 2 Lambda functions asynchronously. This time, we'll show how to execute them in parallel. Here is how the complete code of the AuthorContentExtractor Lambda durable function looks:

public class AuthorContentExtractor extends DurableHandler<Author, AuthorContent> {

private static final String UPCOMING_TALKS_EXTRACTOR_FUNCTION_ARN  = 
System.getenv("UpcomingTalksExtractorFunctionArn");
private static final String YOUTUBE_VIDEOS_EXTRACTOR_FUNCTION_ARN  =
System.getenv("YouTubeVideosExtractorFunctionArn");
private static final String WRITE_AUTHOR_CONTENT_TO_FILE_FUNCTION_ARN  =
System.getenv("WriteAuthorContentToFileFunctionArn");


@Override
public AuthorContent handleRequest(Author author, DurableContext ctx) {
  var config = ParallelConfig.builder()
      .maxConcurrency(5)
      .nestingType(NestingType.NESTED)
      .completionConfig(CompletionConfig.allCompleted())
      .build();

  var invokeConfig=InvokeConfig.builder().build();

  var parallel = ctx.parallel("parallel-search", config);

  var upcomingTalksFuture = parallel.branch("searchForUpcomingTalks-parallel-step",
      UpcomingTalks.class, branchCtx -> {
           return branchCtx.invoke("searchForUpcomingTalks-step",           
             UPCOMING_TALKS_EXTRACTOR_FUNCTION_ARN, author,
             UpcomingTalks.class, invokeConfig);
     });

  var youtubeVideosFuture = parallel.branch("searchForYouTubeVideos-parallel-step",
      YouTubeVideos.class, branchCtx -> {
      return branchCtx.invoke("searchForYouTubeVideos-step",                
             YOUTUBE_VIDEOS_EXTRACTOR_FUNCTION_ARN, author, 
             YouTubeVideos.class, invokeConfig);
    });

  var result = parallel.get();
  var upcomingTalks=upcomingTalksFuture.get();
  var youtubeVideos= youtubeVideosFuture.get();

  var authorContent = new AuthorContent(author, upcomingTalks, youtubeVideos);

  ctx.invoke("writeAuthorContentToFile-step", WRITE_AUTHOR_CONTENT_TO_FILE_FUNCTION_ARN, 
    authorContent, Void.class, invokeConfig);

  return authorContent;
  }
}

Let's go step by step through the code. First, we pass the ARNs of all 3 Lambda functions via environment variables. We set those for the Lambda durable function AuthorContentExtractorFunction in the AWS SAM template. Also, we give our Lambda durable function the required permissions to invoke the other 3 Lambda functions:

  AuthorContentExtractorFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: AuthorContentExtractorOrchestrator
      Handler: dev.vkazulkin.handler.AuthorContentExtractor::handleRequest
      Environment:
        Variables:
          UpcomingTalksExtractorFunctionArn: !GetAtt UpcomingTalksExtractorFunction.Arn
          YouTubeVideosExtractorFunctionArn: !GetAtt YouTubeVideosExtractorFunction.Arn
          WriteAuthorContentToFileFunctionArn: !GetAtt WriteAuthorContentToFileFunction.Arn
      DurableConfig:
        ExecutionTimeout: 3600
        RetentionPeriodInDays: 7
      Policies:
        - Version: '2012-10-17'
          Statement:
            - Sid: InvokeLambda
              Effect: Allow
              Action: lambda:InvokeFunction
              Resource:
                  - !GetAtt YouTubeVideosExtractorFunction.Arn
                  - !Sub '${YouTubeVideosExtractorFunction.Arn}:*'
                  - !GetAtt UpcomingTalksExtractorFunction.Arn
                  - !Sub '${UpcomingTalksExtractorFunction.Arn}:*'
                  - !GetAtt WriteAuthorContentToFileFunction.Arn
                  - !Sub '${WriteAuthorContentToFileFunction.Arn}:*'
....

As we invoke UpcomingTalksExtractor and YouTubeVideosExtractor Lambda functions in parallel, we create ParallelConfig. Here we set the maximum concurrency value and nesting type. There are 2 nesting types:

Nested (the default one). Create CONTEXT operations for each branch/iteration with full checkpointing. Operations within each branch/iteration are wrapped in their own context. Observability: High - each branch/iteration appears as a separate operation in execution history. Cost: Higher - consumes more operations due to CONTEXT creation overhead. Scale: Lower maximum iterations due to operation limits
Flat. Skip CONTEXT operations for branches/iterations using virtual contexts. Operations execute directly without individual context wrapping. Observability: Lower - branches/iterations don't appear as separate operations. Cost: ~30% lower - reduces operation consumption by skipping CONTEXT overhead. Scale: Higher maximum iterations possible within operation limits

We also set the CompletionConfig. Here, there are many possibilities from which we can choose:

allCompleted (we use it). All items run regardless of failures. Failures are captured per-item.
allSuccessful. All items must succeed. Zero failures tolerated.
firstSuccessful. Complete as soon as the first item succeeds.
minSuccessful. Complete when the specified number of items have succeeded.
toleratedFailureCount. Complete when more than the specified number of failures have occurred.
toleratedFailurePercentage. Complete when the failure percentage exceeds the specified threshold (0.0 to 1.0).

Next, we create an InvocationConfig for each individual Lambda function invocation that we can optionally set. Here we go with the default configuration. But we additionally set the tenant ID, which is used to isolate execution state for different tenants. It's required when invoking multi-tenant Lambda functions. So far, we covered the following parts:

 var config = ParallelConfig.builder()
      .maxConcurrency(5)
      .nestingType(NestingType.NESTED)
      .completionConfig(CompletionConfig.allCompleted())
      .build();

  var invokeConfig=InvokeConfig.builder().build();

Next, let's implement the Lambda function invocation in parallel:

  var parallel = ctx.parallel("parallel-search", config);

  var upcomingTalksFuture = parallel.branch("searchForUpcomingTalks-parallel-step",
      UpcomingTalks.class, branchCtx -> {
           return branchCtx.invoke("searchForUpcomingTalks-step",           
             UPCOMING_TALKS_EXTRACTOR_FUNCTION_ARN, author,
             UpcomingTalks.class, invokeConfig);
     });

  var youtubeVideosFuture = parallel.branch("searchForYouTubeVideos-parallel-step",
      YouTubeVideos.class, branchCtx -> {
      return branchCtx.invoke("searchForYouTubeVideos-step",                
             YOUTUBE_VIDEOS_EXTRACTOR_FUNCTION_ARN, author, 
             YouTubeVideos.class, invokeConfig);
    });

  var result = parallel.get();
  var upcomingTalks=upcomingTalksFuture.get();
  var youtubeVideos= youtubeVideosFuture.get();

  var authorContent = new AuthorContent(author, upcomingTalks, youtubeVideos);

First, we invoke the parallel method on the DurableContext and pass the ParallelConfig. We get back the ParallelDurableFuture, with which we can start a branch. To do this, we invoke the branch method for each individual Lambda invocation and specify the result type. In each branch, we call the invoke method on the BranchContext. Here we pass the following parameters:

name - the unique operation name within this context.
functionName - the ARN or name of the Lambda function to invoke.
payload - the input payload to send to the target function.
resultType - the result class for deserialization.

We get back the DurableFuture of the resultType (in our case UpcomingTalks or YouTubeVideos).

When we invoke the blocking get method on the ParallelDurableFuture to get the results with respect to the ParallelConfig. Then, we invoke the get method on DurableFuture to get the individual results of both Lambda invocations. Finally, we create the _ AuthorContent _ with these results.

The last step is to invoke the Lambda function, which is responsible for writing the author content into the file:

 ctx.invoke("writeAuthorContentToFile-step", WRITE_AUTHOR_CONTENT_TO_FILE_FUNCTION_ARN, 
    authorContent, Void.class, invokeConfig);

As we explained in part 2, we use S3 Files here. The whole part on how to configure S3 Files and give the Lambda function access to it has now moved from the AuthorContentExtractorOrchestrator durable Lambda function to the WriteAuthorContentToFileFunction Lambda function. See the SAM template for more detail.

To test our Lambda durable function, we can navigate to the Lambda service, search for the AuthorContentExtractorOrchestrator function, and go to the "Test" tab.

We need to pass the following sample JSON Event to it, which represents the author:

{
  "firstName": "Vadym",
  "lastName": "Kazulkin"
}

Then we can test it. After that, we go to the "Durable execution" tab and can see all the execution details:

Let's also look at event history:

We see that this matches what we implemented. Our Lambda durable function invokes in parallel 2 Lambda functions to search for YouTube videos and upcoming talks (each in an individual branch). Then, it awaits the results of both invocations because we defined in the parallel configuration that we wait until all invocations are completed. Then the last Lambda function to write the author content into the file gets invoked.

One general question at the end: is the Lambda function invocation from another Lambda function considered an anti-pattern? Or should we put an API Gateway in between instead? My answer is that with built-in fault-tolerance for AWS Lambda durable functions, it's now safe to invoke a Lambda function directly.

Conclusion

In this part of the series, we moved the logic associated with each step into a separate Lambda function. We explored how to invoke another Lambda function within the durable step. Also, we showed how to invoke multiple Lambda functions in parallel.

In the next part of the series, we'll transform our application into an agentic one. Currently, the search for YouTube and upcoming talks returns static content. We'll replace it with the Amazon Bedrock AgentCore Gateway Web Search Tool. As it's exposed via MCP, we need an MCP client to connect to it. For that, we'll use the Spring AI framework. First, we still use AWS Lambda to host the AI agents. In later parts, we'll show how to host those AI agents on the Amazon Bedrock AgentCore Runtime instead.

If you like my content, please follow me on GitHub and give my repositories a star!

Please also check out my website for more technical content and upcoming public speaking activities.

Orchestrating workflows with Amazon S3 Files and AWS Lambda durable functions using Java SDK - Part 5 Map and child context

Vadym Kazulkin — Mon, 14 Sep 2026 14:30:00 +0000

Introduction

In part 2 of the series, we explored how to use the AWS Lambda Durable Execution SDK for Java to create and execute durable steps synchronously and asynchronously. Later, in parts 3 and 4 of the series, we explored how to use the AWS Lambda Durable Execution SDK for Java to implement wait for callback and wait for condition.

In this part, we'll explore map and child context operations.

Sample application with map and child context

Let's explore the child context operation first. Child contexts run an isolated stream of work with their own operation counter and checkpoint log. They support the full range of durable operations — step, wait, invoke, createCallback, and nested child contexts. In our sample application, we'll add a map operation, which uses a child context underneath. We get access to it through DurableContext. A Map operation applies a function to each item in a collection concurrently, with each item running in its own child context.

Now let's add an artificial use case: for each YouTube video found, we add it to the author's YouTube playlist. I first copied the application that we created in part 2 into the aws-s3-files-lambda-durable-functions-with-map-and-child-context-java-25 repository.

The main business logic we have to add is in the saveYouTubeVideosToPlayList method of the AbstractAuthorContentExtractor:

public default void saveYouTubeVideosToPlayList (DurableContext ctx, Author author, YouTubeVideos youtubeVideos)  {
   var youtubePlayList = findOrCreateYouTubePlayListForTheAuthor(author);

   var mapConfig = MapConfig.builder()
       .nestingType(NestingType.NESTED)
       .maxConcurrency(5)                                   
       .completionConfig(CompletionConfig.allCompleted())    
       .build();

   var mapResult = ctx.map("saveYouTubeVideoToPlayList-step", youtubeVideos.youtubeVideos(), 
      Boolean.class, (youtubeVideo, index, childCtx) -> {       
        return childCtx.step("saveYouTubeVideoToPlayList-step-"+index, Boolean.class, 
       stepCtx -> saveYouTubeVideoToPlayList(youtubeVideo, youtubePlayList)
      , this.getStepConfig());
    }, mapConfig);

}


private static int findOrCreateYouTubePlayListForTheAuthor(Author author) {
     // Use YouTube API to log in to the YouTube Account and search for the author's playlist
     // and return it if it already exists or create a new one
     // move this logic into a separate Lambda function and invoke it as a durable step
     return 1;
}

private static Boolean saveYouTubeVideoToPlayList(YouTubeVideo youtubeVideo, int playListId) {
    //Use YouTube API to save the video URL to the playlist. 
    return true;
}

We invoke this saveYouTubeVideosToPlayList method in the AuthorContentExtractor or AsyncAuthorContentExtractor classes.

First of all, I won't use the YouTube API to create or retrieve the YouTube playlist for the given author and store each found video there. I use some static output, as the goal of this article is to demonstrate the functionality of the map operation.

Let's go step by step through this code. Map applies a function to each item in a collection concurrently, with each item running in its own child context. Results are collected into a MapResult that maintains input order. Each item's function receives its own DurableContext, so you can use any durable operation (step(), wait(), invoke(), etc.) inside the map function. The function passed to map() is a MapFunction:

@FunctionalInterface
public interface MapFunction<I, O> {
    O apply(I item, int index, DurableContext context);
}

The index parameter is the zero-based position of the item in the input collection, useful for naming operations or correlating results. For each found YouTube video, we invoke the saveYouTubeVideoToPlayList method, which returns the result of type Boolean. In our case, it is always true, indicating that the video was stored in the playlist.

The input collection must have deterministic iteration order. List, LinkedList, and TreeSet are accepted. HashSet and unordered map views are not, leading to the IllegalArgumentException. That's why I changed the implementation of the YouTubeVideos class to use List instead of Set there.

Next, let's explore MapConfig in more detail. There are several main settings there:

maxConcurrency controls how many items execute concurrently. When set, items beyond the limit are queued and started as earlier items complete. The default is null (unlimited).

nestingType, with Nested as the default.

Nested. Create CONTEXT operations for each branch/iteration with full checkpointing. Operations within each branch/iteration are wrapped in their own context. Observability: High - each branch/iteration appears as a separate operation in execution history. Cost: Higher - consumes more operations due to CONTEXT creation overhead. Scale: Lower maximum iterations due to operation limits
Flat. Skip CONTEXT operations for branches/iterations using virtual contexts. Operations execute directly without individual context wrapping. Observability: Lower - branches/iterations don't appear as separate operations. Cost: ~30% lower - reduces operation consumption by skipping CONTEXT overhead. Scale: Higher maximum iterations possible within operation limits

CompletionConfig controls when the map operation stops starting new items. Here, there are many possibilities from which we can choose:

allCompleted (we use it). All items run regardless of failures. Failures are captured per-item.
allSuccessful. All items must succeed. Zero failures tolerated.
firstSuccessful. Complete as soon as the first item succeeds.
minSuccessful. Complete when the specified number of items have succeeded.
toleratedFailureCount. Complete when more than the specified number of failures have occurred.
toleratedFailurePercentage. Complete when the failure percentage exceeds the specified threshold (0.0 to 1.0).

When early termination is triggered, items that were never started have SKIPPED status with null for both result and error in the MapResult.

Each MapResultItem contains the following methods:

status: SUCCEEDED, FAILED, or SKIPPED.
result: the result value, or null if failed/skipped.
error: the error details as MapError, or null if succeeded/skipped.

Failed items store error details as MapError, a serializable record that survives checkpoint-and-replay cycles with the following methods that can be invoked:

errorType: Fully qualified exception class name (e.g., java.lang.RuntimeException).
errorMessage: The exception message.
stackTrace: Stack trace frames as a list of strings, or null.

One item's failure does not prevent other items from completing. MapResult captures the failed items at their corresponding index.

Map operations are fully durable. On replay after interruption:

Completed items return cached results without re-execution.
Incomplete items resume from their last checkpoint.
Items that never started execute fresh.

Small results (< 256KB) are checkpointed directly, whereas large results are reconstructed from individual child context checkpoints on replay.

That's it. There are no changes in the Infrastructure as Code part that we need to make. Now we can build and package our application with mvn clean package and deploy it with sam deploy. The deployment process can take up to 10 minutes because of the creation and mounting of S3 Files.

To test our Lambda durable function, we can navigate to the Lambda service, search for the AuthorContentExtractor or AsyncAuthorContentExtractor function, and go to the "Test" tab.

We need to pass the following sample JSON Event to it, which represents the author:

{
  "firstName": "Vadym",
  "lastName": "Kazulkin"
}

Then we can test it. After that, we go to the "Durable execution" tab and can see all the execution details:

Here we see that the operation with the name saveYouTubeVideoToPlayList-step and the subtype Map. We also see 2 iterations (for each of the 2 YouTube videos found) with the subtype MapIteration. Each iteration is executed as an individual durable step.

Let's also look at event history:

Here we see all events (durable operations) in the right order required for the execution of our Lambda durable function.

There is also the mapAsync operation. It starts the map operation without blocking, returning a DurableFuture.

Conclusion

In this part of the series, we explored how to use the AWS Lambda Durable Execution SDK for Java to implement map and child context operations.

Still, our Lambda durable function itself contains too much business logic. Ideally, it should simply be the orchestrator and contain as little business logic as possible. That's why, in the next part, we'll move the logic for each step into a separate Lambda function. With that, we'll explore how to invoke another Lambda function within the durable step. We'll also show how to invoke multiple Lambda functions in parallel.

If you like my content, please follow me on GitHub and give my repositories a star!

Please also check out my website for more technical content and upcoming public speaking activities.

DEV Community: AWS Heroes

Give your agent an agenda

A different agent experience

Giving the agent a future

Let the agent change its mind

Can you actually play fantasy football with AI agents?

A forward look for agents

Serverless applications on AWS with Lambda using Java 25, API Gateway and DynamoDB - Part 8 Using Container Image

Introduction

Sample application using a Container Image

Measurements of cold and warm start times of our application using a Container Image

Conclusion

Deliberation Dashboard: see and analyze your consensus results

You cannot fix a panel you cannot see

The analyzer tells me which model to drop

Every run remembers the config it ran with

Slow is fine, unbounded is not

Models argue about today, not their training cutoff

Smaller things that removed friction

What I would still not trust it with

Try it

4 Ways to Safely Refactor AWS CDK Code Without Resource Replacement

Construct Tree and Path

Code Before Refactoring

Code After Refactoring

Logical ID Changes and Resource Replacement

Four Ways to Refactor Safely

1. The cdk refactor Command

1-1. How to Use cdk refactor

1-2. Cases Where cdk refactor Cannot Be Used

2. The cdk orphan + cdk import Commands

2-1. Running cdk orphan

2-2. Running cdk import

2-3. Final cdk deploy and Points to Note

3. Setting the Construct ID to Default

3-1. L1 Constructs and Paths

3-2. Keeping the Logical ID with Default

3-3. Conditions for Applying This Method

4. Overriding the Logical ID

4-1. Pinning with overrideLogicalId

4-2. Pinning with renameLogicalId

4-3. Downside: The Pinning Code Remains

How to Choose Among the Methods

Appendix 1. Accepting Replacement of Stateless Resources

Appendix 2. Leaving Physical Names Unspecified

Conclusion

Orchestrating workflows with Amazon S3 Files and AWS Lambda durable functions using Java SDK - Part 8 AI Agents with Spring AI on AgentCore Runtime

Introduction

Sample application using AgentCore Gateway Web Search Tool and Spring AI hosted on Amazon Bedrock AgentCore Runtime

Building, packaging, deploying, and testing our sample application

Conclusion

Agent memory needs more than vector search

Filter first, then rank

Setting the baseline

The enlightening reranker results

Where rerankers make sense

My new approach

Try it yourself

Orchestrating workflows with Amazon S3 Files and AWS Lambda durable functions using Java SDK - Part 7 AI Agents with Spring AI and AgentCore on AWS Lambda

Introduction

Introduction to Spring AI framework

How to convert AWS Lambda to a Spring (Boot) Application

Sample application using AgentCore Gateway Web Search Tool and Spring AI hosted on AWS Lambda

Introduction to the Amazon Bedrock AgentCore Gateway Web Search Tool

How to set up the Amazon Bedrock AgentCore Gateway Web Search Tool

How to implement the Amazon Bedrock AgentCore Gateway Web Search Tool using Spring AI

IaC for the sample application using AgentCore Gateway Web Search Tool and Spring AI hosted on AWS Lambda

Building, packaging, deploying, and testing our sample application

Conclusion

Monthly Amazon Location Service Updates - 2026.08

Monthly Amazon Location Service Updates - 2026.08

2026.08 Updates

Other Info

Related Articles

Monthly Amazon Location Service Updates - 2026.07

Which Part Was Me?

You're still the bottleneck

You can't multitask like you think you can

You are the decision maker

Attention is your greatest resource