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

Vercel AI SDK

Use one setup across AI SDK v4, v5, v6, and v7. Squasher selects the compatible instrumentation path internally.

Set up once

src/ai.ts

import * as aiSdk from "ai";
import { withSquasher } from "@squasher-ai/agent";

export const ai = withSquasher(aiSdk, {
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  agentId: "support-bot",
  context: {
    workflow: "support-chat",
  },
});

ai keeps the original AI SDK module types and exports. Squasher instruments generateText and streamText; object generation, agent classes, and other exports pass through unchanged.

Scope each request

import { ai } from "./ai";

export function answer(
  sessionId: string,
  userId: string,
  options: Parameters<typeof ai.streamText>[0],
) {
  return ai.with({ sessionId, userId }).streamText(options);
}

.with() returns another typed module and does not mutate the shared instance. Nested .with() scopes merge context, with inner values winning and attributes merged by key. Prefer .with() for portable request isolation. This call shape is the same on every supported AI SDK major:

AI SDK 6 and 7 use lifecycle integration hooks.
AI SDK 4 and 5 use model middleware.
Existing callbacks, telemetry settings, and telemetry integrations remain in place.

Automatically captured fields include model and provider identity, tokens, cost, latency, finish status, cache and reasoning token counts, model settings, tool trajectory, and streaming outcome.

Serverless and shutdown

Flush after a non-streaming serverless invocation:

export async function answerInServerless(
  sessionId: string,
  options: Parameters<typeof ai.generateText>[0],
) {
  const requestAi = ai.with({ sessionId });

  try {
    return await requestAi.generateText(options);
  } finally {
    await requestAi.flush(2_000);
  }
}

For streams, keep a completion-and-flush task alive with the runtime’s request-lifetime mechanism, such as waitUntil. Flushing before the stream settles can miss terminal telemetry. Call ai.close() during process shutdown, not after every request.

Privacy defaults

Prompt and completion content is off by default. Enable it only for workflows with a deliberate retention policy:

const requestAi = ai.with({
  sessionId,
  capturePayloads: true,
  captureReasoning: false,
});

captureReasoning controls Squasher’s dedicated reasoning field. On the AI SDK 6-7 lifecycle path, capturePayloads: true also retains the provider response, which can contain reasoning parts. Use privacyMode: true when reasoning must not be retained. Privacy mode always wins and suppresses prompt messages, output text, provider payloads, raw error text, reasoning, and tool input/output. Tokens, model/provider identifiers, statuses, tool names, timings, and custom attributes still flow. On the AI SDK 4-5 model-middleware path, streaming output deltas are not accumulated. The AI SDK 6-7 lifecycle path can retain streamed output when payload capture is enabled.

Advanced integrations

Most applications should use withSquasher. The lower-level APIs remain for framework authors and custom instrumentation.

Native AI SDK lifecycle integration

Use the native integration when you already own the call’s telemetry settings or need direct lifecycle events:

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!,
});

const result = streamText({
  model,
  messages,
  telemetry: {
    isEnabled: true,
    integrations: [
      createAiSdkTelemetryIntegration(telemetry, {
        sessionId,
        privacyMode: true,
      }),
    ],
  },
});

await result.consumeStream();
await telemetry.flush();

AI SDK 6 callers can use createAiSdkV6TelemetryIntegration with experimental_telemetry.integrations. Existing integration aliases remain supported.

Model-level middleware

Use middleware to instrument one model independently of the module wrapper:

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

const telemetry = new AgentTelemetryClient({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
});
const observedModel = wrapLanguageModel({
  model,
  middleware: squasherMiddleware(telemetry, {
    workflow: "support-chat",
  }),
});

Use experimental_wrapLanguageModel on AI SDK versions that expose only the experimental name.

Manual telemetry for custom runtimes

Use the underlying client when a runtime does not use Vercel AI SDK:

import { randomBytes } from "node:crypto";
import { AgentTelemetryClient } from "@squasher-ai/agent";

const telemetry = new AgentTelemetryClient({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
});
const traceId = randomBytes(16).toString("hex");
const spanId = randomBytes(8).toString("hex");

await telemetry.captureSessionStart({
  sessionId: "sess_123",
  runId: traceId,
  traceId,
});
await telemetry.captureGeneration("Drafted reply", {
  sessionId: "sess_123",
  traceId,
  spanId,
  provider: "openai",
  model: "gpt-4o-mini",
  promptTokens: 820,
  completionTokens: 140,
  totalTokens: 960,
});
await telemetry.captureSessionEnd({
  sessionId: "sess_123",
  runId: traceId,
  traceId,
  status: "completed",
});
await telemetry.flush();

Always pass a spanId on manual tool calls and generations. Ingest only materializes an observation when it has a span name, trace id, and span id.

Quality scores

Cost and latency tell you a model is cheaper and faster. Only a score tells you whether it is as good — which is the question a rollout actually turns on. For editable ratings or thumbs feedback, use the purpose-built helper. It requires the stable feedback id and trace link that make later edits join the same generation instead of becoming orphan scores:

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

// Editing uses the same feedbackId. Removing it writes a tombstone.
await ai.squasher.captureFeedback({ feedbackId, traceId, deleted: true });

Use sentiment: "positive" | "negative" instead of rating for thumbs feedback. Human feedback is recorded with source: "annotation" automatically. The example below pins a trace-level score to the run it judges. To bind a score to a specific generation instead, also pass that generation’s observationId, as in the feedback example above:

import { randomBytes } from "node:crypto";

const traceId = randomBytes(16).toString("hex");
const result = await ai.with({ sessionId, userId, traceId }).generateText({
  model,
  prompt,
});
const answer = result.text;

await ai.squasher.captureScore({
  scoreId: `answer-quality:${sessionId}`,
  name: "answered_in_one_word",
  dataType: "boolean",
  value: answer.trim().split(/\s+/).length === 1 ? 1 : 0,
  source: "eval",
  comment: `model said: ${answer.trim()}`,
  traceId,
  sessionId,
});

Use a stable scoreId for editable user feedback or annotations. Sending the same id again replaces the prior value in score queries and summaries. Send deleted: true with that id to remove it from query results without a mutable ingest write. source separates a human judgement from an automated one, because they carry very different weight in a rollout decision:

source	meaning
`eval`	an automated judge or offline evaluation
`annotation`	a human reviewer or end user
`api`	another application-originated score

Pass value for numeric and boolean scores (1 / 0), or label for categorical ones like correct / refused. Scores also carry the OpenTelemetry gen_ai.evaluation.* attributes, so they are readable by anything that speaks the GenAI semantic conventions rather than only by Squasher.

Runtime support and guarantees

@squasher-ai/agent is an ESM, server-side package. AI SDK 7 additionally requires Node.js 22+. Telemetry does not change model results, consume a stream on your behalf, alter callback behavior, or replace the original model error. Capture failures remain isolated from the model call.

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

Vercel AI SDK

Set up once

Scope each request

Serverless and shutdown

Privacy defaults

Advanced integrations

Native AI SDK lifecycle integration

Model-level middleware

Manual telemetry for custom runtimes

Quality scores

Runtime support and guarantees

How it appears in Squasher

Good fit

Agent handoff

Notes

​Install

​Vercel AI SDK

​Set up once

​Scope each request

​Serverless and shutdown

​Privacy defaults

​Advanced integrations

​Native AI SDK lifecycle integration

​Model-level middleware

​Manual telemetry for custom runtimes

​Quality scores

​Runtime support and guarantees

​How it appears in Squasher

​Good fit

​Agent handoff

​Notes

Install

Vercel AI SDK

Set up once

Scope each request

Serverless and shutdown

Privacy defaults

Advanced integrations

Native AI SDK lifecycle integration

Model-level middleware

Manual telemetry for custom runtimes

Quality scores

Runtime support and guarantees

How it appears in Squasher

Good fit

Agent handoff

Notes