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).

/glossary · 21 terms · alphabetical

Glossary.

Every term used across ar-agents, in one searchable page. For journalists writing their first piece, legislators reading the RFCs cold, developers integrating the libraries. Each entry links to its canonical reference on the site.

Agentconcept
An autonomous software entity that takes actions on behalf of a human or a sociedad-IA.
In ar-agents, an agent is the runtime that calls tools (MercadoPago, AFIP, WhatsApp, etc.) on behalf of an operator. Built on top of Vercel AI SDK 6 Experimental_Agent. Each tool-call lands in an audit log entry, signed with HMAC-SHA256 + classified by governance class.
→ Reference impl → Demo
agents.jsonspec
Discovery manifest at /.well-known/agents.json.
Per RFC-002 + the agents.md v1 convention, every sociedad-IA publishes capabilities + audit endpoints + jurisdiction at this URL. Two compatible shapes accepted: strict map (RFC-002 v1) and array (agents.md v1).
→ JSON schema → RFC-002 → Live example
Related: RFC-002 · Discovery
AP2protocol
Agent Payments Protocol. Mandate-based, signed.
Originated in the Google AP2 spec. In ar-agents, an AP2 mandate is a signed promise to pay (e.g. a Wyoming DAO LLC mandates $X to AR-CUIT-Y, payable for T+24h). The AR sociedad verifies the signature, emits the factura, lands the cobro. Recipe 21 walks through the full cross-jurisdictional flow.
→ Cookbook recipe 21 → Package @ar-agents/ap2
Append-onlyconcept
Property of a log where existing entries cannot be modified or deleted, only new entries appended.
RFC-004 § 4 pins this down concretely: the library exposes exactly one mutation primitive (appendAudit), no update/delete; the backing store uses RPUSH/LRANGE; entry IDs are timestamp-prefixed so textual sort = temporal order; HMAC over the whole entry catches any post-hoc mutation. The only permitted destructive action is TTL-based retention purge.
→ RFC-004 § 4 → Reference impl
Audit logconcept
Append-only HMAC-SHA256-signed record of every action a sociedad-IA takes.
The legal-and-technical primitive that makes a sociedad-IA's operating history reconstructible after the fact. Every tool-call → one entry. Each entry has id, sessionId, ts, tool, governance, input, output, hmac. Stored in Vercel KV (Upstash, sa-east-1) with 7-day TTL in dev; production sociedades configure 180d-to-5y retention per RFC-004 § 7.
→ Deep-dive → RFC-004 → Verify any session
Related: HMAC · RFC-004 · Canonical-JSON
Canonical-JSONspec
Deterministic JSON serialization with sorted object keys.
JSON.stringify in JavaScript follows object insertion order, different runtimes can produce different bytes for semantically-equivalent objects. The HMAC of a canonical-JSON form is stable across runtimes + re-serializations. RFC-004 § 3 specifies the algorithm: keys sorted lexicographically at every depth, arrays preserve order. Test-vectors 1-2 prove the implementation.
→ RFC-004 § 3 → Test vectors
Certifiertool
Web flow + API that scores any URL 0-100 against RFC-002 + RFC-004.
Runs ~9 HTTP checks against a target's public endpoints (agents.json, audit-read, verify, CSV, OpenAPI, security headers) and returns a deterministic Certification JSON. Anyone can verify any sociedad-IA's claims from a single HTTP call with no install.
→ Web UI → API → Recipe 26
CUITconcept
Clave Única de Identificación Tributaria, Argentine tax-ID format XX-XXXXXXXX-X.
Issued by AFIP/ARCA. Required to invoice (factura electrónica), open a bank account, register as monotributista. The @ar-agents/identity package validates + does padron lookups against the live ARCA WSAA service.
→ @ar-agents/identity → cuit-hello demo
Discoveryconcept
The convention that lets a third party find a sociedad-IA's endpoints without prior knowledge.
RFC-002 specifies discovery via /.well-known/agents.json. RFC-002-v1.1 adds discovery via DNS TXT (planned). A regulator inspecting a sociedad-IA's URL never has to ask the operator where the audit endpoints are, they're at a fixed location.
→ RFC-002 → Live manifest
Governance classconcept
One of four tags on each audit entry: algorithm-only, audit-logged, mocked-upstream, requires-confirmation.
Determines RFC-001 liability layer. algorithm-only = pure deterministic code, operator liable. audit-logged = LLM call ran with output logged, operator + recorded model provider share. mocked-upstream = demo-tier, no productive effect. requires-confirmation = human-in-the-loop, the confirming human absorbs liability for the action.
→ RFC-001 § 4 → RFC-004 § 6
HMAC-SHA256spec
Keyed cryptographic hash. RFC 2104 / FIPS 198-1.
Each audit entry's HMAC is computed over the canonical-JSON of the entry (with the hmac field stripped) using a shared secret. The signature can be re-computed and verified by anyone holding the key. Even without the key, anyone can fetch the entries + the verify endpoint to confirm tamper-free state. RFC-004 v1 uses symmetric HMAC; v2 will add asymmetric Ed25519 signatures.
→ RFC-004 § 3 → Web Crypto reference
Incorporatetool
Auto-incorporation flow: name + capital + objeto + representante → generated sociedad-IA + Vercel deploy.
Public wizard at /incorporar. Underneath, calls POST /api/auto-incorporate which generates: source files (Next.js app per sociedad-IA-starter), env-var manifest, legal+operational checklist, audit-log session reference. npm package @ar-agents/incorporate ships the typed TS client.
→ Wizard → API → @ar-agents/incorporate
MCPprotocol
Model Context Protocol. Anthropic / open spec for AI-agent tool servers.
@ar-agents/mcp wraps every ar-agents library (identity, mercadopago, whatsapp, banking, facturacion, shipping, igj, gde-tad, boletin-oficial, mi-argentina, firma-digital, identity-attest, mercadolibre) as MCP tools so Claude Desktop / Claude Code / ChatGPT MCP users can call them directly.
→ @ar-agents/mcp → Repo
Operatorconcept
The human (or legal entity) responsible for a specific sociedad-IA.
Per RFC-001 § 4, the operator absorbs Layer 1 liability, actions tagged algorithm-only or requires-confirmation flow to them. CUIT-identified in the sociedad's well-known manifest. The operator does NOT necessarily code the sociedad; they configure it + accept its operating obligations.
→ RFC-001 § 4
RFC-001spec
Three-layer civil-liability framework for sociedades-IA.
Operator (Layer 1) → sociedad-IA (Layer 2) → model provider (Layer 3). § 9 specifies the audit-log probative-value contract; § 4 defines governance classes. The keystone document for the regime.
→ Full spec
Related: Governance class · Operator
RFC-002spec
Agent-discovery-by-default convention.
Every sociedad-IA publishes /.well-known/agents.json with issuer, endpoints, rfcConformance. No central registry, no permission. A regulator finds anyone's audit endpoints by going to their domain + /.well-known/agents.json.
→ Full spec → Schema
RFC-003spec
Cross-jurisdictional audit-log reciprocity envelope.
Portable JSON envelope for sociedad-IA audit logs crossing jurisdictional boundaries. AR ↔ Wyoming DAO LLC ↔ MIDAO ↔ Estonia OÜ. Each side keeps its own log; the envelope makes them mutually verifiable.
→ Full spec → Schema
RFC-004spec
Normative operational-log wire format.
Pins down what RFC-001 § 9 left open: entry shape, HMAC computation, append-only invariants, verification interface, retention boundaries, conformance test vectors. The document legislation can cite to anchor enforcement.
→ Full spec → Schema → Vectors
Sessionconcept
A coherent series of tool-calls sharing a single governance context.
Identified by sessionId (8-64 chars [A-Za-z0-9_-]). Typically corresponds to one customer interaction, one business day, or one HITL-confirmed flow. Each session has its own audit timeline, downloadable as JSON or CSV. The /verify page operates per-session.
→ Verify page
Sociedad-IAregime
AI-only company under Argentina's proposed regime (Sturzenegger announcement 28-abr-2026).
Equivalent in scope to a Wyoming DAO LLC or a Marshall Islands MIDAO foundation. Operates autonomously through software agents; signs contracts; cobra; pays taxes. The sociedad-IA's legal personhood is what ar-agents's infrastructure underwrites.
→ Political context → Manifiesto
Test vectorsspec
Deterministic JSON vectors any RFC-004 library implementation must produce byte-for-byte.
7 vectors at /test-vectors/rfc-004-v1.json with hex-exact HMAC expected values. Frozen per spec version so legislation referencing v1 has a stable target. Reference implementation passes all 7 (96 vitest tests total).
→ Vectors page → JSON file