Langfuse Integration

VoltAgent offers built-in OpenTelemetry support, making it easy to send traces and logs to observability platforms like Langfuse. This guide shows you how to integrate VoltAgent with Langfuse using the dedicated @voltagent/langfuse-exporter package.

Prerequisites

• You have a Langfuse account and project. Get your API keys (Public Key and Secret Key) and Base URL from your Langfuse project settings.
• You have a basic VoltAgent application setup.

Installation

First, install the necessary packages:

npm install @voltagent/langfuse-exporter

Setup

Import VoltAgent and LangfuseExporter

In your main application file (e.g., index.ts), import the required classes.

import { Agent, VoltAgent } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";

import { LangfuseExporter } from "@voltagent/langfuse-exporter";
// ... other imports like your LLM provider and tools

Configure the Exporter

Create an instance of LangfuseExporter. It's best practice to use environment variables for your Langfuse credentials.

const langfuseExporter = new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY, // Your Langfuse Public Key
  secretKey: process.env.LANGFUSE_SECRET_KEY, // Your Langfuse Secret Key
  baseUrl: process.env.LANGFUSE_BASE_URL, // Optional: Defaults to Langfuse Cloud URL
  // debug: true, // Optional: Enable detailed logging from the exporter
});

Ensure you have set the LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY environment variables.

Pass Exporter to VoltAgent

When creating your main VoltAgent instance, pass the configured langfuseExporter to the telemetryExporter option.

// Define your agent(s)
const agent = new Agent({
  name: "my-voltagent-app",
  instructions: "A helpful assistant that answers questions without using tools",
  llm: new VercelAIProvider(),
});

// Initialize VoltAgent with the exporter
new VoltAgent({
  agents: {
    agent, // Register your agent(s)
  },
  telemetryExporter: langfuseExporter, // Pass the exporter instance
});

How it Works

By providing the telemetryExporter to VoltAgent, you activate VoltAgent's automatic OpenTelemetry integration:

• A global OpenTelemetry NodeTracerProvider is configured.
• The provided exporter(s) are attached using BatchSpanProcessors (recommended for production).
• All operations within any Agent instance managed by this VoltAgent (including sub-agents called via delegation) will automatically create and export OpenTelemetry spans.
• The @voltagent/langfuse-exporter specifically transforms these OpenTelemetry spans into Langfuse traces, generations, and spans, mapping relevant attributes like prompts, responses, tool calls, usage data, user IDs, and session IDs.

Using Multiple Exporters

The telemetryExporter option accepts either a single exporter instance or an array of exporters. This allows you to send telemetry data to multiple systems simultaneously.

import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base"; // Example: OTEL Console Exporter

new VoltAgent({
  agents: { agent },
  telemetryExporter: [
    new LangfuseExporter({
      /* ... config ... */
    }),
    new ConsoleSpanExporter(), // Also log spans to the console
    // new OtherExporter({ /* ... config ... */ }),
  ],
});

Now your VoltAgent setup will automatically send detailed traces to Langfuse! Check your Langfuse project to see the incoming data.