Vercel AI SDK 7

AI SDK 7

You are viewing the recommended integration.

AI SDK 5–6

View the legacy experimental telemetry guide.

The @contextcompany/ai-sdk package registers AI SDK 7’s native OpenTelemetry integration and sends traces to The Context Company. It captures runs, model calls, tool executions, token usage, costs, sessions, users, organizations, and custom metadata.

Dependency	Supported version
Node.js	22 or newer
`ai`	7.x
`@contextcompany/ai-sdk`	1.x
Telemetry	Stable `telemetry` and `runtimeContext`

For AI SDK 5 or 6, use the AI SDK 5–6 guide.

Set TCC environment variables

Our SDKs default to using the TCC_API_KEY environment variable.

.env.local

TCC_API_KEY="your-api-key"

Instrument AI SDK

If your AI SDK calls run in Next.js route handlers, use the @contextcompany/ai-sdk/nextjs entry point. If you use another Node.js framework, use the root @contextcompany/ai-sdk entry point. It owns the OpenTelemetry NodeSDK and returns a shutdown handle.

Next.js
Node.js

Step 1: Install dependencies

pnpm add @contextcompany/ai-sdk ai @opentelemetry/api

npm i @contextcompany/ai-sdk ai @opentelemetry/api

bun add @contextcompany/ai-sdk ai @opentelemetry/api

Step 2: Add instrumentation to Next.js

Add an instrumentation.[js|ts] file to your project root, or inside src if your application uses a src directory. See the Next.js Instrumentation guide for more information.Call registerTCC once when the Node.js runtime starts. The function is idempotent, so Next.js development reloads do not register duplicate integrations.

instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerTCC } = await import("@contextcompany/ai-sdk/nextjs");
    registerTCC();
  }
}

Step 3: Add telemetry to AI SDK calls

Use tccTelemetry on each call where you want an explicit run ID and metadata. Put TCC-specific fields and custom application fields in the same metadata object. Every TCC-specific key uses the tcc.* namespace.

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { generateText } from "ai";

const result = await generateText({
  model,
  prompt: "Write a short story about a lighthouse.",
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
    },
  }),
});

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { streamText } from "ai";

const result = streamText({
  model,
  prompt: "Write a short story about a lighthouse.",
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
    },
  }),
});

Step 1: Install dependencies

pnpm add @contextcompany/ai-sdk ai @opentelemetry/api

npm i @contextcompany/ai-sdk ai @opentelemetry/api

bun add @contextcompany/ai-sdk ai @opentelemetry/api

Step 2: Register the integration

telemetry.ts

import { registerTCC } from "@contextcompany/ai-sdk";

export const tcc = registerTCC();

Step 3: Add telemetry to AI SDK calls

app.ts

import { tccTelemetry } from "@contextcompany/ai-sdk";
import { generateText } from "ai";
import { tcc } from "./telemetry";

const result = await generateText({
  model,
  prompt: "Write a short story about a lighthouse.",
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
    },
  }),
});

process.once("SIGTERM", async () => {
  await tcc.shutdown();
  process.exit(0);
});

shutdown() is idempotent and should be treated as terminal for the current process. Call forceFlush() when you need to send queued traces without shutting down the SDK.

tcc.runId must be a UUID. Calls without an explicit run ID still receive a generated ID, but an explicit ID is recommended when you need feedback, deep links, or correlation with application data.

Adding custom metadata

Custom metadata allows you to add additional properties to your agent runs. This is useful for tying agent runs to your business logic and filtering runs by environment, feature, experiment, or another application-specific dimension. Add custom fields to the same metadata object as the reserved TCC metadata. Custom fields do not use the tcc.* namespace.

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { generateText } from "ai";

const result = await generateText({
  model,
  prompt,
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
      environment: "production",
      feature: "support-assistant",
      experiment: "concise-responses",
    },
  }),
});

Agent runs are automatically indexed by custom metadata fields and can be filtered directly in the dashboard.

The tcc.* namespace is reserved for TCC-specific metadata. Use the exact supported keys shown below. Keep application-specific fields such as environment, feature, and experiment unprefixed.

TCC metadata	Purpose
`tcc.runId`	Identifies the run. It must be a UUID.
`tcc.sessionId`	Groups related runs into a session.
`tcc.conversational`	Marks a run as direct user interaction.
`tcc.agent`	Assigns the run to a named agent.
`tcc.userId` and `tcc.userName`	Attaches first-class user identity.
`tcc.orgId` and `tcc.orgName`	Attaches first-class organization identity.

Runtime context is exported as trace metadata. Do not include secrets or sensitive values that should not appear in your observability data.

Adding user feedback

User feedback allows you to collect score (thumbs up and thumbs down) and text feedback of up to 2,000 characters from end users on your agent runs. This is useful for tracking user satisfaction, identifying problematic responses, and filtering agent runs in the dashboard by feedback.

Step 1: Generate and pass a run ID

Generate the run ID before calling the AI SDK, then return it to your client. For streamed Next.js responses, message metadata is a convenient way to preserve it.

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { streamText } from "ai";

const runId = crypto.randomUUID();

const result = streamText({
  model,
  messages,
  ...tccTelemetry({
    metadata: {
      "tcc.runId": runId,
    },
  }),
});

return result.toUIMessageStreamResponse({
  messageMetadata: () => ({ runId }),
});

Step 2: Submit feedback from your client

Store the run ID on your client, then submit feedback from a server route using submitFeedback. Both score and text are optional individually, but every request must include at least one of them. score must be either "thumbs_up" or "thumbs_down". text can contain written feedback of up to 2,000 characters.

feedback-route.ts

import { submitFeedback } from "@contextcompany/ai-sdk/nextjs";

await submitFeedback({
  runId,
  score: "thumbs_up",
  text: "This was a helpful response!",
});

Agent runs with feedback can be filtered in the dashboard using the feedback filter.

Tracking agent sessions

Agent sessions group multiple agent runs. The most common use case is tracking an entire conversation between a user and an AI agent. Pass the same tcc.sessionId to every related call:

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { generateText } from "ai";

const result = await generateText({
  model,
  prompt,
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
      "tcc.sessionId": "support-conversation-123",
    },
  }),
});

The session ID can be any stable string. A UUID is recommended when your application does not already have a conversation identifier. Agent sessions are automatically indexed and can be filtered directly in the dashboard.

Marking runs as conversational

A conversational run is an agent run initiated by a user. Marking a run as conversational tells The Context Company that it represents direct user interaction. Conversational runs are monitored for user insights such as confusion and frustration. Background jobs, cron tasks, and internal automations should generally remain non-conversational. Set tcc.conversational to true in metadata:

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";

const tracking = tccTelemetry({
  metadata: {
    "tcc.runId": crypto.randomUUID(),
    "tcc.conversational": true,
  },
});

Identifying the agent

If your product ships more than one named agent, set tcc.agent to scope the run to a specific agent. The dashboard’s agent selector, per-agent patterns and recaps, and the agent filter on the REST API and MCP tools read from this value.

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";

const tracking = tccTelemetry({
  metadata: {
    "tcc.runId": crypto.randomUUID(),
    "tcc.agent": "support-agent",
  },
});

Agent names that collide with reserved dashboard routes (for example runs, sessions, patterns, recaps, overview, search, failures, feedback, tools, topics, views, settings, and mcp-and-api) are dropped.

Identifying users and organizations

Attach the end user and their organization to a run as first-class identity using tcc.userId, tcc.userName, tcc.orgId, and tcc.orgName. These fields are different from similarly named custom metadata. They enable dedicated dashboard filters, user and organization search, per-user views, and per-organization analytics. See User and organization identity for the full concept. Set these fields whenever you have a stable identifier for the user or organization:

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";

const tracking = tccTelemetry({
  metadata: {
    "tcc.runId": crypto.randomUUID(),
    "tcc.userId": "user-123",
    "tcc.userName": "Jane Doe",
    "tcc.orgId": "org-456",
    "tcc.orgName": "Acme Inc.",
  },
});

tcc.userName and tcc.orgName require the corresponding tcc.userId or tcc.orgId. Names without IDs are dropped.

Combining multiple options

You can add all TCC tracking fields and custom metadata through one tccTelemetry call:

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { streamText } from "ai";

const runId = crypto.randomUUID();

const result = streamText({
  model,
  messages,
  ...tccTelemetry({
    metadata: {
      "tcc.runId": runId,
      "tcc.sessionId": "support-conversation-123",
      "tcc.conversational": true,
      "tcc.agent": "support-agent",
      "tcc.userId": "user-123",
      "tcc.userName": "Jane Doe",
      "tcc.orgId": "org-456",
      "tcc.orgName": "Acme Inc.",
      environment: "production",
      feature: "support-assistant",
    },
  }),
});

tccTelemetry adds every supplied field to runtime context and includes it in AI SDK 7 telemetry. TCC-specific fields always retain their tcc.* prefix.

Multi-step agents and tools

No additional tracing code is required for tools or multi-step agents. AI SDK 7 emits the root agent operation, every model call, and every tool execution through the integration registered by registerTCC.

route.ts

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { isStepCount, streamText, tool } from "ai";
import { z } from "zod";

const result = streamText({
  model,
  prompt: "What is the weather in San Francisco?",
  tools: {
    getWeather: tool({
      description: "Get the weather for a city",
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, temperature: 68 }),
    }),
  },
  stopWhen: isStepCount(5),
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
      "tcc.agent": "weather-assistant",
    },
  }),
});

The resulting trace contains:

One agent run for the full operation
One model step for every chat operation
One tool-call record for every execute_tool operation
Token usage, cached tokens, model IDs, finish reasons, errors, and aborts

Structured output, embeddings, and reranking use the same registerTCC and tccTelemetry setup. Embedding and reranking input and output values are enabled by the TCC integration.

Debug mode

Enable debug mode to log span creation, batching, and export lifecycle information while validating an integration.

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerTCC } = await import("@contextcompany/ai-sdk/nextjs");
    registerTCC({ debug: true });
  }
}

import { registerTCC } from "@contextcompany/ai-sdk";

export const tcc = registerTCC({ debug: true });

For a custom development endpoint, pass url to the Next.js entry point or otlpUrl to the Node.js entry point.

registerTCC({
  url: "http://localhost:8787/v1/traces",
});

registerTCC({
  otlpUrl: "http://localhost:8787/v1/traces",
});

Examples

See the Next.js AI SDK 7 example for a complete streaming agent with tools, sessions, users, organizations, custom metadata, and feedback. If you are upgrading an existing application, follow Migrate to AI SDK 7.

Local mode

Local mode allows you to run The Context Company in a local-first mode. It is 100% open-source and requires no account or API key. We also offer a free, cloud development environment for all users. Local mode demonstration

Setup

Step 1: Install dependencies

pnpm add @contextcompany/ai-sdk ai @opentelemetry/api

npm i @contextcompany/ai-sdk ai @opentelemetry/api

bun add @contextcompany/ai-sdk ai @opentelemetry/api

Step 2: Add instrumentation to Next.js

Add an instrumentation.[js|ts] file to your project root, or inside src if your application uses a src directory. Register TCC with local: true.

instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerTCC } = await import("@contextcompany/ai-sdk/nextjs");
    registerTCC({ local: true });
  }
}

Add the Local Mode widget to your root layout:

app/layout.tsx

import Script from "next/script";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <Script
          crossOrigin="anonymous"
          src="//unpkg.com/@contextcompany/widget/dist/auto.global.js"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Step 4: Add telemetry to AI SDK calls

Use tccTelemetry exactly as you would in production:

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { generateText } from "ai";

const result = await generateText({
  model,
  prompt,
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
    },
  }),
});

import { tccTelemetry } from "@contextcompany/ai-sdk/nextjs";
import { streamText } from "ai";

const result = streamText({
  model,
  prompt,
  ...tccTelemetry({
    metadata: {
      "tcc.runId": crypto.randomUUID(),
    },
  }),
});

Anonymous telemetry

By default, The Context Company collects limited anonymous usage data when running local mode. This helps us understand how developers use the tool and guides improvements. No sensitive or personally identifiable information is collected. You can view the exact events and values tracked in the Observatory repository. To disable anonymous telemetry, set TCC_DISABLE_ANONYMOUS_TELEMETRY to true in your Next.js project.

Getting started

Supported frameworks

Custom Instrumentation

Monitoring

Integrations

Security

AI SDK 7

AI SDK 5–6

Set TCC environment variables

Instrument AI SDK

Step 1: Install dependencies

Step 2: Add instrumentation to Next.js

Step 3: Add telemetry to AI SDK calls

Step 1: Install dependencies

Step 2: Register the integration

Step 3: Add telemetry to AI SDK calls

Adding custom metadata

Adding user feedback

Step 1: Generate and pass a run ID

Step 2: Submit feedback from your client

Tracking agent sessions

Marking runs as conversational

Identifying the agent

Identifying users and organizations

Combining multiple options

Multi-step agents and tools

Debug mode

Examples

Local mode

Setup

Step 1: Install dependencies

Step 2: Add instrumentation to Next.js

Step 3: Add widget to layout

Step 4: Add telemetry to AI SDK calls

Anonymous telemetry

AI SDK 7

AI SDK 5–6

​Set TCC environment variables

​Instrument AI SDK

​Step 1: Install dependencies

​Step 2: Add instrumentation to Next.js

​Step 3: Add telemetry to AI SDK calls

​Step 1: Install dependencies

​Step 2: Register the integration

​Step 3: Add telemetry to AI SDK calls

​Adding custom metadata

​Adding user feedback

​Step 1: Generate and pass a run ID

​Step 2: Submit feedback from your client

​Tracking agent sessions

​Marking runs as conversational

​Identifying the agent

​Identifying users and organizations

​Combining multiple options

​Multi-step agents and tools

​Debug mode

​Examples

​Local mode

​Setup

​Step 1: Install dependencies

​Step 2: Add instrumentation to Next.js

​Step 3: Add widget to layout

​Step 4: Add telemetry to AI SDK calls

​Anonymous telemetry

Set TCC environment variables

Instrument AI SDK

Step 1: Install dependencies

Step 2: Add instrumentation to Next.js

Step 3: Add telemetry to AI SDK calls

Step 1: Install dependencies

Step 2: Register the integration

Step 3: Add telemetry to AI SDK calls

Adding custom metadata

Adding user feedback

Step 1: Generate and pass a run ID

Step 2: Submit feedback from your client

Tracking agent sessions

Marking runs as conversational

Identifying the agent

Identifying users and organizations

Combining multiple options

Multi-step agents and tools

Debug mode

Examples

Local mode

Setup

Step 1: Install dependencies

Step 2: Add instrumentation to Next.js

Step 3: Add widget to layout

Step 4: Add telemetry to AI SDK calls

Anonymous telemetry