> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agnost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK

> Capture traces from the Vercel AI SDK with experimental_telemetry

## 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

<Note>
  **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.
</Note>

Install the skill once in your coding-agent environment:

```bash theme={null}
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.

```text theme={null}
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

```bash theme={null}
npm install agnostai
```

```typescript theme={null}
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 });
try {
  const { text } = await generateText({ model, prompt });
  interaction.end(text);
} catch (error) {
  interaction.end(String(error), false);
  throw error;
} finally {
  await agnost.shutdown();
}
```

## Manual setup: OpenTelemetry

The Vercel AI SDK emits `ai.*` spans natively. Wire an OTel exporter pointing at Agnost AI, 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?**

```bash theme={null}
npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto
```

### 2. Wire the OTel exporter pointing at Agnost AI

**Already exporting OTel?** Append Agnost AI as an additional span processor on your existing TracerProvider:

```typescript theme={null}
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

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

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

```typescript theme={null}
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';

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

### 3. Pass userId / sessionId per call

```typescript theme={null}
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 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 `experimental_telemetry.isEnabled` is `true` on the call.
* Confirm the OTLP exporter is initialized before the first AI SDK call.
* Confirm `X-Agnost-Org-ID` is set on the exporter.

### References

* [Vercel AI SDK telemetry](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)
* [Add custom metadata](https://ai-sdk.dev/docs/ai-sdk-core/telemetry#telemetry-metadata)

## Next steps

* [Conversations](/using-conversations): review the complete Vercel AI SDK interaction.
* [Events](/using-events): inspect generated model and tool spans.
* [Intents](/using-intents): organize production conversations by what users wanted.