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