Home Blog Integrating Retail Agents End-to-End: Events vs APIs vs Queues, State Correctness, and Replay

Integrating Retail Agents End-to-End: Events vs APIs vs Queues, State Correctness, and Replay

September 30, 2025 By Fatih Nayebi
Retail AIEvent-Driven ArchitectureSystemsAgentic AIReliability

Integrating Retail Agents End-to-End: Events vs APIs vs Queues, State Correctness, and Replay

Series: Foundations of Agentic AI for Retail (Part 9 of 10)
Based on the book: Foundations of Agentic AI for Retail

At 2:13am, an agent proposes a price change.

At 2:14am, a retry fires.

At 2:15am, the same change is applied twice.

Nothing about this is an LLM problem. It's an integration problem: a downstream system did exactly what it was told, twice, and your agent stack had no memory.

The fastest way to kill an agent project is to treat integration as plumbing. Integration is the product. It determines correctness, auditability, and whether anyone will trust the system.

Jump to: Rule | Events vs APIs vs queues | Integration contract | Replay | Idempotency | 30-day checklist

TL;DR

  • Events are memory, APIs are intent, queues are delivery mechanics.
  • State correctness is the hidden cost center in retail autonomy.
  • Replay is non-negotiable if you want trust, audits, and fast iteration.

The One-Sentence Rule

If you cannot replay decisions deterministically, you cannot debug, audit, or govern a retail agent.

Events vs APIs vs Queues (A Practical Decision Guide)

Think of them as different tools for different guarantees.

You need... Prefer... Why
audit trail and replay events immutable history and reproducibility
synchronous response APIs request/response with clear intent
buffering and retries queues delivery guarantees, backpressure

A common mistake is to choose one and force everything into it. Production systems usually use all three.

Then you hit the part that hurts: state correctness under messy reality.

How Agents Break State

Retail state is messy:

  • on-hand differs across systems
  • price and promo calendars lag
  • data arrives late or out of order
  • the same action can be executed twice under retries

If your agent writes directly to downstream systems without a gateway and idempotency, you will eventually double-apply an action.

The Integration Contract: Versioned Messages + Idempotent Writes

A minimal, practical contract:

- every message is versioned (v1, v2...)
- every action has an idempotency key
- every run has a trace id
- every write passes through a tool gateway

Once that contract exists, replay becomes an engineering tool, not an audit burden.

Replay: The Capability That Turns Agents Into Engineering

Replay is not only for auditors. It is for builders.

With replay, you can:

  • rerun the last 30 days of decisions after changing a policy
  • debug why the agent acted a certain way
  • compare two agent versions on the same history

That is how you get iteration speed without risking live KPIs.

Idempotency is the cheapest place to start.

Idempotent Consumer Pattern (Code Sketch)

type EventEnvelope<T> = {
  eventType: string; // e.g. price_change_proposed.v1
  traceId: string;
  idempotencyKey: string;
  asOf: string;
  payload: T;
};

const seen = new Set<string>();

export function handleEvent<T>(evt: EventEnvelope<T>) {
  if (seen.has(evt.idempotencyKey)) return; // idempotent

  // 1) validate payload (schema)
  // 2) apply policy gate
  // 3) execute through tool gateway

  seen.add(evt.idempotencyKey);
}

In reality, the "seen" set is a database table with TTL and strong semantics. The idea is the same.

A Minimal Idempotency Table (So Retries Do Not Hurt You)

If you want one practical upgrade that prevents painful incidents, build this:

create table idempotency_keys (
  idempotency_key text primary key,
  trace_id text not null,
  first_seen_at timestamptz not null,
  status text not null, -- applied | blocked | failed
  result_json jsonb
);

That lets your consumer be stateless and still safe under retries.

Failure Modes (Where Integration Hurts)

Failure mode What you will see Prevention
duplicate writes doubled price changes / orders idempotency keys + gateways
out-of-order events wrong state snapshots ordering rules + timestamps
schema drift silent breakage versioned schemas + validation
no audit trail stakeholder distrust trace ids + run records

Implementation Checklist (30 Days)

  • Define one event envelope format and enforce it.
  • Route all writes through a tool gateway (validation + idempotency).
  • Store run records (trace id + inputs hash + policy decisions).
  • Add replay for at least one decision surface.
  • Ship in shadow mode first, then gated autonomy.

FAQ

Can I do this with only APIs?
You can, but you will struggle with replay and audit unless you also persist an immutable history.

Are queues the same as events?
No. Queues are a delivery mechanism. Events are a source of truth.

What is the most common integration bug in agents?
Non-idempotent writes under retries.

Talk Abstract (You Can Reuse)

Agent projects often fail in integration, not intelligence.

This talk is a decision guide for events vs APIs vs queues, plus the unglamorous mechanics that keep retail KPIs safe: idempotency keys, gateways, state correctness under retries and out-of-order data, and replay. If you can replay, you can iterate. If you cannot, you will either ship blind or stop shipping.

Talk title ideas:

  • Events vs APIs vs Queues: The Integration Contracts Behind Retail Agents
  • Replay or Regret: Auditable Autonomy for Retail
  • State Correctness: The Hidden Cost Center of Agentic Systems

Next in the Series

Next: AgentOps and Governance for Retail Agents: From Prototype to Production (with a Maturity Roadmap)

Series Navigation

Work With Me

← Back to all posts