Get Started
Agent frameworks

Vercel AI SDK

Capture traces from the Vercel AI SDK with experimental_telemetry

Choose a setup method

Method Use it when
Voxmith skill You want your coding agent to inspect the app, make the change, and verify it.
Voxmith 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. 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 Voxmith.

Install the skill once in your coding-agent environment:

npx skills add Voxmith/skills --skill voxmith

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

Use the voxmith skill to add Voxmith 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: Voxmith SDK

npm install voxmithai
import { generateText } from 'ai';
import * as voxmith from 'voxmithai';

voxmith.init('your-org-id');
const interaction = voxmith.begin({ userId: 'u-42', agentName: 'vercel-ai-support', input: prompt });
try {
  const { text } = await generateText({ model, prompt });
  interaction.end(text);
} catch (error) {
  interaction.end(String(error), false);
  throw error;
} finally {
  await voxmith.shutdown();
}

Manual setup: OpenTelemetry

The Vercel AI SDK emits ai.* spans natively. Wire an OTel exporter pointing at Voxmith, then enable telemetry per call with userId / sessionId.

1. Install

Already have @opentelemetry/sdk-node (or another OTel SDK) and @opentelemetry/exporter-trace-otlp-proto? Skip: you only need the existing packages.

No OTel set up yet?

npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto

2. Wire the OTel exporter pointing at Voxmith

Already exporting OTel? Append Voxmith as an additional span processor on your existing TracerProvider:

import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

provider.addSpanProcessor(
  new BatchSpanProcessor(
    new OTLPTraceExporter({
      url: 'https://otel.voxmith.com/v1/traces',
      headers: { 'X-Voxmith-Org-ID': process.env.VOXMITH_ORG_ID! },
    }),
  ),
);

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';

new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'https://otel.voxmith.com/v1/traces',
    headers: { 'X-Voxmith-Org-ID': process.env.VOXMITH_ORG_ID! },
  }),
}).start();

3. Pass userId / sessionId per call

import { generateText } from 'ai';

await generateText({
  model: openai('gpt-4o'),
  prompt: 'Hello',
  experimental_telemetry: {
    isEnabled: true,
    metadata: {
      userId: 'user-42',
      sessionId: 'conv-abc123',
    },
  },
});

experimental_telemetry.isEnabled defaults to false: set it per call.

What appears in Voxmith

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

Verify

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

Troubleshooting

  • Confirm experimental_telemetry.isEnabled is true on the call.
  • Confirm the OTLP exporter is initialized before the first AI SDK call.
  • Confirm X-Voxmith-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.