106 — Event Sourcing for Agent Workflows

Concept overview

Event sourcing stores the facts that changed workflow state rather than only the latest state snapshot. Events such as EvidenceAttached, ApprovalGranted, ActionSubmitted, and ReceiptObserved form a business history. Read models derive the current view from that history and can be rebuilt when projection logic changes.

An event log is not a transcript of every model token. Choose stable domain facts with identifiers, schema versions, and ordering rules. Distinguish requested actions from confirmed effects, and store sensitive payloads through governed references where possible. Replaying events rebuilds state; it must not automatically repeat external side effects.

Why it matters in production

Proof of concept

A proof of concept can append a few workflow facts and rebuild one projection to verify that the domain events capture meaningful transitions.

Production

Production requires optimistic concurrency, event schema evolution, idempotent consumers, protected payload references, and separation between projections and effect execution.

Enterprise scale

Enterprise scale adds partitioning, projection lag monitoring, snapshot strategy, replay tooling, retention governance, and migrations across years of event versions.

Architecture components

Command handler

Validates requested transitions against current aggregate state and business authorization.

Append-only event store

Persists accepted facts with aggregate version, event identity, and schema metadata.

Projection workers

Build query views and dashboards from events without triggering business effects during replay.

Effect dispatcher

Executes approved external actions using stable operation keys and records their observed results.

Replay and audit tools

Reconstruct historical state and explain which facts supported a decision at a particular version.

The architecture, mapped

flowchart LR
    C["Authorized command"] --> H["Versioned command handler"]
    H --> E["Append-only domain events"]
    E --> P["Idempotent projections"]
    P --> V["Current and historical views"]
    E --> D["Live effect dispatcher"]
    D --> S["External service"]
    S --> R["Observed receipt event"]
    R --> E
    E --> B["Side-effect-free replay"]

Runtime flow

1. 1

   Receive command

   Attach requester, workflow identity, expected aggregate version, and approval references to the requested transition.

2. 2

   Validate current state

   Reject commands whose preconditions or authority no longer hold against the latest accepted event version.

3. 3

   Append accepted facts

   Atomically record the domain event and any dispatch intent using a consistent transaction or outbox boundary.

4. 4

   Update projections

   Consume events idempotently, retaining sequence positions and exposing projection freshness to readers.

5. 5

   Execute authorized effects

   Dispatch only eligible live action intents with stable keys and record submission, uncertainty, or receipt as separate facts.

6. 6

   Rebuild safely

   Replay historical events into new projections with side effects disabled, then compare reconstructed state before switching readers.

Claim evidence and review history

Insurance · Illustrative enterprise scenario, not a reported customer outcome.

Business situation

Illustrative architecture: An insurer must explain which claim documents and policy revisions were available when an adjuster approved a packet.

The problem

Overwriting the latest case state loses the distinction between the original decision and later evidence corrections.

Agent requirement

Reconstruct review history while keeping payments and customer notices from repeating during replay.

Architecture

The claim aggregate records evidence and approval events; projections show the current packet, while a separate dispatcher handles approved external actions.

Runtime

• Append evidence revision
• project review packet
• record adjuster approval
• dispatch approved notice
• append receipt
• rebuild historical packet on request

Failure scenario

A projection is rebuilt after a code change; it regenerates the timeline but does not resend the previously issued customer notice.

Operational impact

Measure reconstruction accuracy, projection lag, duplicate-consumer handling, event schema compatibility, and unresolved effect receipts rather than treating log volume as audit quality.

Architecture tradeoffs

Failure scenarios & recovery

Common architecture mistakes

Storing arbitrary model prose as the primary event schema.

Record explicit domain facts and keep generated drafts as referenced artifacts.

Replaying history through the live effect executor.

Disable side effects during projection rebuild and separate dispatch eligibility from event consumption.

Embedding sensitive documents permanently in every event.

Use governed payload references with explicit access, retention, and correction policies.

When to choose this pattern

Choose it when

• Historical decision reconstruction is a first-class operational requirement.
• Several teams need different read views over the same accepted workflow facts.
• Business state evolves through meaningful transitions with explicit version conflicts.

Avoid it when

• Simple current-state CRUD meets the audit and recovery requirements adequately.
• The team cannot own event evolution, projection operations, and replay safety.
• An append-only payload design would conflict with required information lifecycle controls.

Architecture checklist

• Define stable domain events and distinguish intent, submission, and confirmed effect.
• Assign aggregate versions and reject conflicting commands atomically.
• Make projection consumers idempotent and expose their freshness.
• Separate live effect dispatch from historical replay.
• Version event schemas and test old histories against new code.
• Design sensitive payload references, access policy, and retention handling.
• Verify historical reconstruction and duplicate-delivery recovery before adoption.

Related concepts

• 3 — Agentic State Machines
• 12 — State Persistence
• 15 — Event-Driven Agent Triggers
• 30 — Non-Repudiation Logs
• 38 — Data Lineage Tracking
• 41 — Idempotent Tool Execution
• 55 — Distributed Tracing (OpenTelemetry)
• 57 — Crash-Safe Memory

Primary references

• Microsoft Azure Architecture Center: Event Sourcing pattern
• Temporal: Workflow execution
• W3C PROV overview