# ar-agents

> Open-source toolkit and reference implementation for Argentine **sociedades-IA** — AI-only companies under Argentina's proposed regime (anuncio Sturzenegger 28-abr-2026). 17 npm packages, 168 tools, 8 hosted endpoints, 4 RFCs (001..004), conformance test vectors, public certifier. MIT + CC-BY-4.0, SLSA-provenanced. Every tool call lands in an HMAC-SHA256-signed audit log persisted to Vercel KV.

The toolkit covers 16 of the 17 operating pieces an Argentine business needs (identity, banking, factura electrónica, MP, ML, WhatsApp, BCRA, Boletín Oficial, IGJ, GDE/TAD). RFC-001 proposes a three-layer liability framework. RFC-004 normatively pins down the operational-log wire format with 7 frozen conformance vectors at `/test-vectors/rfc-004-v1.json`. The companion human-facing demo at `/play` is operable in 30 seconds with zero setup, and an external orchestrator can self-incorporate an AR sociedad-IA programmatically via `POST /api/auto-incorporate` (or the typed npm client `@ar-agents/incorporate`).

## Start here

- [Reference index](https://ar-agents.vercel.app/reference): every URL, endpoint, package, well-known well in one page. The fastest way to crawl the whole surface.
- [Live agent demo](https://ar-agents.vercel.app/play): 12-tool sociedad-IA agent. Streaming via Vercel AI Gateway. Zero setup.
- [Auto-incorporation API](https://ar-agents.vercel.app/api/auto-incorporate): one POST → generated source files + Vercel deploy URL + signed audit-log reference. Idempotent.
- [SDK docs](https://ar-agents.vercel.app/sdk): @ar-agents/incorporate, zero-dep TS client, ~4KB.
- [Architecture](https://ar-agents.vercel.app/architecture): 16 packages, Mermaid diagrams, the Edge-Runtime composition contract.
- [Cookbook](https://ar-agents.vercel.app/examples): 26 production patterns.
- [Data room](https://ar-agents.vercel.app/data-room): live npm + GitHub numbers, auto-refreshed every 6h.

## Governance

- [Playbook (en)](https://ar-agents.vercel.app/playbook) · [Playbook (es)](https://ar-agents.vercel.app/es/playbook): flagship narrative. The single doc that explains the toolkit, the regime, the operating model.
- [RFC-001](https://ar-agents.vercel.app/rfcs/001): three-layer liability framework (operator / model provider / library author). Includes the audit-log probative-value contract (§ 9).
- [RFC-002](https://ar-agents.vercel.app/rfcs/002): agent-discovery-by-default. /.well-known/agents.json convention.
- [RFC-003](https://ar-agents.vercel.app/rfcs/003): cross-jurisdictional audit-log reciprocity envelope.
- [RFC-004](https://ar-agents.vercel.app/rfcs/004): canonical operational-log wire format. The document legislation can cite.
- [RFC-005](https://ar-agents.vercel.app/rfcs/005): Ed25519 asymmetric upgrade path. **SHIPPED + VERIFIED LIVE** — production `/api/play` entries carry both `hmac` and `signature` fields. Live confirmation: 3/3 HMAC + 3/3 Ed25519 verified.
- [Test vectors](https://ar-agents.vercel.app/test-vectors): RFC-004 v1 (7 vectors) + RFC-005 v1 (3 vectors). Reference impl passes all 10 (107 vitest tests in 6 files, including 4 dual-sign regression tests).
- [Auditor's brief](https://ar-agents.vercel.app/auditor): 1-page Spanish-first regulator-facing summary. Print-friendly.
- [Legislative synthesis](https://ar-agents.vercel.app/legislacion): Spanish synthesis of all 5 RFCs with suggested cite-by-reference legislative text. English mirror at /en/legislation.
- [Registry of known implementations](https://ar-agents.vercel.app/registro): public list of sociedades-IA implementing the RFCs. Self-listed via PR. Live cert-badges per entry.
- [Compliance certifier](https://ar-agents.vercel.app/certifier): paste any URL, score 0-100 against RFC-002 + RFC-004 + RFC-005. Programmatic API at /api/certifier.
- [Glossary](https://ar-agents.vercel.app/glossary): 21 alphabetized term definitions across concepts/protocols/specs/tools.
- [Outreach templates](https://ar-agents.vercel.app/share): copy-paste social + email drafts for sharing ar-agents with regulators, journalists, ministry asesores.
- [Academic references](https://ar-agents.vercel.app/refs): BibTeX, APA, Chicago citations for the 4 RFCs + datasets + toolkit.
- [Timeline](https://ar-agents.vercel.app/timeline): visual chronology from the Sturzenegger 28-abr-2026 announcement onwards.
- [Architecture / audit-log deep-dive](https://ar-agents.vercel.app/architecture/audit-log): 11-section code-level breakdown.
- [Architecture / security model](https://ar-agents.vercel.app/architecture/security): code-level threat walkthrough (T1-T14).
- [Security threat model](https://ar-agents.vercel.app/security): 14 explicit threats, 14 explicit mitigations. STRIDE + OWASP LLM Top 10.
- [Verify any audit log](https://ar-agents.vercel.app/verify): paste a session id, get an independent server-side HMAC re-verification report.
- [Audit explorer](https://ar-agents.vercel.app/audit-explorer/demo-public-ar-001): forensic per-session view with governance bar, tool usage, latency quantiles, mini-timeline.
- [Operational status](https://ar-agents.vercel.app/status): live state of every subsystem (KV, HMAC, AI Gateway, ARCA, MP, WhatsApp, BCRA). Refreshed every 30s. Live RFC-002+004 self-cert badge.
- [Jurisdiction comparison](https://ar-agents.vercel.app/jurisdicciones): side-by-side of AR proposal vs Wyoming DAO LLC, Marshall Islands MIDAO, Estonia e-Residency, Singapore VCC + AI Verify, EU AI Act Art. 50. Honest delta of what each precedent has that ar-agents does not (yet).
- [Immutable citation generator](https://ar-agents.vercel.app/cite): pick an RFC + commit hash, get BibTeX / APA / Chicago citations anchored to GitHub commit. Programmatic API at GET /api/cite. For legislators citing the spec in articulado.
- [Government briefing](https://ar-agents.vercel.app/gobierno): operational 10-min briefing for ministry advisors. Distinct from /al-ministro (personal letter): this is the structured one-page-scroll a staffer forwards internally.
- [Cloud (commercial tier)](https://ar-agents.vercel.app/cloud): the open-core model. Self-host stays free forever; Studio/Government/Bespoke tiers cover managed hosting, SLA, AR data residency, key custody. Answers "how does this monetize if everything is open-source?".
- [Co-sign an RFC](https://ar-agents.vercel.app/co-firmar): open invitation to academic / juridical co-authors of the 5 RFCs. CC-BY-4.0, no commercial commitment, co-authorship cited formally via /cite.
- [Dashboard index](https://ar-agents.vercel.app/dashboard): per-session forensic model + link to public demo session /dashboard/demo-public-ar-001.
- [Feed](https://ar-agents.vercel.app/feed.xml): Atom feed of shipping rounds.

## Hosted HTTP API (call directly, no SDK required)

- `POST /api/auto-incorporate` — one-call sociedad-IA incorporation. JSON body. Returns config files + deploy URL + signed audit ref.
- `POST /api/play` — live agent loop. 12 mocked-but-realistic tools. Streaming SSE.
- `GET  /api/play/audit/{sessionId}` — full audit timeline read.
- `GET  /api/play/audit/{sessionId}?verify=1` — HMAC-verified audit log read.
- `GET  /api/play/audit/{sessionId}/csv` — RFC-4180 CSV export with UTF-8 BOM.
- `GET  /api/play/audit-stream/{sessionId}` — Server-Sent Events live stream.
- `POST /api/play/tamper-demo` — read-only forensic-proof (educational).
- `GET  /api/badge/{sessionId}` — 24px shields.io-style SVG verification badge for embeds.
- `GET  /api/cert-badge?url={baseUrl}` — shields.io-style live RFC-002+004 conformance badge for any URL.
- `GET  /api/discovery` — machine-readable inventory. `?format=openapi` returns OpenAPI 3.1 stub.
- `GET  /api/openapi` — full OpenAPI 3.1 schema for all public endpoints.
- `GET  /api/openapi.yaml` — YAML mirror of the above.
- `GET  /api/certifier?url={baseUrl}` — score any sociedad-IA's RFC-002/004/005 conformance 0-100 (~11 checks).
- `GET  /api/conformance-history?url={baseUrl}` — KV-backed time-series of cert scores. POST to append.
- `GET  /api/auto-monitor` — Vercel cron-driven daily poll of all /registro entries.
- `GET  /api/audit-summary/{sessionId}` — per-session aggregates (governance breakdown, latency quantiles, anomaly flags).
- `GET  /api/rfc-003-envelope?sessionId={id}&counterpart={url}` — generate the RFC-003 cross-jurisdictional envelope.

## Well-known endpoints (RFC-002 + RFC-004 § 5 + RFC-005 § 4)

- [/.well-known/agents.json](https://ar-agents.vercel.app/.well-known/agents.json) — discovery manifest with issuer.jurisdiction, rfcConformance, auditEndpoints.
- [/.well-known/sociedad-ia/verify-key?challenge=HEX](https://ar-agents.vercel.app/.well-known/sociedad-ia/verify-key?challenge=deadbeefdeadbeef) — RFC-004 § 5 challenge-response key-possession proof.
- [/.well-known/sociedad-ia/keys](https://ar-agents.vercel.app/.well-known/sociedad-ia/keys) — RFC-005 § 4 Ed25519 public-keys publication.

## Discovery (machine-readable, agent-crawlable)

- [/.well-known/ai-plugin.json](https://ar-agents.vercel.app/.well-known/ai-plugin.json) — OpenAI plugin spec.
- [/.well-known/agents.json](https://ar-agents.vercel.app/.well-known/agents.json) — agents.md convention. Lists endpoints, packages, governance primitives, per-agent operating instructions.
- [/.well-known/security.txt](https://ar-agents.vercel.app/.well-known/security.txt) — RFC 9116 disclosure policy.

## Press + outreach

- [Press kit](https://ar-agents.vercel.app/press-kit): one-pager + verifiable numbers + citable quotes (es).
- [vs alternatives](https://ar-agents.vercel.app/vs): comparison table with AfipSDK, handrolled, consultoría.

## Code

- [github.com/ar-agents/ar-agents](https://github.com/ar-agents/ar-agents): monorepo. 17 packages, 28 cookbook recipes, 5 demo apps, 1 starter template, 5 RFCs, 4 JSON schemas, 2 frozen test-vectors files, 103 vitest tests across 6 files. CITATION.cff at repo root.
- [npmjs.com/org/ar-agents](https://www.npmjs.com/org/ar-agents): all 17 published packages with SLSA v1 provenance.
- [Quarterly compliance workflow template](https://ar-agents.vercel.app/workflows/sociedad-ia-quarterly-compliance.yml): drop-in GitHub Actions workflow that generates a self-disclosure JSON every quarter, signed with your AUDIT_HMAC_SECRET, retained 5 years.

## Install

```
pnpm add @ar-agents/incorporate
# or for the full toolkit:
pnpm add @ar-agents/identity @ar-agents/banking @ar-agents/facturacion @ar-agents/mercadopago @ar-agents/whatsapp @ar-agents/gde-tad
```

## Contact

Nazareno Clemente · naza@helloastro.co · CUIT 20-41758101-5 · Buenos Aires, AR · [@cesargazzo](https://twitter.com/cesargazzo) is the Subsec TIC currently in office; outreach is welcome via the issues tracker or email.

## License

MIT. SLSA v1 npm provenance attestations on every package release.