DOCS

Capsule documentation

Getting started

Capsule wraps every AI agent you run in production with full visibility, hard cost limits, and policy control. You can be tracing your first agent in about five minutes — no rebuilds or migrations required.

You'll need a Capsule account and an API key, which you can create from the dashboard under Settings → API keys.

Install the SDK

Install the SDK with your package manager:

npm install @capsule/sdk
# or
pnpm add @capsule/sdk

Then wrap any agent run inside a Capsule:

import { capsule } from "@capsule/sdk"

const agent = capsule.wrap(myAgent, {
  name: "support-agent",
  maxUsd: 50,
  region: "us-east",
})

await agent.run(input)

Concept · Trace

Every run executes inside an observable Capsule. Inputs, tool calls, sub-agent handoffs, latency, and outcomes are captured automatically and available for end-to-end replay.

const trace = await agent.run(input)
console.log(trace.id) // → "trace_7f3a..."

Concept · Cap

Set hard token and cost budgets at the agent, team, or org level. When a budget is breached, Capsule pauses the run before it spends another cent.

capsule.cap({
  scope: "team:growth",
  maxUsd: 500,
  window: "1d",
  onBreach: "pause",
})

Concept · Route

Policy-based routing picks the right model, provider, and region for each step — with automatic failover and data-residency controls.

capsule.route({
  default: "gpt-4o",
  rules: [
    { if: "region == 'eu'", use: "mistral-large", region: "eu" },
    { if: "step == 'classify'", use: "gpt-4o-mini" },
  ],
})

Policies

Define governance as code. Policies are versioned, reviewable, and enforced on every run — so platform teams stay in control as agents scale.

capsule.policy({
  maxUsd: 50,
  region: "us",
  allowTools: ["search", "db.read"],
  denyTools: ["db.write"],
  requireApprovalOver: 25,
})

API reference

All endpoints are available under https://api.capsule.dev/v1. Authenticate with a bearer token.

GET    /v1/traces            list traces
GET    /v1/traces/:id        fetch a trace
POST   /v1/policies          create a policy
GET    /v1/usage             cost & token usage