Agent SDK

@squasher-ai/agent records the model calls and tool calls of your server-side AI code. With the Vercel AI SDK, versions 4 to 7, you wrap the ai module once, and every generateText and streamText call appears in AI observability.

What the SDK records

Data	Recorded
Model, provider, finish status, latency	Always.
Prompt, completion, cached input, and reasoning token counts	Always.
Cost	Always. From the provider when it reports cost, or computed by Squasher.
Tool names and timing	Always.
Session, user, workflow, and your attributes	When you set them.
Prompts, output text, and tool input and output	Only with `capturePayloads: true`.
Reasoning text	Only with `captureReasoning: true`.

Install the SDK

npm install @squasher-ai/agent

Add your ingest key and project ID to the server environment as SQUASHER_API_KEY and SQUASHER_PROJECT_ID. To get both values, see Create an ingest key. The package is ESM only and runs on the server.

Wrap the AI SDK 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!,
  environment: process.env.NODE_ENV,
  agentId: "support-bot",
  context: { workflow: "support-chat" },
});

ai has the same exports and types as the ai package. Your callbacks and telemetry settings stay as they are.

Scope each request

Call .with() to add the session and user of a request. It returns a new scoped module and does not change the shared one.

src/chat.ts

import { openai } from "@ai-sdk/openai";
import { ai } from "./ai";

export function reply(chatId: string, userId: string, question: string) {
  return ai.with({ sessionId: chatId, userId }).generateText({
    model: openai("gpt-4o-mini"),
    prompt: question,
  });
}

Nested .with() calls merge: the inner values win, and attributes merge by key.

Flush before a serverless function ends

The SDK sends data in batches. In a serverless function, flush before the function returns:

src/handler.ts

import { openai } from "@ai-sdk/openai";
import { ai } from "./ai";

export async function handler(sessionId: string, prompt: string) {
  const requestAi = ai.with({ sessionId });
  try {
    return await requestAi.generateText({
      model: openai("gpt-4o-mini"),
      prompt,
    });
  } finally {
    await requestAi.flush(2_000);
  }
}

For a stream, flush after the stream finishes, for example in the runtime’s waitUntil. A flush before the stream ends can miss the last data. Call ai.close() when the process shuts down, not after each request.

Record prompts and output text

Prompts and output text are off by default. Turn them on only where you have a policy to keep them:

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

captureReasoning: true also records reasoning text. On AI SDK 6 and 7, capturePayloads keeps the provider response, which can contain reasoning. To make sure that no content is recorded, set privacyMode: true: it wins over the other options.

Record quality scores

Link a score to a trace: set your own traceId (32 hex characters) on the request, then send the score with the same traceId.

src/answer.ts

import { randomBytes } from "node:crypto";
import { openai } from "@ai-sdk/openai";
import { ai } from "./ai";

export async function answer(sessionId: string, question: string) {
  const traceId = randomBytes(16).toString("hex");
  const result = await ai.with({ sessionId, traceId }).generateText({
    model: openai("gpt-4o-mini"),
    prompt: question,
  });
  // An automated check
  await ai.squasher.captureScore({
    scoreId: `short-answer:${traceId}`,
    name: "answer_under_100_words",
    dataType: "boolean",
    value: result.text.split(/\s+/).length < 100 ? 1 : 0,
    source: "eval",
    traceId,
    sessionId,
  });
  return { text: result.text, traceId };
}

// A rating from the user, later
export function rateAnswer(traceId: string, userId: string, liked: boolean) {
  return ai.squasher.captureFeedback({
    feedbackId: `answer:${traceId}:${userId}`,
    traceId,
    userId,
    sentiment: liked ? "positive" : "negative",
  });
}

Field	Description
`source`	`eval` for an automated check, `annotation` for a person, `api` for other scores (default). Feedback is always `annotation`.
`value` or `label`	A number (`1` and `0` for a boolean), or a category such as `correct`.
`scoreId`, `feedbackId`	A stable ID. Send the same ID again to change the value, or with `deleted: true` to remove it.
`rating` or `sentiment`	For feedback: a number, or `positive` or `negative`.
`observationId`	Optional. Links the score to one model call in the trace.

Send data without the AI SDK

For other frameworks, use the client directly. Every generation and tool call needs a traceId and a spanId; Squasher drops events without them.

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");

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

captureToolCall(name, input) records a tool call the same way. To send AI data without any SDK, see HTTP batch ingest.

Options

Option	Description
`apiKey`	Your ingest key. Required.
`projectId`	Your project ID. Required.
`environment`	For example `production`.
`release`	Your app version or commit.
`agentId`, `workflowId`	Names that you can filter on in the CLI and the API.
`endpoint`	The ingest URL. The default is `https://ingest.squasher.ai`.
`context`	Default request context: `workflow`, `sessionId`, `userId`, `traceId`, `attributes`, `generationName`, `capturePayloads`, `captureReasoning`, and `privacyMode`. `.with()` takes the same fields.

Limits

The wrapper records generateText and streamText only. generateObject, streamObject, embeddings, and agent classes work as before, but Squasher does not record them.
On AI SDK 4 and 5, streamed output text is not recorded, even with capturePayloads.
If Squasher cannot record a call, your model call still runs and returns as normal.
The package also exports lower-level parts: createAiSdkTelemetryIntegration, createAiSdkV6TelemetryIntegration, and squasherMiddleware. When you use the integration directly, prompts and output are recorded unless you set privacyMode: true.

Give the setup to a coding agent

Install @squasher-ai/agent in this server-side project. In one module, import * as aiSdk from "ai"
and export withSquasher(aiSdk, { apiKey: process.env.SQUASHER_API_KEY, projectId:
process.env.SQUASHER_PROJECT_ID, environment: process.env.NODE_ENV }). Replace imports of
generateText and streamText from "ai" with that module, and call .with({ sessionId, userId }) for
each request. Keep capturePayloads off. In serverless handlers, await flush() before returning,
or after the stream finishes.

Get started

Guides

What the SDK records

Install the SDK

Wrap the AI SDK once

Scope each request

Flush before a serverless function ends

Record prompts and output text

Record quality scores

Send data without the AI SDK

Options

Limits

Give the setup to a coding agent

Next steps

AI observability

OpenRouter

​What the SDK records

​Install the SDK

​Wrap the AI SDK once

​Scope each request

​Flush before a serverless function ends

​Record prompts and output text

​Record quality scores

​Send data without the AI SDK

​Options

​Limits

​Give the setup to a coding agent

​Next steps

AI observability

OpenRouter

What the SDK records

Install the SDK

Wrap the AI SDK once

Scope each request

Flush before a serverless function ends

Record prompts and output text

Record quality scores

Send data without the AI SDK

Options

Limits

Give the setup to a coding agent

Next steps