Vercel AI SDK

Set environment variables#

Our SDKs default to using the TCC_API_KEY environment variable.

TCC_API_KEY="your-api-key"

Instrument AI SDK (Next.js)#

Step 1: Install dependencies

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

Step 2: Add instrumentation to Next.js

Add an instrumentation.ts file to your project root (or src/). Call registerTCC once when the Node.js runtime starts — it's idempotent, so dev reloads don't register duplicate integrations.

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. TCC-specific fields use the tcc.* namespace and live in the same metadata object as your own custom fields.

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

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 fields live in the same metadata object as reserved TCC metadata but don't use the tcc.* namespace:

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.

Adding user feedback#

Collect thumbs up/down and up to 2,000 characters of text feedback from end users on your agent runs.

Step 1 — generate and pass a run ID. Generate it before calling the AI SDK, then preserve it through message metadata for streamed responses:

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, via a server route with submitFeedback:

import { submitFeedback } from "@contextcompany/ai-sdk/nextjs";
 
await submitFeedback({
  runId,
  score: "thumbs_up",
  text: "This was a helpful response!",
});

score (thumbs_up | thumbs_down) and text are each optional individually, but a request needs at least one. Runs with feedback can be filtered in the dashboard.

Tracking sessions, conversational runs, agents, and identity#

Pass the same tcc.sessionId to every call in a conversation to group them into one session. Set tcc.conversational: true on runs a real user initiated — cron jobs and internal automations should stay non-conversational. Set tcc.agent when your product ships more than one named agent. Set tcc.userId/tcc.userName/tcc.orgId/tcc.orgName to attach first-class user and organization identity.

const tracking = tccTelemetry({
  metadata: {
    "tcc.runId": crypto.randomUUID(),
    "tcc.sessionId": "support-conversation-123",
    "tcc.conversational": true,
    "tcc.agent": "support-agent",
    "tcc.userId": "user-123",
    "tcc.orgId": "org-456",
  },
});

See Concepts for the full reference on runs, sessions, agents, and identity.