AgentBooks

Financial management toolkit for AI agents — framework-agnostic, works with any agent runtime.

Version: 0.1.4 · Live Demo Report →

What it is

AgentBooks gives AI agents a real, double-entry financial ledger. Agents track their costs (LLM inference, runtime, custom), record confirmed income, maintain a balance sheet against real crypto wallets, and compute a Financial Health Score (FHS) that reflects their operational sustainability.

AgentBooks is a financial dimension provider. It does not make behavioral decisions — it computes facts and exposes them. Host frameworks (like OpenPersona) aggregate the financial dimension into a broader Vitality score and map it to agent behavior.

Installation

# Standalone
npm install -g agentbooks

# As a module (within a monorepo or framework)
npm install agentbooks

Quick Start

# Set your agent ID
export AGENTBOOKS_AGENT_ID=my-agent

# Initialize wallet
agentbooks wallet-init

# Connect a real provider (switches to production mode)
agentbooks wallet-connect --provider coinbase-cdp

# Check financial health
agentbooks status

# Generate a self-contained HTML report (open in browser)
agentbooks report

# Record a cost (manual)
agentbooks record-cost --channel inference --amount 0.005 --note "code review"

# Record confirmed income
agentbooks record-income --amount 10.00 --quality high --confirmed

# Pre-conversation health check (outputs FINANCIAL_HEALTH_REPORT)
agentbooks guard

HTML Report

Generate a self-contained HTML file for human review — no external dependencies, open directly in a browser:

agentbooks report                          # saves agentbooks-report-<id>-<date>.html
agentbooks report --output ./report.html   # custom output path

The report includes: Financial Health Score with tier badge, wallet & provider balances, P&L (current period + all time), cost breakdown by channel, daily burn rate trend chart (SVG), and the last 50 ledger entries.

To preview the report with realistic mock data (no real agent needed):

node scripts/gen-demo-report.js                      # saves agentbooks-demo-report.html
node scripts/gen-demo-report.js --output ./demo.html # custom path

Or view the hosted demo directly in your browser.

Runner Integration

Runners call economy-hook after each conversation to record LLM costs automatically.

Environment variables (runner sets these):

| Variable | Description | |---|---| | AGENTBOOKS_AGENT_ID | Agent identifier | | AGENTBOOKS_DATA_PATH | Data directory (default: ~/.agentbooks/<id>/) | | TOKEN_INPUT_COUNT | Input token count for this conversation | | TOKEN_OUTPUT_COUNT | Output token count | | TOKEN_THINKING_COUNT | Thinking token count (optional) | | LLM_MODEL | Model name (e.g. claude-sonnet-4) | | CONVERSATION_DURATION_MS | Duration in ms (for burn rate estimate) |

# Runner calls this at end of every conversation
TOKEN_INPUT_COUNT=1500 TOKEN_OUTPUT_COUNT=800 LLM_MODEL=claude-sonnet-4 \
  agentbooks hook

Data Location

Standalone: ~/.agentbooks/<agentId>/

• economic-state.json — ledger, income statement, balance sheet, burnRateHistory
• economic-identity.json — provider config, model pricing, wallet address

OpenPersona integration: ~/.openclaw/economy/persona-<slug>/ (set via AGENTBOOKS_DATA_PATH)

Financial Health Score (FHS)

The FHS is a 0–1 composite score, not exposed to agents as a raw number but mapped to tiers:

| Tier | Meaning | |---|---| | uninitialized | Development mode or no real provider connected | | normal | FHS ≥ 0.50 and runway ≥ 14 days | | optimizing | FHS < 0.50 or runway < 14 days | | critical | FHS < 0.20 or runway < 3 days | | suspended | Balance ≤ 0 |

Dimensions (weights):

• Liquidity 0.40 — days of runway
• Profitability 0.30 — net income rate
• Efficiency 0.15 — revenue/expense ratio
• Trend 0.15 — recent burn rate direction

Data Integrity

Three-layer defense against fabricated financial data:

1. Provider is source of truth — operational balance mirrors the external provider; balance cannot be directly set via CLI
2. Cash flow reconciliation — openingBalance + revenue - expenses ≈ operationalBalance; discrepancy > $0.01 appends to integrityWarnings (production mode only)
3. Ledger source field — every entry tagged agent | runner | provider_sync; runner entries are trusted; agent entries are auditable

Supported Providers

| Provider | Assets | Status | |---|---|---| | coinbase-cdp | USDC, ETH on Base | Integration ready (SDK call reserved) | | acn | ACN credits | Integration ready | | onchain | USDC, ETH on Base | Integration ready |

OpenPersona Integration

AgentBooks exports calcFinancialHealth(state, identity) as its public API. OpenPersona's lib/vitality.js consumes this as the financial dimension in its Vitality aggregator.

# OpenPersona-specific Vitality report (aggregates financial + future dimensions)
openpersona vitality <slug>

# AgentBooks standalone report
agentbooks guard

API

const {
  calcFinancialHealth,       // (state, identity) → { fhs, tier, diagnosis, prescriptions, ... }
  createInitialState,        // (agentId) → initial economic-state.json
  createIdentityInitialState,// (agentId) → initial economic-identity.json
  createLedgerEntry,         // (type, channel, amount, opts) → ledger entry
  addToExpenseAccount,       // (state, identity, opts) → mutates state
  shouldRollover,            // (state) → boolean
  rolloverPeriod,            // (state) → mutates state
  deductFromProvider,        // (state, identity, amountUSD) → mutates state
  creditToProvider,          // (state, identity, amountUSD) → mutates state
  validateState,             // (state, identity) → mutates derived fields
} = require('agentbooks');

License

MIT