Langfuse JS/TS SDKs
    Preparing search index...

    Class LangfuseVercelAiSdkIntegration

    Langfuse telemetry integration for Vercel AI SDK v7 (ai@7).

    Register this once at application startup (or pass it per-call via telemetry.integrations) and every AI SDK call — generateText, streamText, generateObject, embed, tool executions — is traced as Langfuse observations. Requires the LangfuseSpanProcessor from @langfuse/otel to be registered with your OpenTelemetry setup; this integration only creates spans, the processor exports them to Langfuse.

    For AI SDK versions ≤6, do not use this class — enable experimental_telemetry: { isEnabled: true } on each call instead; the LangfuseSpanProcessor picks those spans up without an integration.

    Trace-level attributes (userId, sessionId, tags, traceName, metadata) should be set with propagateAttributes from @langfuse/tracing around the AI SDK call. Runtime context keys included via the AI SDK telemetry option become Langfuse observation metadata; the special key langfusePrompt links a Langfuse prompt version to model-call observations instead.

    // instrumentation.ts — run once at startup
    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());

    // app code
    import { generateText } from "ai";
    import { propagateAttributes } from "@langfuse/tracing";

    const { text } = await propagateAttributes(
      { userId: "user-123", sessionId: "session-456" },
      () =>
        generateText({
          model,
          prompt: "Explain RAG in one paragraph",
          telemetry: { functionId: "chat-assistant" },
        }),
    );

    Implements

    • Telemetry
    Index

    Constructors

    constructor

    Methods

    executeLanguageModelCall executeTool onAbort onEmbedEnd onEmbedStart onEnd onError onLanguageModelCallEnd onLanguageModelCallStart onObjectStepEnd onObjectStepStart onRerankEnd onRerankStart onStart onStepEnd onStepStart onToolExecutionEnd onToolExecutionStart

    Constructors

    Methods

    • Optionally runs the language model call in a telemetry-integration-specific context. This enables auto-instrumented model provider requests to become children of the current model-call span.

      The options carry the model-call start-event content as context (the event fields are optional), alongside the always-present callId and the execute function that performs the model call.

      Type Parameters

      • T

      Parameters

      • params: { callId: string; execute: () => PromiseLike<T> }

      Returns PromiseLike<T>

    • Optionally runs the tool execute function in a telemetry-integration-specific context. This enables nested traces — e.g. when a tool's execute function calls generateText, the inner call's spans become children of the tool span.

      The options carry the tool-execution start-event content as context (the event fields are optional), alongside the always-present callId, toolCallId, and the execute function to run.

      Type Parameters

      • T

      Parameters

      • params: { callId: string; execute: () => PromiseLike<T>; toolCallId: string }

      Returns PromiseLike<T>

    • Called when a streaming text generation operation is aborted before it completes.

      Parameters

      • event: GenerateTextAbortEvent<ToolSet>

      Returns void

    • Called when an individual embedding model call (doEmbed) completes. Contains the embeddings, usage, and any warnings from the model response.

      Parameters

      • event: EmbeddingModelCallEndEvent

      Returns void

    • Called when an individual embedding model call (doEmbed) begins. For embed, there is one call. For embedMany, there may be multiple calls when values are chunked.

      Parameters

      • event: EmbeddingModelCallStartEvent

      Returns void

    • Called when an operation completes. Fired for text generation (generateText/streamText), object generation (generateObject/streamObject), embedding (embed/embedMany), and reranking operations.

      Use the event shape or operationId to distinguish between operation types.

      Parameters

      • event:
            | GenerateObjectEndEvent<unknown>
            | EmbedEndEvent
            | RerankEndEvent
            | GenerateTextEndEvent<ToolSet>

      Returns void

    • Called when an unrecoverable error occurs during the generation lifecycle. The error value is untyped — it may be an Error instance, an AISDKError, or any thrown value.

      Use this to record error details on telemetry spans and set error status.

      Parameters

      • error: unknown

      Returns void

    • Called after the model response has been normalized and parsed, but before any client-side tool execution begins.

      Parameters

      • event: LanguageModelCallEndEvent<ToolSet>

      Returns void

    • Called immediately before the provider model call begins. Unlike onStepStart, this callback is scoped to model work only and excludes any later client-side tool execution.

      Parameters

      • event: LanguageModelCallStartEvent

      Returns void

    • Parameters

      • event: GenerateObjectStepEndEvent

      Returns void

      AI SDK v7 still emits object generation model spans through this callback.

    • Parameters

      • event: GenerateObjectStepStartEvent

      Returns void

      AI SDK v7 still emits object generation model spans through this callback.

    • Called when an individual reranking model call (doRerank) completes. Contains the ranking results from the model response.

      Parameters

      • event: RerankingModelCallEndEvent

      Returns void

    • Called when an individual reranking model call (doRerank) begins. There is one call per rerank invocation.

      Parameters

      • event: RerankingModelCallStartEvent

      Returns void

    • Called when an operation begins. Fired for text generation (generateText/streamText), object generation (generateObject/streamObject), embedding (embed/embedMany), and reranking operations.

      Use the operationId field to distinguish between operation types.

      Parameters

      • event:
            | GenerateObjectStartEvent
            | EmbedStartEvent
            | RerankStartEvent
            | GenerateTextStartEvent

      Returns void

    • Called when an individual step (single LLM invocation) completes. The event is a StepResult containing the model's response, tool calls and results, usage statistics, finish reason, and optional request/response bodies.

      Parameters

      • event: GenerateTextStepEndEvent<ToolSet>

      Returns void

    • Called when an individual step (single LLM invocation) begins. A generation may consist of multiple steps (e.g. when tool calls trigger follow-up LLM calls). Use this to create per-step spans or record step-level inputs.

      The event includes the step number, accumulated previous step results, and the messages that will be sent to the model.

      Parameters

      • event: GenerateTextStepStartEvent

      Returns void

    • Called when a tool execution completes, either successfully or with an error. The event uses a discriminated union on the success field — check event.success to determine whether output or error is available.

      The event includes execution time (toolExecutionMs) for performance tracking.

      Parameters

      • event: WidenedToolExecutionEndEvent

      Returns void

    • Called when a tool execution begins, before the tool's execute function is invoked. Use this to create tool-level spans or log tool invocations.

      Parameters

      • event: WidenedToolExecutionStartEvent

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods