Vercel AI SDK

Choose a setup method

Method	Use it when
Agnost AI skill	You want your coding agent to inspect the app, make the change, and verify it.
Agnost AI SDK	You want explicit control over the interaction boundaries and fields.
OpenTelemetry	The framework already emits useful spans or you operate an OTel pipeline.

Start with one method for a call path. Combining SDK tracking with framework OpenTelemetry on the same call can create duplicate interactions.

Recommended: Agnost AI skill

Recommended. Choose this path when you want your coding agent to inspect the project, select a supported transport, make the smallest instrumentation change, send a test event, and verify that it reached Agnost AI.

Install the skill once in your coding-agent environment:

npx skills add AgnostAI/skills --skill agnost-ai

Run the framework-specific prompt below from the application root. Review the resulting diff before deploying it.

Use the agnost-ai skill to add Agnost AI analytics to this Vercel AI SDK application.
Org ID: your-org-id
Instrument the real generateText() or streamText() path and verify one fresh interaction.

Manual setup: Agnost AI SDK

npm install agnostai

import { generateText } from 'ai';
import * as agnost from 'agnostai';

agnost.init('your-org-id');
const interaction = agnost.begin({ userId: 'u-42', agentName: 'vercel-ai-support', input: prompt });
if (!interaction) throw new Error('Agnost is not initialized. Call agnost.init() first.');
try {
  const { text } = await generateText({ model, prompt });
  interaction.end(text);
} catch (error) {
  interaction.end(String(error), false);
  throw error;
}

Call await agnost.shutdown() once when the application exits, not after each request.

Manual setup: OpenTelemetry

The Vercel AI SDK emits ai.* and GenAI semantic-convention spans through its OpenTelemetry integration. Wire an OTel exporter pointing at Agnost AI, register the integration once, then explicitly include userId / sessionId from the call’s runtime context.

1. Install

Already have @opentelemetry/sdk-node (or another OTel SDK) and an OTLP exporter? Install only @ai-sdk/otel if it is missing. No OTel set up yet?

npm install ai @ai-sdk/otel @opentelemetry/sdk-node \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto

2. Wire the OTel exporter pointing at Agnost AI

Already exporting OTel? Include the Agnost processor in the spanProcessors array when constructing the existing NodeSDK or NodeTracerProvider.

import { NodeSDK } from '@opentelemetry/sdk-node';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { registerTelemetry } from 'ai';
import { OpenTelemetry } from '@ai-sdk/otel';

const agnostProcessor = new BatchSpanProcessor(
  new OTLPTraceExporter({
    url: 'https://otel.agnost.ai/v1/traces',
    headers: { 'X-Agnost-Org-ID': process.env.AGNOST_ORG_ID! },
  }),
);

const sdk = new NodeSDK({
  spanProcessors: [
    // ...your existing processors,
    agnostProcessor,
  ],
});
sdk.start();
registerTelemetry(new OpenTelemetry({ runtimeContext: true }));

No OTel yet? Boot a NodeSDK at startup (e.g. Next.js instrumentation.ts):

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { registerTelemetry } from 'ai';
import { OpenTelemetry } from '@ai-sdk/otel';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'https://otel.agnost.ai/v1/traces',
    headers: { 'X-Agnost-Org-ID': process.env.AGNOST_ORG_ID! },
  }),
});
sdk.start();

registerTelemetry(new OpenTelemetry({ runtimeContext: true }));

3. Pass userId / sessionId per call

import { generateText } from 'ai';

await generateText({
  model, // your existing AI SDK provider model
  prompt: 'Hello',
  runtimeContext: {
    userId: 'user-42',
    sessionId: 'conv-abc123',
  },
  telemetry: {
    isEnabled: true,
    includeRuntimeContext: {
      userId: true,
      sessionId: true,
    },
  },
});

AI SDK 7 excludes runtime context from telemetry unless each safe field is listed in includeRuntimeContext. Keep secrets and sensitive request context out of that allowlist.

What appears in Agnost AI

Conversations grouped by sessionId.
User-level analytics grouped by userId.
Events for every generated span.

Verify

Run one generateText call, then open Events in Agnost AI. If the event is present, check Conversations for session grouping.

Troubleshooting

Confirm registerTelemetry(new OpenTelemetry(...)) runs once at startup.
Confirm telemetry.isEnabled is true and the grouping fields appear in includeRuntimeContext.
Confirm the OTLP exporter is initialized before the first AI SDK call.
Confirm X-Agnost-Org-ID is set on the exporter.

References

Next steps

Conversations: review the complete Vercel AI SDK interaction.
Events: inspect generated model and tool spans.
Intents: organize production conversations by what users wanted.

Getting started

Agent frameworks

Voice agents

Custom applications

MCP server analytics

Platforms

Choose a setup method

Recommended: Agnost AI skill

Manual setup: Agnost AI SDK

Manual setup: OpenTelemetry

1. Install

2. Wire the OTel exporter pointing at Agnost AI

3. Pass userId / sessionId per call

What appears in Agnost AI

Verify

Troubleshooting

References

Next steps

​Choose a setup method

​Recommended: Agnost AI skill

​Manual setup: Agnost AI SDK

​Manual setup: OpenTelemetry

​1. Install

​2. Wire the OTel exporter pointing at Agnost AI

​3. Pass userId / sessionId per call

​What appears in Agnost AI

​Verify

​Troubleshooting

​References

​Next steps

Choose a setup method

Recommended: Agnost AI skill

Manual setup: Agnost AI SDK

Manual setup: OpenTelemetry

1. Install

2. Wire the OTel exporter pointing at Agnost AI

3. Pass userId / sessionId per call

What appears in Agnost AI

Verify

Troubleshooting

References

Next steps