Skip to main content

​
Quickstart

This example creates a Captar runtime, starts a session with budget and policy, wraps an OpenAI client, tracks a tool call, and closes the session cleanly. Use it as the first end-to-end check that your integration is wired correctly. If this works, the rest of the docs should feel familiar rather than abstract. 
import OpenAI from "openai";
import { createCaptar } from "@captar/sdk";

const captar = createCaptar({
  project: "support-bot",
  exporter: { url: process.env.CAPTAR_INGEST_URL! },
});

const session = await captar.startSession({
  budget: {
    maxSpendUsd: 2,
    finalizationReserveUsd: 0.2,
  },
  metadata: {
    _user: "u_123",
    _team: "support",
    feature: "chat",
  },
  policy: {
    call: {
      allowedModels: ["gpt-4.1-mini"],
      maxEstimatedCostUsd: 0.6,
    },
    tool: {
      requireApprovalFor: ["zendesk.createComment"],
    },
  },
});

const openai = captar.wrapOpenAI(
  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  { session },
);

const response = await openai.responses.create({
  model: "gpt-4.1-mini",
  input: "Help me answer this support ticket.",
  max_output_tokens: 200,
});

await captar.trackTool("zendesk.createComment", {
  session,
  estimate: 0.02,
}).run(async () => {
  return { ok: true };
});

await session.close();
await captar.flush();

​
What this shows

1
Captar estimates request cost before the provider call runs.
2
Budget is reserved locally so the session cannot overspend silently.
3
Model and tool policy are evaluated before execution proceeds.
4
Provider usage is reconciled after the response returns.
5
Trace, spend, and guardrail events are emitted for platform export.

​
Things to notice

  • createCaptar() is the project root, not a global singleton.
  • startSession() is where request-scoped budget and policy live.
  • wrapOpenAI() keeps the provider client you already know.
  • trackTool() should wrap external actions that matter to the trace.
  • flush() matters for jobs, scripts, and short-lived serverless requests.

​
Common adjustments

const session = await captar.startSession({
  budget: {
    maxSpendUsd: 0.75,
    finalizationReserveUsd: 0.1,
  },
});

​
Next reads