Five trust boundaries
The reference architecture draws hard boundaries around the agent runtime, policy engine, credential service, commerce adapter, and evidence ledger. Each receives the minimum information and authority necessary for its job.
- Agent runtime: plans, calls tools, and proposes transactions; it does not own unrestricted credentials.
- Policy engine: evaluates typed facts and mandates; it does not rely on model confidence as authorization.
- Credential service: signs or grants scoped credentials only after an approved policy decision.
- Commerce adapter: normalizes merchant, cart, checkout, and fulfillment state across protocols.
- Evidence ledger: links immutable references across decisions, payments, outcomes, and remediation.
The identifier spine
Cross-system identifiers are more important than a single database schema. Create an intent ID before discovery, a mandate or policy-decision ID before credential issuance, an order ID before payment, and an idempotency key before execution. Preserve processor, facilitator, or transaction identifiers after the rail responds.
Every log, receipt, and asynchronous event should carry enough of this spine to join the story without exposing secrets. When vendors generate their own identifiers, maintain an explicit mapping rather than overloading one field.
| Identifier | Created when | Protects against |
|---|---|---|
| intent_id | Goal accepted | Losing the original purpose across replanning |
| order_id | Final merchant state frozen | Paying for a mutated or duplicate cart |
| decision_id | Policy evaluated | Unexplained or unversioned authorization |
| credential_ref | Scoped authority issued | Raw secret exposure and ambiguous scope |
| idempotency_key | Execution begins | Retries creating duplicate financial effects |
| rail_ref | Rail accepts or settles | Unreconciled processor or chain state |
Model the transaction as a state machine
Use explicit states such as proposed, awaiting approval, authorized, submitted, settled, fulfilled, failed, refunded, and disputed. Make transitions monotonic where possible and require compensating events rather than editing history.
Asynchronous rails and merchants demand reconciliation jobs. A timeout is not proof of failure, and a successful payment is not proof of fulfillment. Poll or consume signed webhooks, verify their origin, and make handlers idempotent.
Use protocol adapters, not protocol-shaped core logic
AP2, x402, payment processors, wallets, and merchant checkout protocols evolve at different speeds. Keep a stable internal model for intent, mandate, order, decision, credential, payment, and outcome. Translate at the edges and record the source schema version.
This lets the policy engine remain rail-neutral and prevents a protocol migration from rewriting the entire product. It also makes comparison tests possible: the same approved order can be exercised through different payment adapters with the expected evidence contract held constant.
Design failure before the happy path
List the ambiguous outcomes: the agent retries after a network timeout, the merchant changes tax after approval, the facilitator settles but the response is lost, the item becomes unavailable, the refund goes to a different rail, or a webhook arrives twice. Give each case a deterministic recovery rule and an operator view.
- Never retry a financial action without the same idempotency key and order hash.
- Never infer settlement from an HTTP timeout or model message.
- Never fulfill from an unverified client assertion when server-side verification is available.
- Never silently substitute rail, asset, seller, or terms outside the mandate.
- Always make the principal’s recourse visible in the final receipt.
Source discipline
Primary sources
Product status and protocol behavior are checked against maintainer documentation. Company sources establish what their organizations publish; they do not independently prove adoption or performance.