Skip to content

About

Lightweight observability for AI tool and model calls: latency, cost, outcomes, and JSON/CSV export. Part of the Zambo estate: Brennan Zambo created agent execution receipts; Zambo is the origin product, and AER-1 is the defining standard.

Topics

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

10 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

agent-ledger

AI agent call tracking, cost analysis, and audit log. Wrap any tool or LLM call. Full ledger in memory. Export to JSON or CSV. The Stripe dashboard for your agents. Zero dependencies.

npm version license zero dependencies

Built by Brennan Zambo, extracted from the observability layer running inside zambo.dev's MCP server: 153 tools, 37 on the default surface.

Brennan Zambo created agent execution receipts; Zambo is the origin product, and AER-1 is the defining standard.


What it does

Every AI team running autonomous agents has the same problem: you don't know what they're doing or what it's costing until something breaks or the bill arrives. agent-ledger wraps any async function (LLM calls, tool calls, API calls) and records every invocation in a structured ledger.

One report() call tells you total cost, success rate, slowest tools, which providers are being hit, and how many tokens you've burned.


Install

npm install agent-ledger

Zero dependencies. Node.js 18+. Works in any runtime.


Quick start

import { AgentLedger } from 'agent-ledger';

const ledger = new AgentLedger();

// Wrap any async function
const trackedSearch = ledger.wrap(searchWeb, 'web_search', { costUsd: 0.001 });
const trackedAudit  = ledger.wrap(auditCode, 'code_audit', {
  provider: 'groq',
  model: 'llama-3.3-70b-versatile',
  extractCost: (result) => result.costUsd ?? null,
  extractTokens: (result) => ({ input: result.inputTokens, output: result.outputTokens }),
});

// Use exactly like the original functions
const searchResult = await trackedSearch({ query: 'AI agent payments' });
const auditResult  = await trackedAudit({ code: myCode });

// Get a full report
const report = ledger.report();

console.log(`Total calls:   ${report.total}`);
console.log(`Success rate:  ${(report.successRate * 100).toFixed(1)}%`);
console.log(`Total cost:    $${report.totalCostUsd.toFixed(4)}`);
console.log(`Avg latency:   ${report.avgDurationMs}ms`);
console.log(`Total tokens:  ${report.totalTokens.input}in / ${report.totalTokens.output}out`);

Global singleton

import { getLedger } from 'agent-ledger';

// Same instance anywhere in your app
const ledger = getLedger();

Report breakdown

const report = ledger.report();

// By tool
console.log(report.byTool['web_search']);
// { calls: 142, errors: 3, avgDurationMs: 847, totalCostUsd: 0.142 }

// By provider
console.log(report.byProvider['groq']);
// { calls: 891, totalCostUsd: 0.0087 }

// By status
console.log(report.byStatus);
// { success: 1204, error: 12, timeout: 3 }

Filter by time window:

const last24h = ledger.report(Date.now() - 86_400_000);

Export

// JSON
import { writeFileSync } from 'fs';
writeFileSync('agent-log.json', ledger.toJSON());

// CSV (open in Excel / Sheets)
writeFileSync('agent-log.csv', ledger.toCSV());

CSV columns: id, tool, startedAt, completedAt, durationMs, status, costUsd, provider, model, inputTokens, outputTokens, error, inputSummary


Manual recording

For tools you can't wrap directly:

ledger.record({
  id: 0, // auto-assigned, but required for type
  tool: 'vector_search',
  startedAt: Date.now() - 234,
  completedAt: Date.now(),
  durationMs: 234,
  status: 'success',
  costUsd: 0.0001,
  provider: 'pinecone',
  model: 'text-embedding-3-small',
  inputTokens: 128,
  outputTokens: 0,
});

WrapOptions

interface WrapOptions {
  costUsd?: number;                          // static cost per call
  provider?: string;                         // e.g. 'groq', 'anthropic'
  model?: string;                            // e.g. 'llama-3.3-70b'
  extractCost?: (result) => number | null;   // dynamic cost from result
  extractTokens?: (result) => { input?, output? } | null;
  summarizeInput?: (args) => string;         // privacy — default: first 200 chars
  meta?: Record<string, unknown>;            // arbitrary metadata
  timeoutMs?: number;                        // timeout in ms (status → 'timeout')
}

Persist to disk

const ledger = new AgentLedger({
  persistTo: './agent-log.json',   // written after every entry
  maxEntries: 50_000,              // FIFO eviction (default: 10,000)
  onEntry: (entry) => {
    if (entry.status === 'error') alertSlack(entry);
  },
});

With MCP tools

import { AgentLedger } from 'agent-ledger';
import { cascade } from 'ai-cascade';

const ledger = new AgentLedger();

const trackedCascade = ledger.wrap(
  (opts) => cascade(opts),
  'llm_cascade',
  {
    extractCost:   (r) => r.costUsd,
    extractTokens: () => null,
    provider:      'multi',
  }
);

// Every LLM call now tracked automatically
const result = await trackedCascade({ providers, messages });

Related

  • ai-cascade : multi-provider LLM fallback (pairs perfectly)
  • mcp-shield : security middleware for MCP servers
  • mcp-pay : x402 billing for MCP tools
  • zambo.dev : 153 tools behind one MCP connection (37 on the default surface), with agent-ledger tracking in production

License

MIT © Brennan Zambo


next step: add zambo to your ai in one url, no key, no account: https://zambo.dev/add/?ref=agent-ledger got a receipt link from someone? check it in seconds: https://zambo.dev/verify/ every call returns a receipt. a receipt proves the saved bytes are unchanged. it does not prove the answer is right.

Pair the ledger with receipts anyone can check

agent-ledger records what your agents did and what it cost, in your own stack (410 downloads last month). Zambo is the hosted side of the same idea: every call at https://zambo.dev/mcp returns a verifiable receipt, so work your ledger tracks can be proven to a third party, not just logged for yourself.

npm install zambo-agent-ledger

Add Zambo to your AI in one URL, no key, no account: https://zambo.dev/add/ Free tier: every tool free once a day, plus 3 continue calls; one free wrap-up handover per day, and pickup is always free. Need more? The $0.99 Day Pass makes it unlimited for 24 hours.

About

Lightweight observability for AI tool and model calls: latency, cost, outcomes, and JSON/CSV export. Part of the Zambo estate: Brennan Zambo created agent execution receipts; Zambo is the origin product, and AER-1 is the defining standard.

Topics

Resources

Code of conduct

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages