The agent-economy entry point.

npm v0.2.0MITSLSA v1 provenance~4 KB · zero depsNode 20+ · Edge · CF Workers · Deno · browsers
@ar-agents/incorporate is the canonical npm surface for an external orchestrator (USA-LLC agent, ChatGPT extension, Claude tool, custom pipeline) to programmatically self-incorporate an Argentine sociedad-IA. The package is a thin fetch wrapper — no SDK gymnastics, no runtime adapters. The companion human-facing UI is at /incorporar; same backend, same generated output.

Install

pnpm add @ar-agents/incorporate
# or
npm  install @ar-agents/incorporate
yarn add @ar-agents/incorporate
bun  add @ar-agents/incorporate

Quickstart

One async call returns the four generated source files, the Vercel one-click deploy URL, the env-var manifest, the legal+operational checklist, and a signed audit-log reference:

import { incorporate } from "@ar-agents/incorporate";

const result = await incorporate({
  denominacion: "ACME-AI SAS",
  tipo: "SOCIEDAD-IA",
  capitalSocial: 1,
  objeto:
    "Operación de servicios digitales y desarrollo de software propio para clientes argentinos.",
});

if (!result.ok) {
  for (const f of result.validation.findings) {
    console.error(`[${f.severity}] ${f.field}: ${f.message}`);
  }
  process.exit(1);
}

console.log("Slug:        ", result.sociedad.slug);
console.log("Deploy URL:  ", result.deploy.oneClickUrl);
console.log("Audit log:   ", result.audit.dashboardUrl);
console.log("HMAC:        ", result.audit.entry.hmac);

// Persist the four generated files. `config` is { path: contents }.
import { writeFile, mkdir } from "node:fs/promises";
await mkdir("./out/lib", { recursive: true });
await Promise.all(
  Object.entries(result.config).map(([path, content]) =>
    writeFile(`./out/${path}`, content),
  ),
);

The shape of the result

Success returns:

• sociedad: denominacion, tipo, capitalSocial, slug
• config: object with package.json, lib/agent.ts, .env.example, README.md as string values
• envVars: array of { name, description } for the host's secrets manager
• checklist: 8-step ARCA cert / MP token / Meta verify / IGJ inscription roadmap
• deploy.oneClickUrl: pre-filled Vercel clone URL pointing at apps/sociedad-ia-starter
• audit: { sessionId, backend, entry, url, verifyUrl, dashboardUrl } — share dashboardUrl for a forensic timeline page; query verifyUrl for a re-verification report

Validation failure (HTTP 422) returns: { ok: false, validation: { findings: [...] }, rfc001 } — handled as a normal outcome the agent fixes and retries.

Multi-step orchestration

Pass the same sessionId across multiple incorporations + downstream /api/play tool calls to chain them under a single forensic timeline:

// Pass the same sessionId across multiple calls to chain them under
// a single forensic timeline.
const sessionId = crypto.randomUUID();

const r1 = await incorporate({ /* ... */ , sessionId });
// later: more incorporations or /api/play tool calls under the same id

const audit = await fetchAudit(sessionId, { verify: true });
// audit.entries → all events in order
// audit.verification.tampered → 0 if log is clean

Errors + validation

The thrown vs. returned distinction: incorporate() returns validation failures as a result; incorporateOrThrow() raises IncorporateValidationError instead. Network and unexpected HTTP errors raise IncorporateError in either case.

import {
  incorporate,
  IncorporateError,
  IncorporateValidationError,
} from "@ar-agents/incorporate";

try {
  // Throws IncorporateValidationError on 422 instead of returning a result.
  const result = await incorporateOrThrow({ /* ... */ });
  // ...
} catch (err) {
  if (err instanceof IncorporateValidationError) {
    // Pre-flight rules failed. Findings are an array of { code, severity, field, message }.
    for (const f of err.findings) {
      console.error(f.code, f.field, f.message);
    }
  } else if (err instanceof IncorporateError) {
    // Network / unexpected HTTP. err.status + err.response are populated.
    console.error("HTTP", err.status, err.response);
  } else {
    throw err;
  }
}

cURL equivalent

For pipelines that don't want a TypeScript dep, the underlying endpoint is callable directly:

curl -X POST https://ar-agents.vercel.app/api/auto-incorporate \
  -H "content-type: application/json" \
  -d '{
    "denominacion": "ACME-AI SAS",
    "tipo": "SOCIEDAD-IA",
    "capitalSocial": 1,
    "objeto": "Operación de servicios digitales..."
  }'

Audit log + verification badge

Every incorporate() call lands a signed entry in the session's audit log. Embed the verification badge in your README to show your forensic-clean status to anyone visiting:

![ar-agents audit](https://ar-agents.vercel.app/api/badge/{sessionId})

Color + label updates live based on the audit log's verification state (verified · 5/5 / tampered · 1 / no-hmac / no entries). See the live forensic timeline at /dashboard/{sessionId} and the independent re-verification UI at /verify.

Cookbook

Recipe 18 in the cookbook is an end-to-end USA-LLC orchestrator that uses @ar-agents/incorporate to spin up an AR sociedad-IA, materialize the generated files, log the incorporation event, and verify the audit log before proceeding — RFC-001 § 7 + § 9.2 in 100 lines:

packages/mercadopago/cookbook/18-usa-llc-self-incorporates-ar.ts

API reference

• incorporate(input, options?) — POST. Returns success or validation-failure envelope.
• incorporateOrThrow(input, options?) — same as above but throws IncorporateValidationError on 422.
• describe(options?) — fetches the endpoint's self-description for capability discovery.
• fetchAudit(sessionId, options?) — fetches the session's audit log; pass { verify: true } for HMAC verification report.

Full input/output types ship as .d.ts — see packages/incorporate/src/index.ts.

License + provenance

MIT. Every release ships SLSA v1 npm provenance attestations tying the published tarball to a specific GitHub commit + GitHub Actions runner. Verify with npm view @ar-agents/incorporate dist.attestations.