Migrating from 0.x to 1.0

@agorio/sdk v1.0.0 is the first release with a stable public API. This guide covers every breaking change between v0.7 and v1.0 and the minimum edits to move a working agent forward.

TL;DR — most code keeps working. The only mandatory edit is renaming experimental_ap2 to ap2 (and switching to the @agorio/sdk/security import for attestation if you were on the v0.8 release candidate).

Required edits

1. experimental_ap2 → ap2

The flag was promoted to GA in v0.8; v1.0 removes the deprecated alias.

 const agent = new ShoppingAgent({
   llm: claude,
-  experimental_ap2: true,
+  ap2: true,
 });

2. AP2 receivers should adopt verifyMandateShape

If you wrote your own structural checker, the SDK now ships one:

import { verifyMandateShape } from '@agorio/sdk';
 
const result = verifyMandateShape(signedMandate);
if (!result.ok) throw new Error(result.reason);

This is additive — your own checker still works, but the SDK version is the canonical reference implementation.

3. Cloud schema additions (self-hosted only)

Self-hosted Cloud deployments must apply the migrations introduced for v1.0:

• orgs, org_members — RBAC tables.
• cloud_audit_log — audit log.

Hosted Cloud customers get these automatically. Self-hosted operators run:

cd cloud && npm run db:push

Optional but recommended

Adopt agent identity attestation

If you call merchant APIs over the public internet, add the v0.8 AgentAttestation helper — an opt-in HMAC over the outgoing request envelope:

import { AgentAttestation } from '@agorio/sdk';
 
const att = new AgentAttestation({
  agentId: 'agent_acme_procurement_001',
  secret: process.env.AGENT_SECRET,
});
 
const fetchWithAttestation = att.wrapFetch();
 
// Pass to any adapter that accepts `fetch:`
const shopify = new ShopifyAdapter({ shop: '…', accessToken: '…', fetch: fetchWithAttestation });

Bench your changes

Run the benchmark harness on any PR that touches the agent core:

npx tsx bench/run.ts

Compare the printed table against bench/baseline-v0.8.0.json. Regressions over roughly 10% on any scenario should be justified in the PR description.

What did not change

• The ShoppingAgent constructor signature.
• All 17 built-in tools.
• The EnterprisePlugin lifecycle hooks (including hydrate?(state)).
• AgentChain / SubAgent composition.
• SessionStorage and the shipped MemorySessionStorage / FileSessionStorage.
• The wire format of agorioCloud() ingestion.

Removed in v1.0

v1.0 is intentionally a stability release, not a refactor. If you hit a migration edge case the table above doesn’t cover, open an issue on the repository.