Files · Anthropic AI Spend Tracker for SMB Agent Workflows

# Anthropic AI Spend Tracker for SMB Agent Workflows
 
Monitor and control Anthropic API costs across your AI agents with real-time dashboards and per-agent budget enforcement.
 
## Problem
 
Small businesses deploying multiple AI agents on Anthropic lack visibility into per-agent spend, leading to unexpected bills and uncontrolled cost scaling as agent usage grows.
 
## Solution
 
This solution anchors cost observability on **@reaatech/agent-budget-spend-tracker**, which captures granular token usage per agent workflow, and **@reaatech/agent-budget-engine**, which enforces per-agent caps and can route to cheaper models when thresholds are hit. **@reaatech/agent-runbook-observability** surfaces cost metrics and budget alerts in a shared dashboard, while **@reaatech/agent-eval-harness-observability** provides latency and quality context to distinguish between expensive slow runs and efficient responses.
 
## Architecture
 
```
src/
  api/
    report/route.ts   -- GET /api/report (aggregated spend data)
    health/route.ts   -- GET /api/health (service health check)
    metrics/route.ts  -- GET /api/metrics (Prometheus metrics)
  components/
    SpendDashboard.tsx  -- Real-time spend dashboard (client component)
    SpendWidget.tsx     -- Compact spend widget (client component)
  dashboard/
    route.ts          -- Server component data fetcher
  lib/
    errors.ts           -- Custom error classes
    env.ts              -- Type-safe environment configuration (Zod)
    logger.ts           -- Structured logging (Pino via agent-runbook-observability)
    telemetry.ts        -- OpenTelemetry tracing & metrics
    spend-store.ts      -- SpendStore wrapper (agent-budget-spend-tracker)
    pricing-provider.ts -- Anthropic pricing lookup table
    budget-controller.ts -- BudgetController wrapper (agent-budget-engine)
    anthropic-client.ts -- Pre-configured Anthropic SDK client
    langfuse.ts         -- Langfuse observability client
    sync-loop.ts        -- Background sync loop
  middleware/
    budget.ts           -- Budget enforcement middleware
  instrumentation.ts   -- Next.js server instrumentation hook
  env.ts               -- Environment variable parsing
```
 
## Setup
 
1. Clone the repository
2. Install dependencies:
   ```bash
   pnpm install
   ```
3. Configure environment:
   ```bash
   cp .env.example .env
   # Edit .env with your actual API keys
   ```
4. Start the dev server:
   ```bash
   pnpm dev
   ```
 
## Environment Variables
 
| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Yes | Anthropic API key |
| `LANGFUSE_PUBLIC_KEY` | Yes | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Yes | Langfuse secret key |
| `LANGFUSE_HOST` | No | Langfuse host (default: https://cloud.langfuse.com) |
| `OPENTELEMETRY_ENDPOINT` | No | OTLP collector endpoint |
| `BUDGET_DEFAULT_LIMIT_USD` | No | Default budget limit (default: 10.00) |
| `BUDGET_DEFAULT_SCOPE_TYPE` | No | Default scope type (default: user) |
 
## Usage
 
### Set a budget via CLI
 
```bash
pnpm exec agent-budget set --scope user:agent-1 --limit 10.00 --soft-cap 0.8 --hard-cap 1.0
```
 
### View spend reports
 
```bash
curl http://localhost:3000/api/report?agentId=agent-1&hours=24
```
 
### Read the dashboard
 
Open `http://localhost:3000/dashboard` in your browser to see real-time spend data for all agents.
 
### Budget enforcement
 
The budget middleware (`src/middleware/budget.ts`) intercepts Anthropic API calls, checks budgets, auto-downgrades models, and filters expensive tools when configured.
 
## Scripts
 
- `pnpm typecheck` — TypeScript type checking
- `pnpm lint` — ESLint
- `pnpm test` — Vitest unit tests
- `pnpm test:coverage` — Vitest with coverage
- `pnpm build` — Next.js production build
- `pnpm dev` — Development server
 
## Dependencies
 
### REAA Packages
 
- `@reaatech/agent-budget-spend-tracker@0.1.0` — Circular-buffer spend store
- `@reaatech/agent-budget-engine@0.1.0` — Budget enforcement engine
- `@reaatech/agent-runbook-observability@0.1.0` — Observability layer (Pino, OTel)
- `@reaatech/agent-eval-harness-observability@0.1.0` — Evaluation metrics
- `@reaatech/agent-budget-cli@0.1.0` — Budget management CLI
- `@reaatech/agent-budget-types@0.1.0` — Shared type definitions
 
### Third-Party
 
- `@anthropic-ai/sdk@0.95.2` — Anthropic Claude SDK
- `langfuse@3.38.20` — Langfuse observability
- `zod@4.4.3` — Schema validation
- `p-retry@8.0.0` — Retry logic
- `next@15.3.3` — React framework
- `react@19.1.0` — UI library
 
## License
 
MIT — see [LICENSE](LICENSE)