Skip to content

cookbook · 2026-05

Cookbook.

30 production patterns. 20 battle-tested in real money flows. 3 demonstrate cross-package composition. Every recipe is runnable TypeScript.

The cookbook is the working answer to "what does an agent that actually transacts in Argentina look like?" Each recipe is a single TypeScript file, fully typed, with the SDK surface, the gotchas, and the exact sequence of tool calls. Read it as a tutorial, copy as a starter, deploy as production.
Source: packages/mercadopago/cookbook. Every recipe is Edge-Runtime compatible; uncomment export const runtime = "edge" to deploy on Vercel Edge / Cloudflare Workers.

● Starter · 1

mercadopago
Hosted checkout URL for a one-off purchase. Buyer enters card on MP's form (no PCI scope for you). MP fires payment webhook on completion.

● Production patterns · 20

mercadopago
Reusable Plan, per-customer subscribe_to_plan, recurring auto-charge, card swap on expiration via update_subscription({ card_token_id }).
→ Card swap is the path that breaks the most production deploys — recipe wires it correctly.
mercadopago
Rappi / Tienda Nube pattern. Seller connects MP via OAuth, your platform takes a marketplace fee, the rest splits to the seller's MP account. VercelKVOAuthTokenStore for token persistence.
mercadopagowhatsapp
Dynamic QR for brick-and-mortar. create_store + create_pos one-time, create_qr_payment per sale. Cashier gets WhatsApp '✓ Cobro $X' notification when payment lands.
incorporate
Daily cron-driven Node.js script that ingests audit entries via fetchAudit(sessionId, { verify: true }), buckets by tool / governance / latency, surfaces anomalies (tampering, error-rate spikes, p95 regressions), and renders a contador-friendly Spanish summary for monthly compliance reports. The pattern that turns RFC-001 § 9.2's 'legally probative' into actually monitored.
→ Multi-tenant marketplaces operating many sociedades-IA scale linearly with this — one digest per tenant, escalation on tampered.
facturacionmercadopagoincorporate
Daily cron that cross-references MP payments against AFIP-issued CAEs against the audit log. Surfaces 3 drift classes (MP paid + no factura, factura + no MP payment, duplicate MP payments + one factura), auto-corrects the safe ones (re-emit factura on MP-paid orphans), and renders a contador-friendly Spanish digest for monthly compliance. The pattern that catches every silent failure in the AFIP/MP bridge.
→ AFIP fails ~30% of mechanical CAE requests. WSFE silent failures + MP retries make drift inevitable. Recipe 22 is the floor.
identitybankinggde-tadwhatsapp
Production chat (Astro Chat at astro.ar) cutting over from raw @anthropic-ai/sdk to @ar-agents/* via an additive route (/api/arg) instead of rewriting the legacy /api/chat. Risk-asymmetric, reversible, observable. The exact pattern any production-already-shipped operator should follow when adopting the toolkit without a stop-the-world rewrite.
→ Live on naza00000/astro/feat/ar-agents-cutover. Full merge readiness review in docs/launch/astro-cutover-merge-readiness.md.
incorporate
Nightly export of a sociedad's configuration to portable JSON (no secrets — those stay in your secrets manager). When disaster hits (Vercel project deleted, repo locked, laptop dies), feed the export to a fresh /api/auto-incorporate call with the SAME sessionId — the forensic audit timeline continues unbroken across the disaster. Regulators see one chain of events, not two.
→ sessionId continuity is the load-bearing piece. The export references env-var names (not values), so recovery is config-portable without secret leakage.
incorporate
Pure function that takes a list of sessionIds + a sociedad metadata block and produces a single self-contained JSON report: per-session timelines + HMAC-verification results + cross-session aggregates + anomalies (clock-skew, governance-shifts, errored LLM calls, missing-HMAC) + a self-disclosure conclusion (clean / anomalies-noted / tampering-detected) + remediation list. Optionally HMAC-signs the report itself for tamper-evidence. Bundles RFC-004 § 9's four mandatory artifacts into one document.
→ The operational narrative a regulator can demand without a court order, generated from the log not from the operator's recollection. Companion to RFC-004 § 9 + /auditor.
incorporate
Reusable TypeScript function that takes a target base URL, runs ~9 checks against its public endpoints (well-known, audit-read, audit-verify, CSV, OpenAPI, security headers), and returns a 0-100 conformance score + per-check breakdown. Same function backs the /certifier web flow + the /api/certifier HTTP endpoint. Pure fetch, runs in Edge / Node / browser / deno. Includes a CLI mode that exits non-zero if score < 60 — drop into CI as a pre-merge gate.
→ Anyone can verify any sociedad-IA's claims from one HTTP call. No install, no setup. Lives behind /certifier (web) + /api/certifier (programmatic).
incorporate
Pure monitor loop that POSTs to /api/conformance-history every N minutes to append a new cert-score for a URL, then compares the latest against a sliding-window baseline (default: median of last 24 points). If the new score drops > threshold (default 10%), fires an alert via Slack/webhook. KV-backed 365-entry capped time-series with 90-day TTL. Idempotent. Drop into Vercel cron, GitHub Actions schedule, or any scheduler. Exits non-zero on alert for CI integration.
→ Conformance isn't a snapshot — it's a horizon. Recipe 27 turns the certifier into a continuous monitor with drift detection + alerting. Companion to recipe 25 (compliance report) + the /audit-explorer page.
incorporate
Pure function `checkOperatorReadiness(baseUrl)` that walks 10 pre-launch items (discovery manifest, audit endpoints, CSV export, RFC-005 keys, OpenAPI spec, HSTS headers, sitemap, /llms.txt) and returns a per-item pass/fail/skip with remediation links. Reads as the readiness report the operator's pre-launch sign-off. Aggregate readiness rating: ready / almost / blocked. CLI mode exits non-zero on blocked.
→ Different from recipe 26 (RFC conformance, public) — recipe 28 is operator-internal pre-launch sign-off. Used by /api/auto-incorporate to validate freshly-deployed sociedades before adding to /registro.
incorporate
Generate an Ed25519 keypair via Web Crypto, format the public key as SPKI base64url (RFC-005 § 4 wire format), and print: (1) the public-keys JSON to drop into public/.well-known/sociedad-ia/keys.json, (2) the private key as PKCS8 base64url to paste into the operator's secrets manager (Vercel env, 1Password, AWS SM). Same keyId can stay valid; rotation is additive.
→ The one-time bootstrap for opting into the RFC-005 asymmetric path. Subsequent appendAudit calls automatically include both `hmac` (v1) and `signature` (v2) entries when AUDIT_ED25519_PRIVATE_KEY is set.
incorporate
Pre-flight check + PR-body generator. Runs recipe 28 (operator readiness) + recipe 26 (RFC certifier) against your URL, validates honesty heuristics (CUIT format, demo-vs-productive disclosure language, type matches behavior), and if everything passes, prints a copy-paste Markdown PR body for the registry submission. Refuses to produce a PR body if any check fails — prevents over-eager submission of half-built sociedades.
→ Closes the loop from incorporated → conformant → certified → publicly listed. With recipe 30, the full operator lifecycle from `vercel deploy` to listing in /registro is scripted + repeatable.

● Composition (multi-package) · 3

identityidentity-attestmercadopagofacturacionwhatsapp
The flagship composability demo. One prompt → CUIT validate → AFIP padron lookup → BCRA credit-situation check → WhatsApp OTP attestation → MP subscription → AFIP factura → WhatsApp PDF delivery.
→ What would normally be 200 lines of orchestration code, in 30. The killer demo.

● Infrastructure / agent commerce · 6

mercadopago
W3C traceparent on every MP API call. mp.request + mp.tool spans. p50/p95/p99 latency + error-rate + rate-limit-remaining metrics. Ships to Honeycomb / Datadog / Grafana Tempo.
agentic-commerce-bridgemercadopagofacturacion
Stripe-style hosted checkout where the BUYER is an LLM agent (ChatGPT / Claude / Gemini). On payment confirmation, server auto-emits AFIP factura A/B/C/E with CAE.
→ Headline pattern that no other LATAM implementation ships out of the box.
incorporateap2agentic-commerce-bridge
USA-LLC agent calls @ar-agents/incorporate's `incorporate({...})` to spin up an AR sociedad-IA's deploy spec in one call. Receives generated package.json + agent.ts + .env.example + README.md + Vercel deploy URL + signed audit-log reference. Chains incorporation + ongoing operations under a single forensic timeline.
→ The headline claim of /sociedades-ia made fully programmatic. `pnpm add @ar-agents/incorporate` + 1 await.
incorporate
Vertical SaaS / marketplace pattern: each new vendor signing up gets a fresh sociedad-IA spec materialized via @ar-agents/incorporate, audit log keyed by tenantId. Pieza selection driven by vendor profile (ecommerce → +shipping, large-revenue → +whatsapp/ACP/AP2). Includes the platform-side compliance sweep that fan-outs recipe 19 across tenants, and the badge SVG embed for vendor profile pages.
→ Pre-toolkit, this was a manual escribano job per vendor. Post-toolkit: ~50 lines + idempotent.
incorporateap2facturacionidentitybanking
USA-LLC sells to AR consumer; AR sociedad-IA verifies AP2 mandate (ES256/JWS), enforces per-op + monthly + idempotent caps, runs CUIT validity + BCRA credit checks, then emits factura A/B/C under its own CUIT. Each refusal lands as an audit entry that's challengeable later. The reference implementation of RFC-001 § 7's cross-jurisdictional contract surface.
→ 5 verification gates + idempotency + audit-log-as-evidence in ~250 lines. Wyoming DAO LLC plugs into AR jurisdiction without refactoring its agent.

How to run a recipe locally

Each recipe assumes you've installed the relevant @ar-agents/* packages. Then:

# clone the repo (recipes import from the workspace, but the same
# code works against published @ar-agents/* npm packages)
git clone https://github.com/ar-agents/ar-agents
cd ar-agents
pnpm install

# set env vars (MP token, AFIP cert, etc — see each recipe's header)
cp .env.example .env.local
$EDITOR .env.local

# run a recipe
pnpm tsx packages/mercadopago/cookbook/10-cross-package-billing.ts

What recipe is missing for your case?

Cookbook gaps are the best signal of where the toolkit needs to go next. Open an issue at https://github.com/ar-agents/ar-agents/issues with the use case and the API surface you wish existed — most new recipes start as a one-paragraph issue.