ar-agents

Mercado Pago Agent Toolkit. Built on Vercel.

@ar-agents/mercadopago is a Mercado Pago Agent Toolkit for the Vercel AI SDK 6 Experimental_Agent. 89 typed tools across the agent-relevant Mercado Pago API surface:

Payments · Subscriptions · Checkout Pro · Marketplace OAuth · Order Management · Customers · Cards · Cuotas · QR · 3DS · Point devices · Stores+POS · Account/Balance/Settlements · Webhooks · Disputes · Lookups · Bank Accounts

Edge Runtime. Vercel KV adapters for state, OAuth, idempotency, and audit. OpenTelemetry instrumentation. Deterministic idempotency by default. Programmatic HITL on irreversible operations.

pnpm add @ar-agents/mercadopago ai zod

Deploys apps/mp-hello, a runnable agent on Vercel with Edge Runtime API routes, MP webhook handler, and Upstash-backed subscription state. Around 2 minutes from click to live.

import { Experimental_Agent as Agent, stepCountIs } from "ai";
import {
  MercadoPagoClient,
  mercadoPagoTools,
  InMemoryStateAdapter,
} from "@ar-agents/mercadopago";

const mp = new MercadoPagoClient({
  accessToken: process.env.MP_ACCESS_TOKEN!, // TEST- for sandbox, APP_USR- for prod
});

const agent = new Agent({
  model: "anthropic/claude-sonnet-4-6",
  tools: mercadoPagoTools(mp, {
    state: new InMemoryStateAdapter(), // swap for VercelKVStateAdapter in prod
    backUrl: "https://yoursite.com/subscription/done",
  }),
  stopWhen: stepCountIs(8),
});

const { text } = await agent.generate({
  prompt: "Creá una subscription mensual de $1000 ARS para customer@example.com.",
});

Full reference, cookbook (9 recipes including OpenTelemetry wiring), and migration guide vs the official mercadopago SDK live in packages/mercadopago/.

How it compares

Both official SDKs are excellent at what they do (generic REST clients for their respective APIs). @ar-agents/mercadopago is opinionated for the agent-operating-an-Argentine-business case, and composes with mercadopago under the hood when needed. See MIGRATION.md.

Architecture

flowchart LR
  subgraph user_app["Your Next.js / Edge / Workers app"]
    direction TB
    agent["Vercel AI SDK 6<br/>Experimental_Agent"]
  end

  subgraph ar_agents["@ar-agents/* (this monorepo)"]
    direction TB
    mp["mercadopago<br/>89 tools"]
    id["identity<br/>CUIT + AFIP padrón"]
    fac["facturacion<br/>factura electrónica"]
    wa["whatsapp<br/>Business Cloud"]
    bk["banking<br/>CBU + BCRA"]
    sh["shipping<br/>Andreani / OCA / Correo"]
    att["identity-attest<br/>HMAC-signed orchestrator"]
    mcp["mcp<br/>bundles all 7 over MCP"]
  end

  subgraph adapters["Pluggable state (subpath)"]
    direction TB
    kv["@ar-agents/mercadopago/vercel-kv<br/>state · OAuth · idempotency · audit · ratelimit"]
    otel["@ar-agents/mercadopago/otel<br/>OpenTelemetry instrumentation"]
  end

  subgraph external["External APIs"]
    direction TB
    mpapi["api.mercadopago.com"]
    afip["AFIP/ARCA WSAA + WSFE"]
    meta["Meta WhatsApp Cloud API"]
    bcra["BCRA Central de Deudores"]
    carriers["Andreani · OCA · Correo Argentino"]
  end

  agent -- tool calls --> mp & id & fac & wa & bk & sh & att
  mp -.subpath.-> kv & otel
  mp --> mpapi
  id --> afip
  fac --> afip
  wa --> meta
  bk --> bcra
  sh --> carriers
  mcp -.bundles.-> mp & id & fac & wa & bk & sh & att

The agent picks tools from natural-language prompts. Each package is an independent npm release; there are no cross-package runtime dependencies beyond the optional adapter subpaths, so you only ship the surface you use.

Other AR primitives in this monorepo

Same approach, applied to the rest of the stack an Argentine business needs:

Each package ships a README.md for humans and an AGENTS.md for LLMs reading the docs at runtime, following the agents.md format (tool-selection rules, result schemas, error patterns).

Live demos

Develop

pnpm install
pnpm test         # 719 tests across 8 packages
pnpm typecheck
pnpm build
pnpm dev          # mp-hello on http://localhost:3013

Requires Node 20+ and pnpm 10+. CI runs build, typecheck, coverage, manifest-drift, publint, arethetypeswrong, and size-limit on every push.

Repo layout

ar-agents/
├── apps/
│   ├── landing/                 # ar-agents.vercel.app
│   ├── cuit-hello/              # ar-agents-cuit-hello.vercel.app (port 3014)
│   ├── whatsapp-hello/          # ar-agents-whatsapp-hello.vercel.app
│   └── mp-hello/                # dev-only (port 3013)
├── packages/
│   ├── mercadopago/             # 89 tools: subscriptions, payments, OAuth, QR, 3DS, point, ...
│   ├── identity/                # CUIT validate + ARCA padrón
│   ├── identity-attest/         # verification orchestrator
│   ├── whatsapp/                # WhatsApp Cloud
│   ├── facturacion/             # AFIP factura electrónica
│   ├── banking/                 # CBU/CVU + BCRA
│   ├── shipping/                # Andreani / OCA / Correo
│   └── mcp/                     # MCP server wrapping all
├── .github/workflows/           # ci.yml, release.yml
├── package.json                 # workspace root
└── pnpm-workspace.yaml

Stability

All packages are pre-1.0. Public API may evolve in 0.x; we follow semver, so minor bumps may include breaking changes and patch bumps never do. Pinning a minor in production is safe.

License

MIT. Built by Nazareno Clemente.