@agentskit/observability-langfuse

@agentskit/observability-langfuse is a drop-in observer that ships AgentsKit trace spans to Langfuse. LLM generations become generation nodes; tool calls, planning steps, and HITL gates become span nodes. Token usage and error state are captured on each node end.

The langfuse npm package is an optional peer — loaded dynamically at runtime. If it is absent or no API keys are provided, the observer is a no-op and does not throw.

#When to reach for it

• You already use Langfuse for prompt management, user feedback, or cost analytics.
• You want per-session or per-user trace grouping without manual instrumentation.
• You want token + cost tracking in the Langfuse UI alongside your AgentsKit runs.

#Best fit

• Add alongside consoleLogger or opentelemetry — observers compose and do not conflict.
• Pair with @agentskit/eval to turn Langfuse trace failures into repeatable eval cases.
• Pair with @agentskit/runtime to trace multi-step agent workflows end-to-end.

#Install

npm install @agentskit/observability-langfuse
# peer deps
npm install @agentskit/observability langfuse

#Hello world

import { langfuse } from '@agentskit/observability-langfuse'
import { createRuntime } from '@agentskit/runtime'

const runtime = createRuntime({
  adapter,
  observers: [langfuse()],
})

Keys are read from LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY env vars. No config object required for the common case.

#Public API

#langfuse(config?): Observer

Returns an Observer that can be passed directly to observers in createRuntime, useChat, or any other AgentsKit entry point that accepts observers.

#LangfuseConfig

Named export — the type of the config object above. Useful when building helper factories.

#Per-session tracing

import { langfuse } from '@agentskit/observability-langfuse'

// One observer instance per request / conversation to isolate sessions.
const observer = langfuse({
  sessionId: req.sessionId,
  userId: req.user.id,
  tags: ['support-bot', 'v2'],
})

const runtime = createRuntime({ adapter, observers: [observer] })

#Self-hosted Langfuse

langfuse({
  baseUrl: 'https://langfuse.internal.example.com',
  publicKey: process.env.LF_PUBLIC_KEY,
  secretKey: process.env.LF_SECRET_KEY,
})

#Configuration

Explicit config fields always take precedence over env vars.

#Stability

• Version: 0.1.0
• Tier: beta
• Contract: Observer interface stable; Langfuse SDK peer-resolved at runtime.

#Related

• @agentskit/observability — core observer package this adapter plugs into
• @agentskit/eval — convert trace failures into eval cases
• Observability (deep dive)
• Audit log

#Source

npm: @agentskit/observability-langfuse · repo: packages/observability-langfuse