• 

• 

• 

• 

• 

• 

• 

• 

• 

🚚 RoutePatch

When the route breaks, the food still arrives.

RoutePatch is an agentic operations system that helps community logistics teams recover when real-world disruptions break an active route plan.

A vehicle becomes unavailable.
A driver cannot continue.
An urgent pickup appears.
A stop gets cancelled.
A delivery window changes.

Instead of rebuilding the entire day manually, RoutePatch repairs only the part of the operation that can still change.

Completed work stays locked. Future work can move. And when RoutePatch is missing a real-world fact, it does not guess — it asks the human exactly when a real decision is needed.

🚀 TRY THE LIVE PRODUCT
🎥 WATCH THE DEMO VIDEO
💻 VIEW THE SOURCE CODE

---

Synthetic operational data · Public geography · Live AWS infrastructure

---

🌍 Inspiration

A route plan can look perfect at 8:00 AM.

Then reality happens.

For community organizations such as food banks, nonprofits, local distribution teams, and other small logistics operations, the difficult part is often not creating the original route.

The difficult part is recovering when that plan breaks in the middle of the day.

A vehicle becomes unavailable after several stops are already completed. A new pickup suddenly becomes urgent. A receiving location changes its time window. A stop gets cancelled.

At that point, the coordinator has to answer a much harder question:

How do I repair the rest of the day without undoing what has already happened?

Many small organizations handle these changes manually using maps, spreadsheets, phone calls, and messaging apps.

We built RoutePatch around that exact moment.

Not another route planner.

Not a chatbot that suggests what someone might do.

But an agent that coordinates the recovery workflow, repairs the unfinished operation, validates the new plan, and only interrupts a person when a real-world fact is missing.

---

⚡ What RoutePatch does

RoutePatch continuously treats the active operation as the source of truth.

When something changes, it can handle four operational disruption types:

• 🚐 Resource unavailable — a driver or vehicle can no longer continue.
• 📦 Urgent pickup inserted — new work appears during the operating day.
• ❌ Stop cancelled — an unfinished stop is removed.
• ⏱️ Time window changed — a stop must now happen within a different window.

The result is not simply another generated route.

RoutePatch creates a minimal safe repair of the remaining operation.

---

🧠 The core idea: only unfinished work can move

One of the most important product decisions in RoutePatch is the separation between:

Route Plan
What should happen.

and

Execution State
What has already happened.

An operator can start a route and complete stops as the day progresses.

Once a stop is completed, RoutePatch marks that work as LOCKED.

If a disruption happens later, the agent can repair future work — but it cannot rewrite operational history.

This makes the repair much closer to how a real logistics operation behaves:

Keep what already happened. Repair only what is still possible to change.

---

🛠️ How the repair works

The RoutePatch workflow can be summarized in five steps:

1. Disruption

An operational event occurs.

2. Attestation

RoutePatch establishes whether the event came from an authoritative structured source or requires human confirmation.

3. Repair

Amazon Location provides real road-routing information and OR-Tools searches for the minimal feasible reassignment of unfinished work.

4. Independent validation

A separate deterministic validator checks every hard constraint.

5. Version-safe commit

Only a validated candidate can become the new active plan, using a transactional compare-and-swap commit in DynamoDB.

The map then transitions from the previous plan to the repaired plan.

---

🤝 Human only when a human is actually needed

The theme of Agents for Humans strongly influenced our architecture.

RoutePatch should not constantly ask the operator questions.

If an event arrives from trusted structured data, RoutePatch can repair the operation autonomously.

But consider this message:

"One of our vans broke down."

Which van?

A language model could guess.

RoutePatch refuses to.

Instead, Strands issues a genuine human-in-the-loop interrupt, exposes only authoritative vehicle options, and pauses the workflow.

The operator supplies the missing fact.

Then the same workflow resumes from the point where it stopped.

This gives us the behavior we wanted from the beginning:

The agent runs quietly until reality requires a human decision.

---

🛡️ The agent is not the authority

This became one of the most important lessons of the entire project.

Our first experiments gave the language model broader operational authority.

We evaluated those designs instead of assuming they were safe.

The results exposed semantic ambiguity and prompt-injection failure modes.

So we changed the architecture.

Today, RoutePatch follows a strict principle:

Probabilistic coordination. Deterministic operational truth.

The model does not:

• calculate route feasibility;
• determine capacity constraints;
• override completed work;
• bypass hard time windows;
• declare a candidate valid;
• decide that a commit succeeded;
• turn an untrusted statement directly into operational truth.

Instead:

Strands coordinates.
Attestations establish facts.
Amazon Location provides road truth.
OR-Tools performs deterministic repair.
An independent validator proves hard-constraint compliance.
DynamoDB performs the version-safe transactional commit.

A model response by itself can never change the authoritative operational plan.

---

🏗️ Architecture

RoutePatch deliberately separates the agentic layer from the authoritative decision layer.

Agentic / probabilistic coordination

• Strands Agents SDK
• Amazon Bedrock AgentCore Runtime
• Amazon Nova Pro
• Human-in-the-loop interrupt / resume

Deterministic / authoritative core

• Amazon Location Routes V2
• OR-Tools
• Independent constraint validator
• Immutable plan versions
• DynamoDB transactional compare-and-swap
• Durable idempotency records

Product layer

• React
• TypeScript
• MapLibre GL JS
• Amazon Location Maps V2
• FastAPI
• AWS Lambda
• Amazon API Gateway
• AWS Amplify Hosting

---

🗺️ A real operational interface

We did not want RoutePatch to feel like an agent hidden behind a chat box.

The map is the product.

Operators can see:

• active routes;
• completed vs. unfinished work;
• route direction;
• resource availability;
• affected stops;
• previous vs. repaired geometry;
• execution progress;
• incidents;
• Route Health;
• validation state.

Route geometry follows real roads through Amazon Location Routes V2, while Amazon Location Maps V2 and MapLibre render the visual experience.

There is no fake GPS telemetry.

Execution state is operator-managed and clearly represented as such.

---

💚 Route Health

RoutePatch also provides deterministic operational awareness through Route Health.

Possible route states include:

• HEALTHY
• AT_RISK
• INTERRUPTED
• COMPLETED
• UNKNOWN

The system can surface information such as:

• completed vs. remaining stops;
• next stop;
• remaining planned travel;
• resource availability;
• known capacity utilization;
• minimum remaining time-window slack.

This is not a predictive AI risk score.

It is derived from known operational state and explicit deterministic rules.

---

☁️ Built on AWS

RoutePatch uses AWS across the complete working product:

Layer	Technology
Agent orchestration	Strands Agents SDK
Agent runtime	Amazon Bedrock AgentCore Runtime
Foundation model	Amazon Nova Pro via Bedrock
Real road routing	Amazon Location Routes V2
Map rendering	Amazon Location Maps V2
Durable state	Amazon DynamoDB
Product API	FastAPI + AWS Lambda
Public API	Amazon API Gateway
Frontend hosting	AWS Amplify Hosting
Optimization	Google OR-Tools
Web experience	React + TypeScript + MapLibre GL JS

AgentCore was not added simply for a badge.

We deployed the real Strands workflow into AgentCore and proved real cloud interrupt → resume behavior using the same workflow session.

---

🔄 An asynchronous product, not a blocking AI request

Agent workflows can take several seconds.

We did not want the browser to freeze while the agent worked.

RoutePatch therefore uses an asynchronous architecture:

Operator reports disruption
        ↓
API returns 202 quickly
        ↓
Workflow enters QUEUED / PROCESSING
        ↓
Async worker invokes AgentCore
        ↓
Repair + validation
        ↓
Durable state changes
        ↓
Frontend observes authoritative result
        ↓
Map animates old plan → repaired plan

The user gets immediate feedback while the real AWS workflow continues in the background.

---

🔐 Durable state and safe commits

RoutePatch stores operational truth in DynamoDB.

A repair commit atomically binds:

• event attestation;
• candidate digest;
• VALID validation result;
• expected active plan version;
• immutable new plan;
• workflow disposition;
• idempotency truth.

If another process changes the active plan before the repair commits:

RoutePatch rejects the stale commit.

No silent retry.

No accidental second mutation.

No generated text decides that the operation succeeded.

---

📊 Engineering evidence

We treated evaluation as part of the product, not something added at the end.

Deterministic core

20 / 20
Scenario contracts passed.

Human-in-the-loop architecture

16 / 16
Approved HITL workflow benchmark cases passed.

Safety

0 unsafe commits
0 unattested commits
0 commits after VERSION_CONFLICT
0 validation-binding violations
0 completed stops moved during execution-aware repair testing

Final engineering suites

115 passed, 1 skipped — backend tests
19 passed — frontend tests
Live browser E2E passed — deployed AWS product

These are synthetic engineering evaluations, not real-world food-bank outcome statistics.

---

🧗 Challenges we faced

1. How much authority should the agent have?

This was the hardest architectural question.

Our initial Strands architecture exposed a broader operational tool surface.

It worked often — but "often" was not enough.

Our evaluations found cases where semantic interpretation could become unsafe, including an adversarial case that could turn a false premise into an operational mutation.

Instead of solving that with a larger prompt, we redesigned the authority boundary.

That led to:

• non-authoritative event proposals;
• attested events;
• genuine Strands interrupts;
• deterministic repair;
• independent validation;
• version-safe commit.

That failure became one of the most valuable engineering discoveries in the project.

---

2. Making HITL genuine

We did not want a fake "Are you sure?" prompt.

We implemented real Strands interrupt/resume behavior and then proved that the same pattern worked inside Amazon Bedrock AgentCore Runtime.

That allowed RoutePatch to stop at the exact point where a human fact was missing and resume the same workflow afterward.

---

3. Moving from a technical proof to a real product

A routing algorithm alone would not satisfy the problem.

We added:

• durable operational state;
• asynchronous workflows;
• a public API;
• live route execution;
• Incident Center;
• Route Health;
• real road geometry;
• Before / After transitions;
• interactive map experience.

The result became an operational application instead of an optimization notebook.

---

4. Preserving reality after the day has started

Route planning is comparatively easy when nothing has happened yet.

The harder problem was:

What happens when part of the route has already happened?

We introduced a separate durable ExecutionState.

That allowed completed work to become immutable while the remaining work stayed repairable.

This is now one of RoutePatch's most important behaviors.

---

🏆 Accomplishments we're proud of

We are especially proud that RoutePatch became a complete working AWS-hosted system rather than a mocked demo.

It includes:

• a public interactive product;
• genuine Strands agent behavior;
• Amazon Bedrock AgentCore deployment;
• real Amazon Location road routing;
• deterministic OR-Tools repair;
• independent validation;
• DynamoDB transactional state;
• durable HITL metadata;
• asynchronous FastAPI architecture;
• live execution state;
• four operational incident types;
• execution-aware repair;
• Route Health;
• a map-first UI.

Most importantly, the final architecture is stronger because we measured where the agent should not have authority.

---

📚 What we learned

The biggest lesson was that autonomy does not require giving an LLM authority over everything.

In operational systems, a stronger architecture can emerge when different components own different kinds of truth.

We learned to separate:

language understanding from operational facts;

coordination from optimization;

candidate generation from validation;

human judgment from mathematical feasibility;

and AI reasoning from authoritative state mutation.

That separation made RoutePatch both more autonomous and more trustworthy.

---

🔮 What's next

RoutePatch currently uses synthetic operational scenarios and public geography, but the architecture is designed around a real operational workflow.

Future work could include:

• integration with real nonprofit dispatch systems;
• authenticated organizations and operators;
• driver-facing acknowledgements;
• notifications;
• telematics integrations where available;
• richer operational history;
• multi-depot workflows;
• field validation with real community logistics teams.

We would keep the same core principle:

Let the agent coordinate complexity without allowing probabilistic reasoning to silently rewrite operational truth.

---

🚀 Try RoutePatch

Live product

👉 https://judge.d1hjlmux26gpdn.amplifyapp.com

No login required.

Quick path

1. Open RoutePatch.
2. Inspect the current operation.
3. Click Report disruption.
4. Select Resource unavailable.
5. Choose Vehicle 02.
6. Watch RoutePatch repair the unfinished operation.
7. Compare Before / After.
8. Explore Route Health, Incident Center, and the human-decision workflow.

---

🎥 Demo Video

👉 Watch RoutePatch on YouTube

---

💻 Source Code

👉 github.com/jpablortiz96/routepatch

The repository contains the application source, frontend, deployment infrastructure, tests, architecture documentation, evidence, and setup instructions.

---

🏘️ Good Neighbor Agents

RoutePatch was built for the Good Neighbor Agents track.

The project focuses on groups that often operate with limited coordination resources but highly dynamic real-world constraints: food banks, nonprofits, community distribution teams, and local organizations.

The goal is simple:

Give small community logistics teams the ability to recover from disruption without having to rebuild the day from scratch.

---

✍️ AWS Builder Posts

I published three public AWS Builder Center articles documenting the RoutePatch journey, safety architecture, and AWS implementation.

1. Build Journey

Agents for Humans: RoutePatch — When the Route Breaks, the Food Still Arrives

How RoutePatch evolved from a route-repair idea into a complete AWS-hosted operational agent for community logistics.

2. Bounded Autonomy & Safety

Agents for Humans: Why RoutePatch Lets an Agent Ask — but Never Decide What Is True

A deep dive into attestation, prompt-injection testing, genuine Strands HITL, and why operational truth remains outside the language model.

3. AWS Architecture

Agents for Humans: Building a Durable Route Repair Agent with Strands, AgentCore, and Amazon Location

A technical walkthrough of RoutePatch using Strands Agents SDK, Amazon Bedrock AgentCore, Amazon Location, DynamoDB, Lambda, API Gateway, and deterministic route optimization.

❤️ Final thought

Community logistics does not stop because the original plan became invalid.

People are still waiting.

Pickups still matter.

Deliveries still need to happen.

RoutePatch is built for that moment.

When the route breaks, the food still arrives.

Built With

• agentcore
• agents
• amplify
• bedrock
• boto3
• cdk
• cloudwatch
• dynamodb
• gateway
• google
• human-in-the-loop
• lambda
• location
• maplibre
• nova
• or-tools
• pro
• pydantic
• python
• react
• sdk
• service
• strands
• typescript
• vite