Module @langfuse/vercel-ai-sdk

GitHub Banner

@langfuse/vercel-ai-sdk

This package provides a Langfuse-owned telemetry integration for AI SDK v7 (ai@7) using the new callback-based telemetry system.

It delegates AI SDK-compatible OpenTelemetry span creation to Vercel's @ai-sdk/otel package so it works with the existing Langfuse OTEL ingestion pipeline. Runtime context keys included via AI SDK telemetry are attached as Langfuse observation metadata. The only special runtime context key is langfusePrompt, which links Langfuse prompt name and version to model-call observations.

Trace-level attributes such as user ID, session ID, tags, trace name, and trace metadata should be set with propagateAttributes from @langfuse/tracing.

Compatibility

This integration targets AI SDK v7 GA. Install it together with ai@^7; the package depends on the matching @ai-sdk/otel integration internally.

pnpm add @langfuse/vercel-ai-sdk ai

Usage

import { generateText, registerTelemetry } from "ai";
import { propagateAttributes } from "@langfuse/tracing";
import { LangfuseVercelAiSdkIntegration } from "@langfuse/vercel-ai-sdk";

registerTelemetry(new LangfuseVercelAiSdkIntegration());

await propagateAttributes(
  {
    userId: "user-123",
    sessionId: "session-456",
    tags: ["production", "chat"],
    metadata: {
      feature: "assistant",
    },
  },
  () =>
    generateText({
      model,
      prompt: "Explain RAG in one paragraph",
      runtimeContext: {
        route: "support-chat",
        langfusePrompt: {
          name: "assistant/default",
          version: 3,
          isFallback: false,
        },
      },
      telemetry: {
        functionId: "chat-assistant",
        includeRuntimeContext: {
          route: true,
          langfusePrompt: true,
        },
      },
    }),
);

AI SDK v7 excludes runtimeContext from telemetry events unless each top-level key is explicitly included. This integration maps every included runtime context key to Langfuse observation metadata, except langfusePrompt, which is used for prompt linking and is not added as metadata.

You can also pass the integration on a single call:

import { generateText } from "ai";
import { LangfuseVercelAiSdkIntegration } from "@langfuse/vercel-ai-sdk";

await generateText({
  model,
  prompt: "Summarize this article",
  runtimeContext: {
    feature: "article-summary",
  },
  telemetry: {
    functionId: "article-summary",
    includeRuntimeContext: {
      feature: true,
    },
    integrations: new LangfuseVercelAiSdkIntegration(),
  },
});

Packages

Package	Description	Environments
@langfuse/client	Langfuse API client for universal JavaScript environments	Universal JS
@langfuse/tracing	Langfuse instrumentation methods based on OpenTelemetry	Node.js 20+
@langfuse/otel	Langfuse OpenTelemetry export helpers	Node.js 20+
@langfuse/openai	Langfuse integration for OpenAI SDK	Universal JS
@langfuse/langchain	Langfuse integration for LangChain	Universal JS
@langfuse/vercel-ai-sdk	Langfuse integration for AI SDK v7	Universal JS