Production workflows / Guide 05
A Delivery Exception Agent That Separates Late Data From Lost Parcels
Design a logistics delivery exception agent that reconciles carrier events, protects shipment data, and proposes recoverable actions without guessing delivery.
Illustrative engineering guide. Examples are not client deployments, production-ready integrations, or evidence of measured results. Validate the design with your domain and security owners.
Imagine a hypothetical distributor shipping replacement machine parts to a repair site. The carrier feed reports “delivery attempted,” while a depot scan arriving later shows the parcel still in transit. The customer’s technician is waiting, and an operator wants to dispatch a second shipment. A logistics delivery exception agent must decide what evidence is current before recommending an expensive recovery.
The central distinction is between a late parcel and late information about a parcel. A missing scan is not proof of loss. A recently received event is not necessarily the newest physical event. Building around those distinctions is more valuable than generating increasingly empathetic delay messages.
Keep Two Clocks and the Original Meaning
Every event needs the carrier’s occurrence time and your ingestion time. Preserve the raw carrier status, normalized business status, source event identifier, location confidence, and shipment association. A normalization rule should be versioned because changing the meaning of “exception” can alter thousands of open cases.
GS1 EPCIS describes interoperable event information about what, when, where, why, and how, including chain of custody and sensor data. It is a useful modeling reference even when a carrier exposes a proprietary API. Do not claim EPCIS compliance merely because your internal JSON contains timestamps and locations.
Avoid one universal numeric ranking of shipment states. A return-to-sender event can validly follow an attempted delivery, and a carrier correction can supersede a mistaken delivered scan. Keep the event history and build a carrier-specific projection with explicit correction semantics. Conflicts should remain visible until a trusted source resolves them.
Compute Exceptions, Then Explain Them
Use carrier adapters, a normalized event store, a deterministic exception evaluator, and a recovery queue. The evaluator considers promised service window, last verified movement, lane-specific thresholds, customer commitments, and goods restrictions. The LLM summarizes the evidence and drafts the next communication. It does not calculate an ETA from prose or declare loss from silence.
This illustrative JSON event contract is an internal example, not the EPCIS schema or a carrier API. Production code must validate identifiers, authenticate carrier messages, handle corrections, and maintain time-zone-aware timestamps.
{
"shipment_ref": "shipment_demo_28",
"carrier_event_id": "event_demo_91",
"occurred_at": "2026-09-07T08:40:00Z",
"received_at": "2026-09-07T10:10:00Z",
"raw_status": "DEPOT_SCAN",
"normalized_status": "in_transit",
"mapping_version": "carrier_a_v3",
"supersedes_event_id": null,
"source": "authenticated_carrier_feed"
}For the repair-site example, the first action might be a carrier trace request and a customer callback deadline, not immediate reshipment. If inventory is scarce, reserving a replacement temporarily can protect options without shipping twice. That reservation needs an expiry and an owner so abandoned cases do not consume warehouse stock indefinitely.
Specialist sub-agents are useful only when the recovery genuinely branches into independently owned reasoning, such as interpreting a complex international shipping document. Keep routing optimization and carrier queries as tools. A second agent repeating the same incomplete tracking feed cannot establish physical custody.
Make Recovery a Bounded Business Operation
Represent a redelivery request, address correction, hold-at-depot request, and reshipment as different commands. Each command has eligibility rules, approval requirements, a business identifier, and an observable completion condition. “Fix the shipment” is too broad a tool permission.
Address changes deserve stronger verification because they can redirect valuable goods. Require server-side authorization tied to the shipment owner or an approved operator, validate carrier restrictions, and obtain explicit confirmation of the new destination. Do not trust a new address extracted from an email signature. Keep tenant scope in credentials and database predicates rather than allowing the model to choose it.
Carrier notes, proof-of-delivery text, and customer attachments are untrusted content. They cannot authorize a refund, download other shipments, or redirect the workflow to an external endpoint. OWASP authorization guidance supports per-resource permission checks. MCP is only an integration protocol; it does not grant shipment access.
Some carrier APIs do not offer reliable idempotent writes. Record the intended operation locally before submission, store the carrier reference when available, and reconcile unknown outcomes before retrying. RFC 9110 is the foundation for HTTP semantics, not a guarantee that an arbitrary redelivery POST is safe to repeat.
Recover From Partial and Contradictory Evidence
If the tracking feed is unavailable, show its last successful observation and apply a freshness ceiling. Do not present a cached “out for delivery” state as a live driver location. Schedule a bounded refresh and escalation deadline rather than letting the model poll indefinitely.
If reshipment succeeds but cancellation of the original fails, both physical shipments may arrive. Keep that possibility in the case, notify the operator, and follow an approved recovery policy. Never issue a refund simply to make the case appear closed. For temperature-sensitive goods, a sensor excursion should route to the designated quality owner; the assistant must not declare the goods safe based on a general temperature threshold.
Retain proof-of-delivery evidence under restricted access. A signature image or delivery photograph can reveal people and addresses. Operational telemetry should count event delays and status conflicts using opaque references, not copy photographs or personal details into broad dashboards.
Acceptance Tests for Physical Operations
- Receive a depot scan after a newer attempted-delivery event, with an older occurrence time. The projection preserves chronology and does not regress solely by ingestion order.
- Deliver the same carrier event repeatedly. One event identity is stored and no duplicate trace, notification, or reshipment is created.
- Send an address-change request from another merchant tenant. The operation is denied before carrier data is revealed or modified.
- Lose the response to a redelivery request. The coordinator searches for the existing carrier operation and escalates ambiguity rather than repeating it blindly.
- Provide conflicting delivered and correction events. The agent reports the conflict, retains both sources, and routes to an operator instead of choosing the more reassuring status.
Measure Recovered Commitments
Baseline exception handling by carrier, lane, service class, and exception reason. Measure eligible exceptions resolved within the agreed recovery window divided by all eligible exceptions. Resolution should require verified delivery or an approved alternative outcome, not a sent email. Record waiting-for-carrier and unresolved cases explicitly.
Guardrails include unnecessary reshipments per recovery, unauthorized redirections, false loss declarations, and inventory reserved beyond expiry. Compare operator minutes per case and customer recontact, including work caused by incorrect recommendations. Proposed improvement targets should reflect the actual baseline rather than borrowing industry averages.
Begin with read-only event reconciliation for one carrier and one exception type. Only then add staff-approved trace requests. The refund agent guide covers money movement after delivery failures, while fleet management addresses operational vehicle context. Data engineering services fit the event lineage and freshness foundations that make both dependable.