Quick start

Install the package

From your Eve project:

npm install @vantezzen/langfuse-eve
bun add @vantezzen/langfuse-eve

The package targets Eve 0.55 and newer and Node.js 24 and newer.

Add Langfuse credentials

Copy the API keys from your Langfuse project settings into the agent environment:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

Change LANGFUSE_BASE_URL when you use another Langfuse region or a self-hosted instance.

Enable Eve instrumentation providers

Currently eve requires enabling the experimental instrumentationProviders flag to use separate provider files:

import { defineAgent } from "eve";

export default defineAgent({
  experimental: { instrumentationProviders: true },
});

Capture complete trace content

Eve omits model and tool content from non-public conversations outside development by default. Add this provider so Langfuse receives inputs and outputs in every environment:

import { otel } from "eve/instrumentation/otel";

export default otel({
  tracePolicy: () => ({
    emit: true,
    recordInputs: true,
    recordOutputs: true,
  }),
});

Add the Langfuse trace destination

Add the Langfuse instrumentation provider to your agent:

import { defineLangfuseInstrumentation } from "@vantezzen/langfuse-eve/instrumentation";

export default defineLangfuseInstrumentation();

Eve now sends agent, model, tool, skill, and subagent spans to Langfuse. The integration also adds Eve session lineage and Vercel AI Gateway generation and cost fields.

Load the main prompt from Langfuse

If you want to manage your agent prompt in LangFuse, add the text prompt (e.g. agent/base) in Langfuse and then load the prompt in your agent:

import { defineLangfuseInstructions } from "@vantezzen/langfuse-eve/instructions";

export default defineLangfuseInstructions("agent/base", {
  fallback: "You are a concise support agent.", // Fallback prompt, e.g. if Langfuse is down
  label: "production", // Or "latest" to always use the latest version of the prompt in Langfuse
});

The fallback keeps the agent available if Langfuse cannot return the prompt - e.g. if it is down or the prompt is not found. Generations using a fetched prompt link to its name and version in Langfuse.