Anvia Docs

Use @anvia/langfuse when you want Anvia observer events in Langfuse.

1. Install the Adapter

pnpm add @anvia/langfuse

The adapter is separate from @anvia/core. Core Anvia does not export langfuse.

2. Create the Tracing Observer

Pass Langfuse credentials from your application's configuration.

import { langfuse } from "@anvia/langfuse";

const tracing = langfuse.create({
  publicKey,
  secretKey,
  baseUrl,
  environment,
  release,
});

baseUrl, environment, and release are optional.

3. Attach It to an Agent

const agent = new AgentBuilder("support", model)
  .instructions("Answer with a short engineering-focused summary.")
  .observe(tracing)
  .defaultMaxTurns(2)
  .build();

4. Send Trace Metadata

const response = await agent
  .prompt("Summarize ticket TICKET-1001 for engineering.")
  .withTrace({
    name: "support-ticket-summary",
    userId: "user_123",
    sessionId: "session_456",
    metadata: {
      ticketId: "TICKET-1001",
      surface: "support-console",
    },
    tags: ["support", "anvia"],
  })
  .send();

console.log(response.trace?.traceId);

Langfuse receives the run, model generations, tool observations, usage, errors, and trace attributes.

5. Score a Trace

await tracing.score({
  traceId: response.trace?.traceId,
  observationId: response.trace?.observationId,
  name: "quality",
  value: 1,
  comment: "Good answer",
  metadata: { source: "review" },
});

Scoring requires publicKey, secretKey, and a trace id.

6. Report Eval Scores

Use createLangfuseEvalReporter(...) to publish eval outcomes as Langfuse scores.

import { agentEvalTarget, contains, runEvalSuite } from "@anvia/core/evals";
import { createLangfuseEvalReporter } from "@anvia/langfuse";

await runEvalSuite({
  name: "support-agent-regression",
  cases: [{ id: "refund-window", input: "How long are refunds available?", expected: "30 days" }],
  target: agentEvalTarget(agent),
  metrics: [contains()],
  reporters: [createLangfuseEvalReporter(tracing)],
});

The reporter uses the prompt response trace when available. You can also attach traceId and observationId to eval case metadata.

7. Flush or Shutdown

await tracing.flush();
await tracing.shutdown();

Use flush() after short-lived jobs. Use shutdown() when the process is exiting.