@useleash/agent

Client-side spending guardrails for LLM agents. Wrap your OpenAI or Anthropic client, set a dollar cap, and Leash tracks usage and stops calls once the limit is hit.

Zero runtime dependencies — bring your own openai or @anthropic-ai/sdk (or any compatible client shape).

Requirements

• Node.js 18+ (uses global fetch)

Install

npm install @useleash/agent

Create an API key in the Leash dashboard and pass it as apiKey.

Quick start (OpenAI)

import OpenAI from 'openai'
import { Leash, LeashError } from '@useleash/agent'

const leash = new Leash({
  apiKey: process.env.LEASH_API_KEY!,
  maxCostUsd: 0.5,
})

const openai = leash.wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY! }))

try {
  const res = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello!' }],
  })
  console.log(res.choices[0]?.message?.content)
  console.log('Spent so far:', leash.totalCost)
} catch (err) {
  if (err instanceof LeashError) {
    console.error('Limit reached:', err.current, '/', err.limit)
  } else {
    throw err
  }
}

Anthropic

import Anthropic from '@anthropic-ai/sdk'
import { Leash } from '@useleash/agent'

const leash = new Leash({
  apiKey: process.env.LEASH_API_KEY!,
  maxCostUsd: 1,
})

const anthropic = leash.wrapAnthropic(
  new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! })
)

const msg = await anthropic.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 256,
  messages: [{ role: 'user', content: 'Hi.' }],
})

Options

| Option | Type | Description | |--------|------|-------------| | apiKey | string | Leash API key (sent as x-api-key to the ingest service). | | maxCostUsd | number | Maximum estimated spend (USD) for this process before calls throw. | | ingestUrl | string (optional) | Base URL for event ingestion. Defaults to the hosted Leash app; override for self-hosted deployments. |

API

• new Leash(opts) — Configure limits and tracking.
• leash.wrapOpenAI(client, runId?) — Proxies client.chat.completions.create.
• leash.wrapAnthropic(client, runId?) — Proxies client.messages.create.
• await leash.completeRun(runId?) — Marks the run completed in the dashboard (only if it was still active, so it does not override stopped). Prefer passing runId explicitly (same value as wrapOpenAI(client, runId)). Uses the last tracked runId if you omit it. Call in finally when your agent exits normally. Throws if the HTTP request fails (wrong key, offline ingest, etc.).
• Limit hit — When spend reaches maxCostUsd, the SDK sets the run to stopped before throwing LeashError.
• leash.totalCost / leash.maxCost — Current estimated spend and cap.
• LeashError — Thrown when the cap is reached (before or after a call, depending on usage). Exposes current and limit (USD).

Costs are estimated from built-in per-token rates for a fixed set of models; unknown models fall back to Sonnet 4–6–style pricing.

Try a multi-step agent (OpenAI)

From packages/sdk with OPENAI_API_KEY and LEASH_API_KEY in .env (the demo also reads LEASH_TEST_API_KEY for older local setups):

npm run demo:agent

Optional: LEASH_INGEST_URL (your deployed app origin), LEASH_MAX_USD (cap). Confirm events under that runId in the Leash dashboard.

License

MIT