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

# Vercel AI SDK

> Instrument the Vercel AI SDK for LLM observability

This guide covers how to instrument the Vercel AI SDK for monitoring LLM calls, token usage, and costs. You will learn how to:

* Install and configure the instrumentation
* Track AI operations (generateText, streamText, etc.)
* Group calls into conversations

For the full list of required span attributes and what powers the AI dashboard, see the [AI Agents feature page](/features/ai-agents).

## Installation

```bash theme={"theme":"vesper"}
npm install @monocle.sh/instrumentation-vercel-ai
```

**Peer dependency:** `ai >= 3.0.0 < 7`

## Usage

The instrumentation has two parts: the `VercelAiInstrumentation` that hooks into the AI SDK to enable telemetry, and the `VercelAiSpanProcessor` that normalizes span attributes to [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).

```typescript title="instrumentation.ts" theme={"theme":"vesper"}
import { VercelAiInstrumentation, VercelAiSpanProcessor } from "@monocle.sh/instrumentation-vercel-ai";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

// Add the span processor to your tracer provider
const provider = new NodeTracerProvider();
provider.addSpanProcessor(new VercelAiSpanProcessor());

// Enable auto-instrumentation
const instrumentation = new VercelAiInstrumentation();
instrumentation.enable();
```

Once enabled, all `generateText`, `streamText`, `generateObject`, `streamObject`, `embed`, `embedMany`, and `rerank` calls are automatically instrumented.

```typescript title="example.ts" theme={"theme":"vesper"}
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

// This automatically creates spans with token usage, model info, etc.
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "What is observability?",
});
```

## Configuration

```typescript theme={"theme":"vesper"}
const instrumentation = new VercelAiInstrumentation({
  // Record prompt/input data in spans (default: true)
  recordInputs: true,

  // Record response/output data in spans (default: true)
  recordOutputs: true,
});
```

You can also control recording per call via the AI SDK's `experimental_telemetry` option. Per-call settings take priority over the global config.

## Conversation tracking

Use `withConversationId()` to group multiple AI calls into a single conversation. This sets `gen_ai.conversation.id` on all spans created within the callback, enabling the Conversations tab in the Monocle AI dashboard.

```typescript title="chat.ts" theme={"theme":"vesper"}
import { withConversationId, getConversationId } from "@monocle.sh/instrumentation-vercel-ai";

await withConversationId("conv-abc-123", async () => {
  // All AI calls here share the same conversation ID
  const response = await generateText({
    model: openai("gpt-4o"),
    prompt: userMessage,
  });

  // You can also read the current conversation ID
  const currentId = getConversationId(); // "conv-abc-123"
});
```

## Spans

The instrumentation does not create spans directly. It enables the Vercel AI SDK's built-in telemetry and processes those spans through the `VercelAiSpanProcessor` to normalize attributes.

### Pipeline spans

A span is created for each top-level AI call (`generateText`, `streamText`, etc.). The span name is normalized to `{operation} {functionId}` (e.g., `invoke_agent weather-app`).

### Inner LLM call spans

A child span is created for the actual LLM API call. The span name is `{operation} {modelId}` (e.g., `generate_text gpt-4o`).

### Tool call spans

Each tool invocation creates a span named `execute_tool {toolName}`. The instrumentation also detects Vercel AI SDK v5 tool errors embedded in result content and records them as exceptions on the corresponding span.

## Vercel AI-specific attributes

In addition to the [standard AI attributes](/features/ai-agents#span-attributes), the Vercel AI instrumentation emits these extra attributes.

### Input/output attributes (when recording is enabled)

| Attribute                    | Description           |
| ---------------------------- | --------------------- |
| `gen_ai.system_instructions` | System prompt text    |
| `gen_ai.input.messages`      | Input messages (JSON) |
| `gen_ai.response.text`       | Generated text        |
| `gen_ai.response.tool_calls` | Tool calls made       |
| `gen_ai.response.object`     | Generated object      |
| `gen_ai.tool.input`          | Tool arguments        |
| `gen_ai.tool.output`         | Tool result           |

### Provider-specific token breakdowns

The processor extracts detailed token metrics from provider metadata when available:

| Attribute                               | Providers                            |
| --------------------------------------- | ------------------------------------ |
| `gen_ai.usage.input_tokens.cached`      | OpenAI, Anthropic, Bedrock, DeepSeek |
| `gen_ai.usage.input_tokens.cache_write` | Anthropic, Bedrock                   |
| `gen_ai.usage.input_tokens.cache_miss`  | DeepSeek                             |
| `gen_ai.usage.output_tokens.reasoning`  | OpenAI                               |

### Vercel AI SDK native attributes

Remaining Vercel-native attributes are preserved under the `vercel.ai.*` namespace (e.g., `vercel.ai.response.msToFirstChunk`, `vercel.ai.response.avgOutputTokensPerSecond`).