From 96667ecaf1141997524e4cbdbfa9d69cc6f01c01 Mon Sep 17 00:00:00 2001 From: Hassieb Pakzad <68423100+hassiebp@users.noreply.github.com> Date: Fri, 26 Jun 2026 17:01:22 +0200 Subject: [PATCH] docs: update Vercel AI SDK 7 integration --- components-mdx/get-started/vercel-ai-sdk.mdx | 25 ++--- .../2026-06-18-vercel-ai-sdk-v7-beta.mdx | 6 ++ .../changelog/2026-06-26-vercel-ai-sdk-7.mdx | 91 +++++++++++++++++++ .../integrations/frameworks/vercel-ai-sdk.mdx | 20 ++-- cookbook/js_integration_vercel_ai_sdk.ipynb | 20 ++-- 5 files changed, 130 insertions(+), 32 deletions(-) create mode 100644 content/changelog/2026-06-26-vercel-ai-sdk-7.mdx diff --git a/components-mdx/get-started/vercel-ai-sdk.mdx b/components-mdx/get-started/vercel-ai-sdk.mdx index 8b8cec965..cb236cfe2 100644 --- a/components-mdx/get-started/vercel-ai-sdk.mdx +++ b/components-mdx/get-started/vercel-ai-sdk.mdx @@ -1,14 +1,9 @@ **Install packages** -The quickstart below is for the current stable Vercel AI SDK setup. If you are -adopting the AI SDK v7 beta, use -[`@langfuse/vercel-ai-sdk@beta`](/integrations/frameworks/vercel-ai-sdk#ai-sdk-v7-beta) -instead. - -Install the Vercel AI SDK, OpenTelemetry, and the Langfuse integration packages. +Install AI SDK 7, OpenTelemetry, and the Langfuse integration packages. ```bash -npm install ai @ai-sdk/openai @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node +npm install ai @ai-sdk/openai @langfuse/vercel-ai-sdk @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node ``` **Add credentials** @@ -21,30 +16,36 @@ import EnvJS from "@/components-mdx/env-js.mdx"; **Initialize OpenTelemetry with Langfuse** -Set up the OpenTelemetry SDK with the Langfuse span processor. This captures telemetry data from the Vercel AI SDK and sends it to Langfuse. +Set up the OpenTelemetry SDK with the Langfuse span processor and register the Langfuse Vercel AI SDK telemetry integration once at application startup. ```typescript +import { registerTelemetry } from "ai"; import { NodeSDK } from "@opentelemetry/sdk-node"; import { LangfuseSpanProcessor } from "@langfuse/otel"; +import { LangfuseVercelAiSdkIntegration } from "@langfuse/vercel-ai-sdk"; const sdk = new NodeSDK({ spanProcessors: [new LangfuseSpanProcessor()], }); sdk.start(); + +registerTelemetry(new LangfuseVercelAiSdkIntegration()); ``` -**Enable telemetry in your AI SDK calls** +**Run AI SDK calls** -Pass `experimental_telemetry: { isEnabled: true }` to your AI SDK functions. The AI SDK automatically creates telemetry spans, which the `LangfuseSpanProcessor` captures and sends to Langfuse. +After telemetry is registered, AI SDK 7 emits telemetry by default. Use `telemetry` to set a function name, include selected runtime context keys, or opt out of telemetry for a specific call. ```typescript import { generateText } from "ai"; import { openai } from "@ai-sdk/openai"; const { text } = await generateText({ - model: openai("gpt-4o"), + model: openai("gpt-5.1"), prompt: "What is the weather like today?", - experimental_telemetry: { isEnabled: true }, + telemetry: { + functionId: "weather-chat", + }, }); ``` diff --git a/content/changelog/2026-06-18-vercel-ai-sdk-v7-beta.mdx b/content/changelog/2026-06-18-vercel-ai-sdk-v7-beta.mdx index c76a65534..633a886f2 100644 --- a/content/changelog/2026-06-18-vercel-ai-sdk-v7-beta.mdx +++ b/content/changelog/2026-06-18-vercel-ai-sdk-v7-beta.mdx @@ -11,6 +11,12 @@ import { Book, Package } from "lucide-react"; + + AI SDK 7 and `@langfuse/vercel-ai-sdk` are now generally available. Use the + current [Vercel AI SDK integration docs](/integrations/frameworks/vercel-ai-sdk) + for new projects. + + Langfuse now ships a beta telemetry integration for the Vercel AI SDK v7 beta. Install `@langfuse/vercel-ai-sdk@beta` with `ai@beta`, keep the regular Langfuse OpenTelemetry exporter setup in place, and register `LangfuseVercelAiSdkIntegration` once. AI SDK calls then emit OpenTelemetry spans that Langfuse maps into traces, generations, tool calls, embeddings, and reranks. Use it to migrate a chat or agent route to AI SDK v7 beta while keeping Langfuse user IDs, sessions, tags, and trace metadata via `propagateAttributes`. You can also attach route or feature metadata through `runtimeContext`, and link Langfuse Prompt Management versions to model-call observations with `runtimeContext.langfusePrompt`. diff --git a/content/changelog/2026-06-26-vercel-ai-sdk-7.mdx b/content/changelog/2026-06-26-vercel-ai-sdk-7.mdx new file mode 100644 index 000000000..fec75c074 --- /dev/null +++ b/content/changelog/2026-06-26-vercel-ai-sdk-7.mdx @@ -0,0 +1,91 @@ +--- +date: 2026-06-26 +title: Trace AI SDK 7 with Langfuse +description: Use @langfuse/vercel-ai-sdk 5.9.0 to trace Vercel AI SDK 7 calls in Langfuse. +author: Hassieb +canonical: /integrations/frameworks/vercel-ai-sdk +--- + +import { ChangelogHeader } from "@/components/changelog/ChangelogHeader"; +import { Book, Package } from "lucide-react"; + + + +AI SDK 7 is generally available, and the Langfuse Vercel AI SDK integration is stable as of `@langfuse/vercel-ai-sdk@5.9.0`. Register `LangfuseVercelAiSdkIntegration` once with the AI SDK telemetry registry and keep exporting spans through the Langfuse OpenTelemetry span processor. + +The stable setup uses the regular `latest` npm tags: + +```bash +npm install ai @ai-sdk/openai @langfuse/client @langfuse/vercel-ai-sdk @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node +``` + +```typescript filename="instrumentation.ts" +import { registerTelemetry } from "ai"; +import { LangfuseSpanProcessor } from "@langfuse/otel"; +import { LangfuseVercelAiSdkIntegration } from "@langfuse/vercel-ai-sdk"; +import { NodeSDK } from "@opentelemetry/sdk-node"; + +const sdk = new NodeSDK({ + spanProcessors: [new LangfuseSpanProcessor()], +}); + +sdk.start(); + +registerTelemetry(new LangfuseVercelAiSdkIntegration()); +``` + +```typescript filename="app.ts" +import "./instrumentation"; + +import { generateText } from "ai"; +import { openai } from "@ai-sdk/openai"; +import { LangfuseClient } from "@langfuse/client"; +import { propagateAttributes } from "@langfuse/tracing"; + +const langfuseClient = new LangfuseClient(); +const langfusePrompt = await langfuseClient.getPrompt("support-chat/default"); + +await propagateAttributes( + { + traceName: "support-chat", + userId: "user-123", + sessionId: "session-456", + tags: ["production", "chat"], + }, + () => + generateText({ + model: openai("gpt-5.1"), + prompt: langfusePrompt.compile({ topic: "RAG" }), + runtimeContext: { + route: "support-chat", + langfusePrompt, + }, + telemetry: { + functionId: "support-chat", + includeRuntimeContext: { + route: true, + langfusePrompt: true, + }, + }, + }), +); +``` + +If you adopted the beta integration, remove the `@beta` tags from your AI SDK and Langfuse packages. The runtime shape stays the same: AI SDK 7 emits telemetry after registration, while `runtimeContext` keys must be explicitly included with `telemetry.includeRuntimeContext`. + +## Get started + + + } + arrow + /> + } + arrow + /> + diff --git a/content/integrations/frameworks/vercel-ai-sdk.mdx b/content/integrations/frameworks/vercel-ai-sdk.mdx index bdbb96027..1aa5f0d9c 100644 --- a/content/integrations/frameworks/vercel-ai-sdk.mdx +++ b/content/integrations/frameworks/vercel-ai-sdk.mdx @@ -26,18 +26,18 @@ This notebook demonstrates how to **integrate Langfuse** with the **Vercel AI SD > **What is Langfuse?**: [Langfuse](https://langfuse.com/) is an open-source observability platform for AI agents and LLM applications. It helps you visualize and monitor LLM calls, tool usage, cost, latency, and more. -> **How do they work together?** The Vercel AI SDK has built-in telemetry based on [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/). Langfuse also uses OpenTelemetry, which means they integrate seamlessly. For the AI SDK v7 beta, register the Langfuse telemetry integration with the AI SDK and export spans with the Langfuse span processor. For the current stable AI SDK, enable `experimental_telemetry` on the calls you want to trace. +> **How do they work together?** The Vercel AI SDK has built-in telemetry based on [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/). Langfuse also uses OpenTelemetry, which means they integrate seamlessly. For AI SDK 7, register the Langfuse telemetry integration with the AI SDK and export spans with the Langfuse span processor. For AI SDK v6, enable `experimental_telemetry` on the calls you want to trace. -## AI SDK v7 beta [#ai-sdk-v7-beta] +## AI SDK 7 [#ai-sdk-7] -The AI SDK v7 beta uses a callback-based telemetry system. Install the Langfuse-owned telemetry integration together with the AI SDK beta packages: +AI SDK 7 uses a callback-based telemetry system. Install the Langfuse-owned telemetry integration together with the AI SDK 7 packages: ```bash -npm install ai@beta @ai-sdk/openai@beta @langfuse/client@beta @langfuse/vercel-ai-sdk@beta @langfuse/tracing@beta @langfuse/otel@beta @opentelemetry/sdk-node +npm install ai @ai-sdk/openai @langfuse/client @langfuse/vercel-ai-sdk @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node zod ``` - The `@langfuse/vercel-ai-sdk` package targets the AI SDK v7 beta line and requires Node.js 22 or later. Keep the AI SDK and Langfuse packages on their `@beta` tags while adopting this integration. + The `@langfuse/vercel-ai-sdk` package targets AI SDK 7 and requires Node.js 22 or later. Use the AI SDK v6 legacy setup below if you cannot upgrade yet. @@ -58,7 +58,7 @@ sdk.start(); registerTelemetry(new LangfuseVercelAiSdkIntegration()); ``` -In the file that runs your AI SDK calls, import `instrumentation.ts` first. After the integration is registered, AI SDK v7 emits telemetry by default. Use `telemetry` to set the function name, include selected runtime context keys, or opt out of telemetry for a specific call. +In the file that runs your AI SDK calls, import `instrumentation.ts` first. After the integration is registered, AI SDK 7 emits telemetry by default. Use `telemetry` to set the function name, include selected runtime context keys, or opt out of telemetry for a specific call. ```typescript filename="app.ts" import "./instrumentation"; @@ -113,15 +113,15 @@ const { text } = await propagateAttributes( ); ``` -AI SDK v7 excludes `runtimeContext` from telemetry events unless each top-level key is explicitly included. Langfuse maps included runtime context keys to observation metadata, except `langfusePrompt`, which links Langfuse Prompt Management versions to model-call observations. +AI SDK 7 excludes `runtimeContext` from telemetry events unless each top-level key is explicitly included. Langfuse maps included runtime context keys to observation metadata, except `langfusePrompt`, which links Langfuse Prompt Management versions to model-call observations. To disable telemetry for one call, set `telemetry: { isEnabled: false }`. -## AI SDK v6 and current stable setup +## AI SDK v6 legacy setup ### TL;DR -Here's the flow of how Langfuse and the stable Vercel AI SDK integration work together: +Here's the flow of how Langfuse and the legacy AI SDK v6 integration work together: 1. **You enable telemetry** in the AI SDK (`experimental_telemetry: { isEnabled: true }`) 2. **The AI SDK creates spans** for each operation (model calls, tool executions, etc.) @@ -130,7 +130,7 @@ Here's the flow of how Langfuse and the stable Vercel AI SDK integration work to This integration uses [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/), an observability standard. The Vercel AI SDK's telemetry feature is documented in the [Vercel AI SDK documentation on Telemetry](https://ai-sdk.dev/docs/ai-sdk-core/telemetry). -Let's walk through the stable setup in more detail. +Let's walk through the legacy AI SDK v6 setup in more detail. diff --git a/cookbook/js_integration_vercel_ai_sdk.ipynb b/cookbook/js_integration_vercel_ai_sdk.ipynb index 3173a219a..24bdf39f5 100644 --- a/cookbook/js_integration_vercel_ai_sdk.ipynb +++ b/cookbook/js_integration_vercel_ai_sdk.ipynb @@ -26,18 +26,18 @@ "\n", "> **What is Langfuse?**: [Langfuse](https://langfuse.com/) is an open-source observability platform for AI agents and LLM applications. It helps you visualize and monitor LLM calls, tool usage, cost, latency, and more.\n", "\n", - "> **How do they work together?** The Vercel AI SDK has built-in telemetry based on [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/). Langfuse also uses OpenTelemetry, which means they integrate seamlessly. For the AI SDK v7 beta, register the Langfuse telemetry integration with the AI SDK and export spans with the Langfuse span processor. For the current stable AI SDK, enable `experimental_telemetry` on the calls you want to trace.\n", + "> **How do they work together?** The Vercel AI SDK has built-in telemetry based on [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/). Langfuse also uses OpenTelemetry, which means they integrate seamlessly. For AI SDK 7, register the Langfuse telemetry integration with the AI SDK and export spans with the Langfuse span processor. For AI SDK v6, enable `experimental_telemetry` on the calls you want to trace.\n", "\n", - "## AI SDK v7 beta [#ai-sdk-v7-beta]\n", + "## AI SDK 7 [#ai-sdk-7]\n", "\n", - "The AI SDK v7 beta uses a callback-based telemetry system. Install the Langfuse-owned telemetry integration together with the AI SDK beta packages:\n", + "AI SDK 7 uses a callback-based telemetry system. Install the Langfuse-owned telemetry integration together with the AI SDK 7 packages:\n", "\n", "```bash\n", - "npm install ai@beta @ai-sdk/openai@beta @langfuse/client@beta @langfuse/vercel-ai-sdk@beta @langfuse/tracing@beta @langfuse/otel@beta @opentelemetry/sdk-node\n", + "npm install ai @ai-sdk/openai @langfuse/client @langfuse/vercel-ai-sdk @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node zod\n", "```\n", "\n", "\n", - " The `@langfuse/vercel-ai-sdk` package targets the AI SDK v7 beta line and requires Node.js 22 or later. Keep the AI SDK and Langfuse packages on their `@beta` tags while adopting this integration.\n", + " The `@langfuse/vercel-ai-sdk` package targets AI SDK 7 and requires Node.js 22 or later. Use the AI SDK v6 legacy setup below if you cannot upgrade yet.\n", "\n", "\n", "Create an `instrumentation.ts` file with the OpenTelemetry exporter setup and register the Langfuse Vercel AI SDK integration once at application startup.\n", @@ -57,7 +57,7 @@ "registerTelemetry(new LangfuseVercelAiSdkIntegration());\n", "```\n", "\n", - "In the file that runs your AI SDK calls, import `instrumentation.ts` first. After the integration is registered, AI SDK v7 emits telemetry by default. Use `telemetry` to set the function name, include selected runtime context keys, or opt out of telemetry for a specific call.\n", + "In the file that runs your AI SDK calls, import `instrumentation.ts` first. After the integration is registered, AI SDK 7 emits telemetry by default. Use `telemetry` to set the function name, include selected runtime context keys, or opt out of telemetry for a specific call.\n", "\n", "```typescript filename=\"app.ts\"\n", "import \"./instrumentation\";\n", @@ -112,14 +112,14 @@ ");\n", "```\n", "\n", - "AI SDK v7 excludes `runtimeContext` from telemetry events unless each top-level key is explicitly included. Langfuse maps included runtime context keys to observation metadata, except `langfusePrompt`, which links Langfuse Prompt Management versions to model-call observations.\n", + "AI SDK 7 excludes `runtimeContext` from telemetry events unless each top-level key is explicitly included. Langfuse maps included runtime context keys to observation metadata, except `langfusePrompt`, which links Langfuse Prompt Management versions to model-call observations.\n", "\n", "To disable telemetry for one call, set `telemetry: { isEnabled: false }`.\n", "\n", - "## AI SDK v6 and current stable setup\n", + "## AI SDK v6 legacy setup\n", "\n", "### TL;DR\n", - "Here's the flow of how Langfuse and the stable Vercel AI SDK integration work together:\n", + "Here's the flow of how Langfuse and the legacy AI SDK v6 integration work together:\n", "\n", "1. **You enable telemetry** in the AI SDK (`experimental_telemetry: { isEnabled: true }`)\n", "2. **The AI SDK creates spans** for each operation (model calls, tool executions, etc.)\n", @@ -128,7 +128,7 @@ "\n", "This integration uses [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/), an observability standard. The Vercel AI SDK's telemetry feature is documented in the [Vercel AI SDK documentation on Telemetry](https://ai-sdk.dev/docs/ai-sdk-core/telemetry).\n", "\n", - "Let's walk through the stable setup in more detail.\n", + "Let's walk through the legacy AI SDK v6 setup in more detail.\n", "\n", "\n", "\n",