ar-agents is a Mercado Pago Agent Toolkit for the Vercel AI SDK 6. It ships 89 typed tools that an LLM agent can call directly to drive Mercado Pago billing flows: subscriptions, payments, refunds, checkout pro, marketplace OAuth, cuotas (installments), QR in-store, 3DS challenge resolution, point-of-sale devices, webhooks. Sidecar packages cover AFIP/ARCA, WhatsApp Business Cloud, banking (CBU/CVU + BCRA), and shipping (Andreani/OCA/Correo Argentino).

How is this different from the official mercadopago SDK?

The official mercadopago SDK is a thin REST client. It does not ship Vercel AI SDK tool schemas, does not implement webhook HMAC verification with replay protection, does not run on Edge Runtime (Node-only), and does not gate irreversible operations. ar-agents adds all of that on top of the underlying API: 89 typed tools, deterministic idempotency keys derived from inputs, programmatic human-in-the-loop on refund/cancel/delete, npm provenance attestation, Vercel KV adapters via subpath, OpenTelemetry instrumentation. You can use both packages in the same project; ar-agents wraps the underlying API directly without depending on the official SDK.

Does ar-agents work on Edge Runtime?

Yes. The whole package is Web Crypto-based with no node:crypto dependency, so it runs on Vercel Edge Functions, Cloudflare Workers, Deno, and any other V8-isolate runtime. Webhook signature verification, HMAC, and idempotency-key generation all use the Web Crypto API.

What is HITL (human-in-the-loop) in ar-agents?

Eight tools mutate state irreversibly (refund_payment, cancel_subscription, delete_customer_card, etc.). The toolkit accepts a requireConfirmation callback that gates each invocation: the tool function literally will not execute until your callback returns true. This is a programmatic gate, not just an LLM instruction. You can show the user a UI and wait for their explicit approval before any irreversible operation runs.

How does idempotency work?

Every POST request gets an auto-generated idempotency key. For LLM-driven retries, four mutating tools (create_payment, create_subscription, create_payment_preference, refund_payment) use a deterministic key derived from a SHA-256 hash of the meaningful inputs (external_reference, amount, payment_method, etc.). Same inputs produce the same key, so retries return the existing resource instead of double-charging the customer.

Yes. MIT license. No paid tier, no telemetry phone-home, no usage caps. The package is published to npm under the @ar-agents scope with SLSA v1 provenance attestations.

What about AFIP, WhatsApp, banking, shipping?

Sidecar packages cover the rest of the Argentine business stack: @ar-agents/identity (CUIT/CUIL validation + AFIP/ARCA padron lookup with monotributo category and IVA condition), @ar-agents/facturacion (AFIP/ARCA factura electronica via WSFE), @ar-agents/whatsapp (WhatsApp Business Cloud API with HMAC webhook verify and AR phone normalizer), @ar-agents/banking (CBU/CVU validation + BCRA Central de Deudores), @ar-agents/shipping (Andreani, OCA, Correo Argentino), @ar-agents/identity-attest (HMAC-signed verification orchestrator). Each ships independently to npm.

Is there a Model Context Protocol (MCP) server?

Yes. @ar-agents/mcp bundles all 7 ar-agents packages into a single MCP server compatible with Claude Desktop, Cursor, Codeium, Continue, Cline, or any MCP host. Auto-detects which packages to enable from environment variables. Listed on Glama (glama.ai/mcp/servers/ar-agents/ar-agents) and the official MCP Registry (io.github.ar-agents/mcp).

Case study · Astro (astro.ar)

The maintainer's own AR-context products are mid-cutover from raw SDKs to the @ar-agents/* tool surface. This page is the honest-as-it-is record of the migration — what runs on the toolkit today, what doesn't yet, and which production numbers we'll publish once the cutover lands.

Disclosure. Astro and @ar-agents/*are owned by the same person (Nazareno Clemente). Astro is the financial floor that keeps the toolkit's author employed; the toolkit is the operating system the maintainer wants Astro to run on. Treat this as a migration log from a single founder, not a third-party customer testimonial. Other case studies will follow as the user base grows.

The discipline of publishing this is precisely that it prevents fabricated claims. The maintainer's own product runs on raw SDKs today; the migration to @ar-agents/* is the next visible cutover. When it lands, this page replaces aspirational copy with measured numbers — invoice volume, dedup rate, audit-log size, webhook-signature reject count.

The product surfaces

astro.ar · Astro Chat

LLM chat with Argentine-context tools. Uses @ar-agents/identity for CUIT validation when the user mentions a tax ID, @ar-agents/banking for USD oficial / CER / UVA queries, and @ar-agents/boletin-oficial for regulatory lookups. Live since 2025-12.

astro.ar/bots · WhatsApp business copilot

The end-to-end use case the toolkit was designed for. Operates entirely from a WhatsApp inbox: customer asks for a quote, the agent validates the CUIT, runs a BCRA credit check, creates an MP subscription, issues the AFIP factura on payment, and sends the PDF back via WhatsApp. The cross-package billing recipe (R10 in the cookbook) is the exact code this surface runs in production. Build phase as of 2026-05; blocked on Meta business verification (5-recipient dev cap).

astro.ar/clips · Clipper marketplace

Two-sided marketplace for clip creators and brands. Uses @ar-agents/mercadopagomarketplace OAuth to split payouts to creators' MP accounts, @ar-agents/identity for AFIP padron validation on creator onboarding, and @ar-agents/facturacion for auto-issued Facturas A/B/C/E to brand customers when a clip lands. Build phase.

The operating loop

Astro's entire backend fits in three Edge-runtime route handlers and a cron job:

1. The webhook receivers.One per upstream (MP, WhatsApp, ACP). They verify HMAC, dedupe, and dispatch to the agent loop. Together they're < 200 lines of TS. Every recipe in the cookbook's "production patterns" tier (R03, R08, R11, R12) was written to support this surface.

2. The agent loop. One Experimental_Agent from ai@^6 with all needed tool collections spread in. Same agent across all three surfaces — different system prompts and different identity-attestation gates. The composition recipe (R10) is the canonical example.

3. The morning cron. One Vercel Cron triggers a per-tenant list_domicilio_inbox + get_critical_notifications + list_recent_publications (Boletín Oficial) call. The agent triages and posts a daily WhatsApp briefing to the operator.

What broke and what got fixed

MP Subscriptions API. 9 separate gotchas hit during build. back_urlmust be HTTPS in prod; "Cannot operate between different countries" really means the seller and buyer accounts are different account types; buyer email cannot equal seller email; CVV is required even on saved cards; reCAPTCHA v3 invisible blocks Confirmar when scripts are blocked; PUT cannot force authorized status. Each gotcha became a comment in the source and a checked condition in recoverPayment(). The full list lives in the package's AGENTS.md.

AFIP/ARCA WSAA + WSFE. 11 gotchas. PKCS#7 must be attached not detached; cert issued by AFIP prod CA does not work against homo and vice versa; A13 vs A5 deprecation; A13 SOAP response shape is different from public docs; echo in shell adds a trailing newline that breaks WSAA URLs; PEM strings from env vars sometimes survive with literal \\n instead of newlines. Each gotcha became a check in normalizePem() or a doctor-CLI assertion.

Vercel monorepo + pnpm workspace.A workspace package's dist/isn't available to a depending app at build time unless the build command explicitly compiles the workspace dep first. Now every Astro app sets buildCommand: "cd ../.. && pnpm --filter X build && pnpm --filter Y build".

What we measure (when we have the numbers)

Honest status (2026-05-09): Astro Chat's main /api/chat route is in production (since 2025-12) on the raw @anthropic-ai/sdk. The first slice of the cutover landed on a feature branch: feat/ar-agents-cutover ships a new, additive /api/arg route + a ar-agents visitor page running entirely on Vercel AI SDK 6 + @ar-agents/identity + @ar-agents/banking + @ar-agents/gde-tad. The legacy chat path is untouched. Once ar-agents has a week of production behavior visible, the next slices migrate /api/chat's AFIP/MP integrations to the matching @ar-agents packages.

What is verifiable today: every @ar-agents/* package ships SLSA v1 npm provenance attestations (npm view @ar-agents/identity dist.attestations), the ACP webhook surface rejects unsigned mandates (packages/agentic-commerce-bridge/test/*), the bundled @ar-agents/mcp server passes its doctor CLI on a stock dev machine (npx ar-agents-mcp doctor), and the live /play endpoint generates HMAC-signed audit entries on every tool call — click any session URL like /dashboard/{sessionId} for a forensic timeline. Those are the assertions a regulator can challenge today.

When the Astro Chat → @ar-agents/* cutover ships, this section gets replaced with concrete production numbers and a methodology link.

What this case study is for

Three things:

1. Forcing function. The toolkit is only as good as the production load it can sustain. Astro is the production load.

2. Recruiting evidence. Devs evaluating the toolkit need to see it survive contact with reality. Astro is the reality.

3. Regulatory evidence.When ARCA / IGJ / Sturzenegger's office ask "is anyone actually using this?", the answer is "yes — the maintainer's own company runs end-to-end on it". The first sociedad-IA will not be ACME-AI from a slide deck; it will be a company that has already been running at SAS-grade for a year, flipping one config flag.

Astro · planned reference customer for @ar-agents/*.

The product surfaces

The operating loop

What broke and what got fixed

What we measure (when we have the numbers)

What this case study is for