Agent Receipts

Protokolle sagen dir, dass etwas passiert ist. Belege beweisen es.

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

Praxisbeispiel

Ich habe ModQuote entwickelt – ein Multi-Tenant-SaaS für Autowerkstätten. Während der Entwicklung habe ich Claude Code intensiv für die Prüfung und Korrektur der Codebasis genutzt.

Das Problem: Wenn etwas schiefging, hatte ich keine Möglichkeit zu beweisen, welchen Input Claude erhalten hat, was es geändert hat oder ob der Output dem entsprach, was erwartet wurde.

Mit Agent Receipts generiert jede Claude Code-Sitzung jetzt signierte Belege:

• Input-Hash beweist genau, welchen Code Claude gesehen hat

• Output-Hash beweist genau, was es produziert hat

• Einschränkungen (Constraints) erfassen, wenn Latenzspitzen auftreten oder Kosten das Budget überschreiten

• Ketten (Chains) zeigen die vollständige Sequenz einer mehrstufigen Prüfungssitzung

Wenn eine Korrektur nicht wie erwartet funktionierte, konnte ich den Beleg abrufen, die Signatur überprüfen und die genauen Input-/Output-Hashes sehen — kein Raten, kein "Claude muss das falsch verstanden haben".

Das ist der Unterschied zwischen Protokollen und Belegen. Protokolle sagen dir, dass etwas passiert ist. Belege beweisen es.

Schnellstart: MCP-Server

Füge den Agent Receipts MCP-Server zur Konfiguration deines KI-Tools hinzu und jede Aktion erhält automatisch einen kryptografischen Beleg.

Plattformunterstützung: macOS, Windows und Linux — erfordert Node.js 18+

Claude Desktop

Füge dies zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

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

Claude Code

Füge dies zu .mcp.json in deinem Projektstammverzeichnis hinzu:

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

Cursor

Füge dies zu .cursor/mcp.json in deinem Projektstammverzeichnis hinzu:

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

Schnellstart: 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

Schnellstart: 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

Funktionsweise

1. Agent führt eine Aktion aus — API-Aufruf, Code-Generierung, Datenabfrage

2. Input/Output werden SHA-256 gehasht — Rohdaten verlassen niemals deinen Rechner

3. Beleg wird erstellt — Aktion, Hashes, Zeitstempel, Agent-ID, Metadaten

4. Beleg wird Ed25519-signiert — mit einem lokal generierten privaten Schlüssel

5. Jeder kann verifizieren — teile deinen öffentlichen Schlüssel; Empfänger verifizieren unabhängig

MCP-Tools Referenz

Der MCP-Server stellt 14 Tools bereit, die KI-Agenten direkt aufrufen können:

SDK API Referenz

new AgentReceipts(config?)

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

ar.track(params) — Verfolgt eine abgeschlossene Aktion

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) — Startet einen ausstehenden Beleg

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

ar.complete(receiptId, params) — Vervollständigt einen ausstehenden Beleg

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

ar.verify(receiptId) — Überprüft eine Belegsignatur

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

ar.get(receiptId) — Ruft einen Beleg per ID ab

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

ar.list(filter?) — Listet Belege auf

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() — Ruft den öffentlichen Signaturschlüssel ab

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

ar.track() mit Einschränkungen (Constraints)

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) — Ruft Bewertungen ab

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

ar.cleanup() — Löscht abgelaufene Belege

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

ar.generateInvoice(params) — Generiert Rechnung aus Belegen

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
})

CLI Referenz

Belegformat

{
  "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>"
}

Input und Output werden clientseitig mit SHA-256 gehasht. Rohdaten verlassen niemals deine Umgebung. Nur Hashes werden im Beleg gespeichert.

Verifizierung

Teile deinen öffentlichen Schlüssel mit jedem, der deine Belege verifizieren muss:

# 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>

Die Verifizierung berechnet die Ed25519-Signatur über die deterministischen Felder des Belegs neu und bestätigt, dass sie mit der gespeicherten Signatur übereinstimmt. Keine Netzwerkanfragen — vollständig offline.

Konfiguration

Speicherung

Alle Daten werden lokal im Datenverzeichnis gespeichert:

~/.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

Seit v0.2.7 werden Belege in SQLite mit indizierten Abfragen für schnelles Filtern und Paginierung gespeichert. Bestehende JSON-Belegdateien werden beim ersten Start automatisch migriert.

Architektur

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

• schema — Zod-Schemas, TypeScript-Typen, JSON-Schema für das Action Receipt Protocol

• crypto — Ed25519-Schlüsselgenerierung, Signierung, Verifizierung, kanonische Serialisierung

• mcp-server — MCP-Protokollserver mit Beleg-Engine, Speicherung und Schlüsselverwaltung

• sdk — High-Level Node.js SDK, das die Engine umschließt

• cli — Befehlszeilen-Tool zum Inspizieren, Verifizieren und Verwalten von Belegen

• dashboard — Mission Control Web-UI zum Visualisieren und Verwalten von Belegen

Dashboard (Mission Control)

Visualisiere jeden Beleg, jede Kette, jeden Agenten, jede Einschränkung und jede Bewertung in deinem System.

npx @agent-receipts/dashboard

Öffnet Mission Control unter http://localhost:3274 — visualisiere, verifiziere und verwalte alle Belege.

Funktionen: Echtzeit-Beleg-Feed, Kettenvisualisierung, Überwachung der Einschränkungs-Integrität, Bewertungs-Scores, Signaturverifizierung, Rechnungserstellung, Dark Mode, globale Suche.

13 Seiten: Übersicht, Belege, Belegdetails, Ketten, Kettendetails, Agenten, Agentendetails, Einschränkungen, Bewertungen, Rechnungen, Verifizieren, Einstellungen, Funktionsweise.

Beispiele

Pakete

Roadmap

• [x] Lokal-zuerst Belegspeicherung (SQLite mit indizierten Abfragen)

• [x] Ed25519-Signierung und Verifizierung

• [x] MCP-Server mit 14 Tools

• [x] Node.js SDK

• [x] CLI mit vollständigem Befehlssatz

• [x] Einschränkungs-Verifizierung (6 integrierte Typen)

• [x] KI-Bewertung mit rubrikbasierter Evaluierung

• [x] Output-Schema-Validierung (JSON-Schema)

• [x] Beleg-TTL und Bereinigung

• [x] Rechnungserstellung (JSON, CSV, Markdown, HTML)

• [x] Mission Control Dashboard (13 Seiten, Dark Mode, Suche)

• [x] Dashboard npm-Paket — npx @agent-receipts/dashboard

• [x] Live-Demo unter agent-receipts-web.vercel.app

• [ ] Beleg-Verankerung an Blockchain-/Zeitstempel-Dienste

• [ ] Multi-Agenten-Beleg-Sharing-Protokoll

• [ ] Beleg-Komprimierung und Archivierung

• [ ] Gehostete Ebene mit Cloud-Datenbank

Entwicklung

pnpm install
pnpm build
pnpm test
pnpm dev

Lizenz

MIT — siehe LICENSE