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

/test-vectors · conformance · index

Conformance test vectors.

Deterministic JSON files any library author can fetch + run against their implementation. Versioned + frozen per spec revision so legislation referencing a vector set has a stable target. Each vector is reproducible: given the same inputs, every conformant implementation must produce the same outputs byte-for-byte.

RFC-004 v1 · sociedad-IA operational-log

Spec: /rfcs/004 · Status: draft · Published: 2026-05-11 · Vectors: 7

Download

/test-vectors/rfc-004-v1.json

Application/json · CC-BY-4.0 · frozen at v1 publication

Conformance vectors for RFC-004 v1 (draft). A library claiming RFC-004 v1 conformance MUST produce these exact outputs given these exact inputs and the shared secret below. The HMAC values are hex-encoded SHA-256 outputs prefixed with 'sha256:'. Vectors are deterministic + reproducible — re-run the reference impl against this file and every assertion holds. License: CC-BY-4.0.

Vectors index

vector-1-canonical-keys-sorted — canonical-JSON serializes objects with keys sorted lexicographically at every level. JSON.stringify on its own is NOT canonical in JavaScript — key order follows insertion order, which differs across runtimes + reconstructions.
vector-2-canonical-nested — canonical-JSON recurses through nested objects + arrays. Arrays preserve order (positional); objects inside arrays are still key-sorted.
vector-3-hmac-base-entry — HMAC-SHA256 of the canonical-JSON of an entry, with the hmac field stripped before signing. Verify must operate on the same field set.
vector-4-mutated-output-differs — Mutating any field (here: output.pong from 1 to 2) produces a different HMAC. This is the integrity guarantee of the chain.
vector-5-sign-is-idempotent — Re-signing the same entry with the same secret produces the same HMAC. Determinism check.
vector-6-nested-input-base — Entry with deeply-nested input. Used to validate that recursive canonicalization works inside arrays of objects.
vector-6-mutated-nested — Same entry as vector-6 but with batch[1].amount changed from 200 to 201. The deeply-nested mutation MUST produce a different HMAC.

Reference implementation

The TypeScript reference impl + its conformance proof live in the same repo:

Library: apps/landing/src/lib/audit.ts
Conformance tests: apps/landing/test/rfc-004-vectors.test.ts
Repo: github.com/ar-agents/ar-agents

How to claim conformance

Fetch the JSON file: curl -sL https://ar-agents.vercel.app/test-vectors/rfc-004-v1.json
Run every vector through your library. Compare expectedCanonical + expectedHmac byte-for-byte.
All 7 vectors must match exactly. mustDifferFrom + mustEqual cross-checks must also hold.
Open a PR to github.com/ar-agents/ar-agents adding your library to the conformance registry with a link to your passing test suite.

Conformance registry

Library	Language	Version	RFC-004 v1
`apps/landing/src/lib/audit`	TypeScript	(reference)	✓ passing (7/7)
(your library here)	—	—	open a PR

RFC-005 v1 · Ed25519 asymmetric extension

Spec: /rfcs/005 · Status: draft · Published: 2026-05-11 · Vectors: 3

Download

/test-vectors/rfc-005-v1.json

Application/json · CC-BY-4.0 · includes a demo Ed25519 keypair (DO NOT use in prod)

3 deterministic vectors with base64url-exact Ed25519 signatures. Cross-validated against Node's native crypto.sign(null, msg, privateKey). Conformance proof at apps/landing/test/rfc-005-vectors.test.ts (7 vitest tests, all passing).

The same keypair is published in production at /.well-known/sociedad-ia/keys (public key only). RFC-005 § 4 specifies the publication format.

Versioning policy

Spec version = vectors version. When RFC-004 publishes v2, a parallel rfc-004-v2.json appears. v1 stays frozen so legislation citing v1 remains stable.
v1 finalization checkpoint. Vectors marked draft may change one more time before v1 final. After that, the hex values are locked.
License. CC-BY-4.0 on the vectors + MIT on the reference impl. Use anywhere; attribute the spec.