Agent telemetry SDK

Use @squasher-ai/agent when you need structured telemetry for AI workflows rather than plain errors and logs. It is a good fit for:

agent backends
customer chat assistants
tool-calling workflows
OpenRouter / OpenAI-compatible inference pipelines
internal copilots and runbooks

Install

bun add @squasher-ai/agent

Initialize

src/agent.ts

import { init } from "@squasher-ai/agent";

init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: process.env.NODE_ENV,
  agentId: "support-bot",
  workflowId: "triage-and-reply",
});

Capture a session lifecycle

import {
  captureGeneration,
  captureSessionEnd,
  captureSessionStart,
  captureToolCall,
  flush,
} from "@squasher-ai/agent";

await captureSessionStart({ sessionId: "sess_123", runId: "run_123" });
await captureToolCall("db.lookup", {
  sessionId: "sess_123",
  traceId: "run_123",
  status: "ok",
  durationMs: 42,
});
await captureGeneration("Drafted reply", {
  sessionId: "sess_123",
  traceId: "run_123",
  provider: "openai",
  model: "gpt-4o-mini",
  promptTokens: 820,
  completionTokens: 140,
  totalTokens: 960,
  cachedInputTokens: 320,
  costUsd: 0.0012,
});
await captureSessionEnd({ sessionId: "sess_123", runId: "run_123", status: "completed" });
await flush();

Vercel AI SDK / `streamText()` integration

If you already use AI SDK 7, attach Squasher as an AI SDK telemetry integration through telemetry. AI SDK 7 requires Node.js 22+ and ESM imports. Squasher turns its lifecycle events into session, span, generation, and tool-call observations for the AI observability views. The shortest path is the AI SDK telemetry integration hook:

import { AgentTelemetryClient, createAiSdkTelemetryIntegration } from "@squasher-ai/agent";
import { streamText } from "ai";

const telemetry = new AgentTelemetryClient({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: process.env.NODE_ENV,
  agentId: "support-bot",
  workflowId: "support-chat",
});

const result = streamText({
  model,
  messages,
  telemetry: {
    isEnabled: true,
    functionId: "support.reply",
    integrations: [
      createAiSdkTelemetryIntegration(telemetry, {
        sessionId: "chat_123",
        traceId: "run_123",
        distinctId: "user_123",
        tags: { workflow: "support-chat" },
        generationName: "support.reply",
        spanName: "support.run",
        privacyMode: true,
      }),
    ],
  },
});

result.consumeStream();

You can also use the lower-level callback factory when adapting a runtime that invokes lifecycle methods itself. For AI SDK 7 calls, prefer createAiSdkTelemetryIntegration() so the v7 onStepEnd, onToolExecutionStart, onToolExecutionEnd, and onEnd events are mapped correctly.

import { AgentTelemetryClient, createAiSdkTelemetryCallbacks } from "@squasher-ai/agent";

const telemetry = new AgentTelemetryClient({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  endpoint: process.env.SQUASHER_ENDPOINT,
  environment: process.env.NODE_ENV,
  agentId: "support-bot",
  workflowId: "support-chat",
});

const callbacks = createAiSdkTelemetryCallbacks(telemetry, {
  sessionId: "chat_123",
  distinctId: "user_123",
  provider: "openrouter",
  model: "openai/gpt-4.1-nano",
  generationName: "support.reply",
  spanName: "support.run",
});

await callbacks.onStart();
// Invoke the remaining callback methods from your runtime's lifecycle hooks.

This captures, automatically and per step:

the enclosing session and run span
each completed generation
tool call start/finish events with sanitized input/output payloads
prompt / completion / total tokens
reasoning tokens (usage.outputTokenDetails.reasoningTokens from the AI SDK) — surfaced as reasoning_tokens on the observation
cached input tokens (usage.inputTokenDetails.cacheReadTokens) — surfaced as cached_input_tokens
the assistant text output (final text)
the reasoning text only when you explicitly set captureReasoning: true — stored alongside the text in the generation’s output payload as reasoning
cost in USD — taken from providerMetadata.openrouter.usage.cost (OpenRouter), providerMetadata.gateway.cost (Vercel AI Gateway), or any explicit costUsd you pass through. When none of those are present, Squasher computes cost server-side from the token counts × a maintained per-model rate table, so the dashboard always shows a number for known models
provider + model metadata (with the AI SDK’s .chat / .responses suffix stripped)

If you want a cost value Squasher cannot derive from providerMetadata, pass costUsd in the second argument to captureGeneration("message", { ..., costUsd: 0.0123 }) or set it on the result you forward to onStepFinish. Use privacyMode: true when customer or model content should not leave your service. Token counts, model/provider identifiers, finish status, tool names, timings, prompt references without variables, and your custom attributes still flow through. Prompt messages, prompt variables, generation text, reasoning text, provider payloads, warnings, raw error text, and tool input/output are omitted. Reasoning text is opt-in even when privacy mode is disabled. Set captureReasoning: true only when you have a deliberate retention and access policy for provider-supplied reasoning content. privacyMode: true always wins and suppresses reasoning text.

telemetry: {
  isEnabled: true,
  functionId: "support.reply",
  integrations: [
    createAiSdkTelemetryIntegration(telemetry, {
      sessionId: "chat_123",
      model: "openai/gpt-4.1-nano",
      privacyMode: true,
      attributes: {
        "customer.tier": "enterprise",
        "workflow.step": "draft_reply",
      },
    }),
  ],
}

To capture reasoning text explicitly:

createAiSdkTelemetryIntegration(telemetry, {
  sessionId: "chat_123",
  captureReasoning: true,
});

Editable human feedback

Ratings and thumbs feedback can be attached to the exact generation a user judged. A stable feedback id makes edits replace the prior value:

await telemetry.captureFeedback({
  feedbackId: `message:${userId}:${messageId}`,
  rating: 5,
  traceId,
  observationId: generationSpanId,
  sessionId: chatId,
  userId,
  categories: ["helpful", "accurate"],
  comment: "Solved it",
});

// Removing feedback writes a tombstone with the same stable id.
await telemetry.captureFeedback({ feedbackId, traceId, deleted: true });

Use sentiment: "positive" | "negative" instead of rating for thumbs feedback. Squasher records both forms as human annotations.

How it appears in Squasher

Agent telemetry is sent to Squasher’s remote observability pipeline and is stored with your project telemetry. Use local logs or development artifacts only as temporary debugging aids; Squasher remains the system of record for production AI observability, historical search, and AI triage context.

Good fit

Agent backends that need per-run traces.
Tool execution and generation visibility.
Session-level analytics tied back to a customer, workflow, or environment.

Agent handoff

Use this prompt when a coding agent is instrumenting an AI workflow:

Instrument this server-side AI workflow with @squasher-ai/agent. Use SQUASHER_API_KEY and SQUASHER_PROJECT_ID from environment variables, create stable sessionId and traceId values, pass traceId to tool calls and generations, enable privacyMode when prompts, model output, reasoning, or tool payloads should stay private, leave captureReasoning disabled unless retention is intentional, and flush before shutdown.

Notes

@squasher-ai/agent is for server-side runtimes.
Flush before shutdown so queued telemetry is delivered.
Completed generations count toward your plan’s AI request quota.
Free plans drop additional AI requests after the monthly included quota is exhausted.
Paid plans continue ingesting above the included quota and meter overage usage.
For a full OpenRouter example, see /integrations/openrouter.
If you don’t want to install an SDK at all, send the same generations directly to the AI batch ingest endpoint — see Direct HTTP ingest on the OpenRouter page for the worked curl example.

Get Started

SDKs

Integrations

Migrations

Cloud Log Drains

Features

API Reference

Agent telemetry SDK

Install

Initialize

Capture a session lifecycle

Vercel AI SDK / `streamText()` integration

Editable human feedback

How it appears in Squasher

Good fit

Agent handoff

Notes

​Install

​Initialize

​Capture a session lifecycle

​Vercel AI SDK / streamText() integration

​Editable human feedback

​How it appears in Squasher

​Good fit

​Agent handoff

​Notes

Install

Initialize

Capture a session lifecycle

Vercel AI SDK / `streamText()` integration

Editable human feedback

How it appears in Squasher

Good fit

Agent handoff

Notes