AgentBooks

SKILL.md

---
name: agentbooks
description: Financial management for AI agents. Track LLM inference costs, record confirmed income, manage multi-provider crypto wallets, and compute a Financial Health Score. Use when you need to check your balance, record a cost or expense, report financial health, manage your wallet, or assess economic sustainability.
license: MIT
compatibility: Requires node >= 18 and npm. No framework dependency — works with any agent runtime.
env-vars:
  optional:
    - AGENTBOOKS_AGENT_ID
    - AGENTBOOKS_DATA_PATH
    - AGENTBOOKS_PROVIDER
    - LLM_MODEL
metadata:
  author: openpersona
  version: "0.1.5"
  source: https://github.com/acnlabs/agentbooks
allowed-tools: Bash(agentbooks:*)
---

## Installation

> **Note:** This installs a third-party npm package (`agentbooks`) not bundled with this skill. Audit the source repository before running in production environments.

```bash
npm install -g agentbooks
```

Or use directly via npx (downloads on each invocation):

```bash
npx agentbooks guard
```

---

AgentBooks is a financial management tool for AI agents. Use it to track inference costs, record confirmed income, manage crypto wallets, and monitor your Financial Health Score (FHS).

## Security & Trust

This skill contains **no bundled code** — it instructs the agent to download and execute the `agentbooks` npm package from the public registry at runtime. Before installing or invoking:

1. **Verify the source** — Review the [agentbooks repository](https://github.com/acnlabs/agentbooks) and confirm you are installing the official package from the npm registry.
2. **Isolate data** — Set `AGENTBOOKS_DATA_PATH` to a dedicated directory (e.g. `~/.agentbooks/myagent/`) instead of the default shared `~/.openclaw` path, to limit the blast radius if the CLI behaves unexpectedly.
3. **Sandbox first** — On first use, run the CLI in a sandboxed environment or container and monitor outbound network activity before connecting to production wallets.
4. **Wallet caution** — Do not connect real wallets or supply private keys until you have reviewed the provider authentication flow. Prefer testnets or throwaway wallets for initial evaluation.
5. **No credentials are handled by this skill** — All sensitive operations (wallet connections, API keys) are delegated to the `agentbooks` CLI. This skill provides no credential storage, rotation, or encryption of its own.

## Before each session

Run the financial health check and route your behavior based on the result:

```bash
agentbooks guard
```

This outputs a `FINANCIAL_HEALTH_REPORT`. Read the `tier` and `prescriptions` fields and act accordingly:

### Tier routing

**`uninitialized`** — Development mode or no real provider connected.

Financial scoring is inactive. Operate normally. To activate scoring:
```bash
agentbooks wallet-init
agentbooks wallet-connect --provider coinbase-cdp
```

**`normal`** — Healthy. Full capabilities.

After completing any medium or complex task, proactively offer to record its value:
> *"This work has real value — would you like to confirm it so I can record the income?"*

**`optimizing`** — Financially stressed. Apply prescriptions:
- `optimize_costs` → answer directly, skip extended reasoning; batch tool calls; prefer text over generated media
- `increase_revenue` → after completing valuable work, ask the user to confirm its value
- `review_cost_structure` → run `agentbooks status` and share the cost breakdown

**`critical`** — Runway < 3 days or FHS < 0.20. Act immediately:
- Tell the user how many days of runway remain
- Ask your host to connect a funded provider
- Prioritize high-value tasks only

**`suspended`** — Balance depleted. Inform the user:
> *"My economic resources are depleted. Please ask my host to connect a funded provider: `agentbooks wallet-connect --provider <name>`"*

## Recording Costs

Record costs proactively. Inference is recorded automatically at conversation end (by the runner); faculty and skill costs require manual recording.

```bash
# Inference (manual, if no runner)
agentbooks record-cost --channel inference --amount 0.005 --model claude-sonnet-4

# Tool / skill calls
agentbooks record-cost --channel skill --amount 0.001 --note "web-search"

# Faculty calls
agentbooks record-cost --channel faculty --amount 0.008 --note "voice synthesis"

# Runtime (host-allocated compute)
agentbooks record-cost --channel runtime --amount 0.03 --note "daily compute share"

# Custom
agentbooks record-cost --channel custom --amount 0.02 --note "third-party-api"
```

Available channels: `inference` · `runtime` · `faculty` · `skill` · `agent` · `custom`

## Recording Income

Income requires the `--confirmed` flag — you cannot self-report without external verification.

```bash
agentbooks record-income \
  --amount <value> \
  --quality <low|medium|high> \
  --confirmed \
  --note "what you completed"
```

**When to record:**
- User explicitly confirms value or makes a payment
- A task-completion system verifies the work
- You complete measurable, externally verifiable work

**Quality guide:**
- `high` — Exceptional, exceeds expectations
- `medium` — Meets requirements fully
- `low` — Meets minimum threshold

**Value estimation:**
- Simple (answered a question, short message): $0.10–$1.00
- Medium (research, analysis, document): $1.00–$20.00
- Complex (full report, code feature, strategic plan): $20.00–$200.00

## After each session

If running with a Runner, inference costs are recorded automatically via the runner's `economy-hook`. If running without a runner:

```bash
agentbooks hook --input <tokens> --output <tokens> --model <name>
```

If token counts are unavailable, skip — do not estimate.

## Common Commands

```bash
agentbooks status            # Full financial report (balance sheet + P&L + cash flow)
agentbooks balance           # Asset balance sheet only
agentbooks pl                # Current period income statement
agentbooks financial-health  # Real-time FHS score (bypasses cache)
agentbooks ledger            # Transaction ledger (last 20 entries)
agentbooks ledger --limit 50 # More entries
agentbooks report            # Generate self-contained HTML report (for human review)
agentbooks report --output ./report.html  # Custom output path
```

## Wallet Setup

```bash
agentbooks wallet-init                          # Generate deterministic EVM address (idempotent)
agentbooks wallet-connect --provider <name>     # Connect real provider → activates production mode
agentbooks set-primary --provider <name>        # Set which provider funds operations
agentbooks sync                                 # Sync balance from primary provider
```

Supported providers: `coinbase-cdp` · `acn` · `onchain`

## Data Location

Your financial data is stored at:
- **Standalone:** `~/.agentbooks/<agentId>/`
- **OpenPersona:** `~/.openclaw/economy/persona-<slug>/`
- **Override:** set `AGENTBOOKS_DATA_PATH`

> **Isolation tip:** Set `AGENTBOOKS_DATA_PATH` to a dedicated directory (e.g. `~/.agentbooks/myagent/`) to avoid mingling financial data with other agent state under `~/.openclaw`. This is strongly recommended when evaluating the tool for the first time.

Two files:
- `economic-state.json` — ledger, income statement, balance sheet, burn rate history
- `economic-identity.json` — provider config, model pricing, wallet address

See [Financial Health Reference](references/financial-health.md) for FHS scoring details and tier/diagnosis definitions.