Skip to content

architecture · 2026-05

Architecture.

16 packages, 168 tools, one Edge-Runtime composition contract.

The toolkit is not a monolith. Each package solves one external dependency (AFIP, BCRA, MP, Meta, Andreani, etc.) and ships independently to npm. They compose at the agent-loop level — there are no cross-package runtime dependencies beyond optional adapter subpaths.

That matters because an Argentine business-as-agent isn't one thing — it's the simultaneous operation of 5–7 external systems (taxpayer registry, payment processor, banking, invoicing, government identity, shipping carrier, public records). The toolkit is shaped around that fact.

The 16 packages

Rendering diagram…
The agent talks to packages; packages talk to external systems. Bridges (dashed) compose the others.

Identity

@ar-agents/identityv0.6.0
2 tools
Algorithm-only validate_cuit always works. lookup_cuit_afip needs WSAA cert. · AFIP/ARCA WSAA + ws_sr_constancia_inscripcion
@ar-agents/identity-attestv0.4.2
5 tools
HMAC-signed attestations with trustLevel 0.0–1.0. · WhatsApp / email / Auth0 / Magic.link / MP Identity
@ar-agents/mi-argentinav0.1.0
4 tools
PKCE + RS256 JWT verify + JWKS caching. Edge-safe. · Mi Argentina OIDC (gov AR identity)
@ar-agents/firma-digitalv0.1.0
4 tools
PKCS#7/CMS verify with AR trust-anchor heuristic + fingerprint pinning. · AC-Raíz / ONTI cert authorities

Payments + banking

@ar-agents/mercadopagov0.17.2
89 tools
Subscriptions, Payments, Checkout Pro, Marketplace OAuth, Cuotas, QR, 3DS, Point. · api.mercadopago.com
@ar-agents/mercadolibrev0.1.0
15 tools
First faithful TS SDK since the official one was archived in 2022. Items + catalog + questions/messages + claims + shipments + reputation + promotions + webhooks with /missed_feeds replay. · api.mercadolibre.com
@ar-agents/bankingv0.2.0
11 tools
CBU/CVU validators (algorithm), USD oficial / CER / UVA / reservas / inflación. · BCRA Central de Deudores + BCRA Principales Variables

Fiscal + corporate

@ar-agents/gde-tadv0.1.0
4 tools
DEC inbox polling + Mis Trámites + IGJ pre-flight validator. The 4th pieza for sociedades-IA — RFC-001 § 3.4. · TAD / GDE / Domicilio Electrónico
@ar-agents/facturacionv0.1.2
10 tools
Factura A/B/C, NC/ND, FCE MiPyMEs. Pre-flight validator. · AFIP/ARCA WSFE
@ar-agents/igjv0.1.0
6 tools
Inspección General de Justicia — corporate registry lookups. · datos.jus.gob.ar (open data)
@ar-agents/boletin-oficialv0.1.0
6 tools
Search + subscribe by CUIT / organismo / keyword. · boletinoficial.gob.ar

Communications

@ar-agents/whatsappv0.4.0
6 tools
Webhook + HMAC verify. AR phone normalizer. scopedTo mode. · Meta WhatsApp Business Cloud API

Logistics

@ar-agents/shippingv0.1.1
6 tools
Multi-carrier compare. Provincia + CPA helpers. · Andreani / OCA / Correo Argentino

Infrastructure / bridges

@ar-agents/agentic-commerce-bridgev3.0.0
infra
ACP facilitator. Auto-issues Factura A/B/C/E on payment. /.well-known/acp.json discovery. · ACP spec + Mercado Pago + facturación
@ar-agents/ap2v0.2.0
infra
Mandate verification + signing. ES256, JWS canonical claims. · Google AP2 spec
@ar-agents/mcpv0.6.2
infra
Bundles all 7 tool packages over Model Context Protocol. · MCP host (Claude Desktop / Cursor / Continue / Cline)

Composition flow

How a single agent.generate() call traverses the stack when an Argentine SaaS bills a B2B customer. Sequence diagram below — each arrow is a real tool invocation or HTTP round-trip. The audit log records every step with HMAC-signed timestamps; what the diagram hides is that all of those arrows return through AuditLogger.wrap() on the way back.

Rendering diagram…
One prompt → 8 tool calls across 6 packages → CAE issued, PDF delivered. Compose without coupling.

The Edge-Runtime contract

Every package in this list runs on Edge Runtime (Vercel Edge, Cloudflare Workers, Deno) without code changes. The contract:

1. Web Crypto only. No node:crypto in any production code path. HMAC, signature verification, idempotency-key generation all use crypto.subtle.

2. fetch-based HTTP. No got, axios, or node:http. The toolkit ships its own retry + circuit-breaker + deadline-propagation layer on top of the runtime's native fetch.

3. AbortSignal everywhere. Every long-running tool accepts a parent AbortSignal and propagates cancellation. The runtime kills hung tool calls cleanly when the request times out.

4. Pluggable state via subpath. InMemoryStateAdapter for tests + VercelKVStateAdapter for prod. Same interface; users pick where state lives.

Composition example: 5-package agent

The cookbook ships recipe 10 — one agent loop wiring identity + identity-attest + mercadopago + facturacion + whatsapp. The flagship demo of the composition contract.

Full cookbook (17 production patterns): packages/mercadopago/cookbook.

Trust, audit, governance

npm provenance attestations (SLSA v1): every published tarball is cryptographically tied to the GitHub commit it was built from. npm view @ar-agents/mercadopago dist.attestations returns the Sigstore transparency-log entry.

OpenSSF Scorecard: weekly automated audit of 18 supply-chain practices. Score visible at scorecard.dev.

Programmatic HITL on irreversible ops: refunds, cancellations, deletions, marketplace token revokes — all 8 gated behind a requireConfirmationcallback the host implements. Tool functions literally don't execute until your callback returns true.

Audit log adapter: every tool call (input + output + duration + status) gets logged to a pluggable sink (in-memory, Vercel KV, your own). HMAC timestamps make the log forensically sound — see RFC-001 § 9 for the liability framework.