Agent Receipts

Los registros te dicen que algo sucedió. Los recibos lo prueban.

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Ejemplo en el mundo real

Construí ModQuote, un SaaS multiinquilino para talleres automotrices. Durante el desarrollo, utilicé Claude Code extensivamente para auditar y corregir la base de código.

El problema: cuando algo salía mal, no tenía forma de probar qué entrada recibió Claude, qué cambió o si la salida coincidía con lo esperado.

Con Agent Receipts, cada sesión de Claude Code ahora genera recibos firmados:

• Hash de entrada prueba exactamente qué código vio Claude

• Hash de salida prueba exactamente qué produjo

• Restricciones detectan cuando la latencia aumenta o los costos exceden el presupuesto

• Cadenas muestran la secuencia completa de una sesión de auditoría de varios pasos

Cuando una corrección no funcionaba como se esperaba, podía obtener el recibo, verificar la firma y ver los hashes exactos de entrada/salida; sin suposiciones, sin "Claude debe haber entendido mal".

Esa es la diferencia entre registros y recibos. Los registros te dicen que algo sucedió. Los recibos lo prueban.

Inicio rápido: Servidor MCP

Agrega el servidor MCP de Agent Receipts a la configuración de tu herramienta de IA y cada acción obtendrá un recibo criptográfico automáticamente.

Soporte de plataforma: macOS, Windows y Linux — requiere Node.js 18+

Claude Desktop

Agrégalo a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Claude Code

Agrégalo a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Cursor

Agrégalo a .cursor/mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Inicio rápido: SDK

npm install @agent-receipts/sdk

import { AgentReceipts } from '@agent-receipts/sdk'

const ar = new AgentReceipts()

const receipt = await ar.track({
  action: 'generate_report',
  input: { query: 'Q4 revenue' },
  output: { total: 142000 },
})

console.log(receipt.receipt_id)  // rcpt_8f3k2j4n...
console.log(receipt.signature)   // ed25519 signature

Inicio rápido: CLI

npx @agent-receipts/cli init          # Generate signing keys
npx @agent-receipts/cli keys          # Show public key
npx @agent-receipts/cli list          # List all receipts
npx @agent-receipts/cli verify <id>   # Verify a receipt signature

Cómo funciona

1. El agente realiza una acción — llamada a API, generación de código, búsqueda de datos

2. La entrada/salida se hashea con SHA-256 — los datos sin procesar nunca salen de tu máquina

3. Se crea el recibo — acción, hashes, marca de tiempo, ID del agente, metadatos

4. El recibo se firma con Ed25519 — con una clave privada generada localmente

5. Cualquiera puede verificar — comparte tu clave pública; los destinatarios verifican de forma independiente

Referencia de herramientas MCP

El servidor MCP expone 14 herramientas que los agentes de IA pueden llamar directamente:

Referencia de API del SDK

new AgentReceipts(config?)

const ar = new AgentReceipts({
  dataDir: '~/.agent-receipts',  // optional, defaults to ~/.agent-receipts
})

ar.track(params) — Rastrea una acción completada

const receipt = await ar.track({
  action: 'analyze_data',
  input: { dataset: 'sales_2024' },
  output: { summary: 'Revenue up 12%' },
  agent_id: 'analyst-v2',
  chain_id: 'chain_abc',              // optional, auto-generated if omitted
  parent_receipt_id: 'rcpt_prev',     // optional, links to parent receipt
})

ar.start(params) — Inicia un recibo pendiente

const receipt = await ar.start({
  action: 'long_running_task',
  input: { job_id: '12345' },
})

ar.complete(receiptId, params) — Completa un recibo pendiente

const completed = await ar.complete(receipt.receipt_id, {
  output: { result: 'done' },
  status: 'completed',
})

ar.verify(receiptId) — Verifica la firma de un recibo

const { verified, receipt } = await ar.verify('rcpt_8f3k2j4n')
// verified: true | false

ar.get(receiptId) — Obtiene un recibo por ID

const receipt = await ar.get('rcpt_8f3k2j4n')

ar.list(filter?) — Lista recibos

const result = await ar.list({ agent_id: 'my-agent', status: 'completed' })
// result.data: ActionReceipt[]
// result.pagination: { page, limit, total, total_pages, has_next, has_prev }

ar.getPublicKey() — Obtiene la clave pública de firma

const publicKey = await ar.getPublicKey()
// 64-char hex string (Ed25519 public key)

ar.track() con restricciones

const receipt = await ar.track({
  action: 'generate_summary',
  input: { document_id: 'doc-q4-2024' },
  output: { summary: 'Revenue grew 12% YoY...' },
  latency_ms: 1200,
  cost_usd: 0.005,
  constraints: [
    { type: 'max_latency_ms', value: 5000 },
    { type: 'max_cost_usd', value: 0.01 },
    { type: 'min_confidence', value: 0.8 },
  ],
})
// receipt.constraint_result.passed → true/false

ar.getJudgments(receiptId) — Obtiene juicios

const judgments = await ar.getJudgments('rcpt_8f3k2j4n')

ar.cleanup() — Elimina recibos expirados

const { deleted, remaining } = await ar.cleanup()

ar.generateInvoice(params) — Genera factura a partir de recibos

const invoice = await ar.generateInvoice({
  from: '2026-01-01',
  to: '2026-01-31',
  agent_id: 'my-agent',       // optional filter
  group_by: 'agent',          // optional: agent | action | day
})

Referencia de CLI

Formato de recibo

{
  "receipt_id": "rcpt_8f3k2j4n",
  "chain_id": "chain_x9f2k",
  "parent_receipt_id": null,
  "receipt_type": "action",
  "agent_id": "my-agent",
  "org_id": "my-org",
  "action": "generate_report",
  "status": "completed",
  "input_hash": "sha256:abc123...",
  "output_hash": "sha256:def456...",
  "output_summary": "Generated Q4 report",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-02-07T14:32:01.442Z",
  "completed_at": "2026-02-07T14:32:02.100Z",
  "latency_ms": 658,
  "cost_usd": 0.003,
  "signature": "ed25519:<hex>"
}

La entrada y la salida se hashean en el lado del cliente con SHA-256. Los datos sin procesar nunca salen de tu entorno. Solo los hashes se almacenan en el recibo.

Verificación

Comparte tu clave pública con cualquiera que necesite verificar tus recibos:

# Export your public key
npx @agent-receipts/cli keys --export

# Verify a receipt with an external public key
npx @agent-receipts/cli verify receipt.json --key <public-key-hex>

La verificación recalcula la firma Ed25519 sobre los campos deterministas del recibo y confirma que coincide con la firma almacenada. Sin solicitudes de red: totalmente fuera de línea.

Configuración

Almacenamiento

Todos los datos se almacenan localmente en el directorio de datos:

~/.agent-receipts/
├── keys/
│   ├── private.key          # Ed25519 private key (mode 0600)
│   └── public.key           # Ed25519 public key
├── receipts/
│   └── *.json               # Legacy JSON files (auto-migrated)
├── receipts.db              # SQLite database (primary storage)
└── config.json              # Agent and org configuration

A partir de la v0.2.7, los recibos se almacenan en SQLite con consultas indexadas para un filtrado y paginación rápidos. Los archivos de recibos JSON existentes se migran automáticamente en el primer inicio.

Arquitectura

┌─────────────────────────────────────────────┐
│                  CLI                         │
│           @agent-receipts/cli                 │
├─────────────────────────────────────────────┤
│           SDK            │   MCP Server      │
│   @agent-receipts/sdk     │ @agent-receipts/   │
│                          │   mcp-server      │
├──────────────────────────┴──────────────────┤
│              Crypto + Schema                 │
│   @agent-receipts/crypto  @agent-receipts/     │
│                            schema            │
└─────────────────────────────────────────────┘

• schema — Esquemas Zod, tipos TypeScript, JSON Schema para el Protocolo de Recibos de Acción

• crypto — Generación de claves Ed25519, firma, verificación, serialización canónica

• mcp-server — Servidor de protocolo MCP con motor de recibos, almacenamiento y gestión de claves

• sdk — SDK de Node.js de alto nivel que envuelve el motor

• cli — Herramienta de línea de comandos para inspeccionar, verificar y gestionar recibos

• dashboard — Interfaz web Mission Control para visualizar y gestionar recibos

Panel de control (Mission Control)

Visualiza cada recibo, cadena, agente, restricción y juicio en tu sistema.

npx @agent-receipts/dashboard

Abre Mission Control en http://localhost:3274: visualiza, verifica y gestiona todos los recibos.

Características: feed de recibos en tiempo real, visualización de cadenas, monitoreo de salud de restricciones, puntajes de juicio, verificación de firmas, generación de facturas, modo oscuro, búsqueda global.

13 páginas: Resumen, Recibos, Detalle de recibo, Cadenas, Detalle de cadena, Agentes, Detalle de agente, Restricciones, Juicios, Facturas, Verificar, Configuración, Cómo funciona.

Ejemplos

Paquetes

Hoja de ruta

• [x] Almacenamiento de recibos local-first (SQLite con consultas indexadas)

• [x] Firma y verificación Ed25519

• [x] Servidor MCP con 14 herramientas

• [x] SDK de Node.js

• [x] CLI con conjunto completo de comandos

• [x] Verificación de restricciones (6 tipos integrados)

• [x] IA Judge con evaluación basada en rúbricas

• [x] Validación de esquema de salida (JSON Schema)

• [x] TTL de recibo y limpieza

• [x] Generación de facturas (JSON, CSV, Markdown, HTML)

• [x] Panel de control Mission Control (13 páginas, modo oscuro, búsqueda)

• [x] Paquete npm del panel de control — npx @agent-receipts/dashboard

• [x] Demo en vivo en agent-receipts-web.vercel.app

• [ ] Anclaje de recibos a servicios de blockchain/timestamping

• [ ] Protocolo de intercambio de recibos multi-agente

• [ ] Compresión y archivo de recibos

• [ ] Nivel alojado con base de datos en la nube

Desarrollo

pnpm install
pnpm build
pnpm test
pnpm dev

Licencia

MIT — ver LICENSE