Transactional Outbox for Agent Actions

Definition

The transactional outbox pattern stores a business change and a message to be published within the same local transaction. A separate publisher delivers the message, allowing downstream agent work to be triggered reliably while still requiring duplicate handling.

Writing a database record and publishing a message are two operations that can fail independently. Without coordination, the record can say a task is ready while no worker is notified, or a worker can act on a task whose state was never committed.

What it covers

Local transaction

The state change and outgoing event recorded together.

Publisher

The process delivering stored events.

Consumer

The handler applying an event’s consequence.

Reconciliation

Recovery from delayed or duplicate delivery.

The outbox addresses a particular local consistency boundary. It does not make an external payment or email atomic with the database. Those effects still need their own operation identifiers, outcome checks and recovery rules.

In practice

Practical design patterns by Min.

• Choose stable event and business-operation identifiers.
• Make consumers detect or tolerate duplicates.
• Monitor publication lag and failed deliveries.

Track each stored event through publication and consumption. Define retention and replay rules so recovery is deliberate rather than accidental. A consumer should validate current task authority if delivery occurs after permissions or approval conditions have changed.

Research notes

Source-grounded details and editorial applications. Follow each link for the original document.

Working example

Why the controls matter

In the approval example, the worker may receive the same event twice after a publisher retry. The business operation must remain singular. Event deduplication and transaction-level idempotency are related controls, but their keys and retention windows need explicit design.

Common pitfalls

• Claiming the pattern guarantees exactly-once external effects.
• Dropping an event after an uncertain publish result.
• Assuming message order is always preserved.

Operational lag matters: a correctly stored event can still arrive too late to act safely. Use task deadlines and expiry checks, and make a backlog visible to an owner. Do not equate durable publication with timely or authorized execution.

Questions for operational review

Use these questions to decide what evidence your team needs. They are editorial prompts, not a compliance checklist.

• Which state changes share a real transaction?
• How does duplicate delivery affect the business operation?
• Can an old event still trigger work after authority expires?