agent-lattice 0.18.0 → 0.19.0

package/README.md

@@ -308,6 +308,82 @@ root and share one trace session. Each Agent keeps its own SDK session identity,
 recorded as `agent_session_id` metadata, so tracing does not change Agent state
 or returned SDK messages.
 
+## Langfuse Context Tracing
+
+*Requires 0.19.0 or later.*
+
+The Langfuse adapter targets the current Langfuse JS SDK generation
+(`@langfuse/tracing` v5), which is OpenTelemetry-based. Register the
+`LangfuseSpanProcessor` once at process startup, then create the tracer —
+no other wiring needed.
+
+Configure Langfuse with its standard environment variables:
+
+```bash
+LANGFUSE_PUBLIC_KEY=<your-langfuse-public-key>
+LANGFUSE_SECRET_KEY=<your-langfuse-secret-key>
+LANGFUSE_BASE_URL=https://us.cloud.langfuse.com # or your self-hosted host
+```
+
+```bash
+npm install @langfuse/otel @opentelemetry/sdk-trace-node
+```
+
+```ts
+// instrumentation: register the span processor before agents run.
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+
+export const langfuseSpanProcessor = new LangfuseSpanProcessor();
+
+const tracerProvider = new NodeTracerProvider({
+  spanProcessors: [langfuseSpanProcessor],
+});
+tracerProvider.register();
+```
+
+```ts
+import {
+  createAgent,
+  createCompositeContextTracer,
+  createJsonlContextTracer,
+  createLangfuseContextTracer,
+} from "agent-lattice";
+import { langfuseSpanProcessor } from "./instrumentation";
+
+const tracer = createCompositeContextTracer([
+  createJsonlContextTracer({ path: ".agent-runs/session.jsonl" }),
+  createLangfuseContextTracer({
+    // Drained by tracer.flush()/close() so spans reach Langfuse before a
+    // short-lived process exits.
+    spanProcessor: langfuseSpanProcessor,
+    tags: ["local-debug"],
+  }),
+]);
+
+const agent = createAgent({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: "https://api.deepseek.com/anthropic",
+  model: "deepseek-v4-flash",
+  tracer,
+});
+
+try {
+  await agent.prompt("Trace this run.", { stream: false });
+} finally {
+  await tracer.close?.();
+}
+```
+
+Langfuse receives one trace per SDK query: the agent run is a root `chain`
+observation carrying the trace name, session id, and tags; model turns appear
+as child `generation` observations and SDK tool calls as child `tool`
+observations. For a `Team` query, delegated runs nest as child `chain`
+observations under the team root, so one handoff invocation stays one trace.
+
+`startObservation` defaults to the bundled `@langfuse/tracing` function; pass
+`startObservation` only to inject a custom runtime or a test fake.
+
 Custom sinks can implement the same interface for SQLite, OpenTelemetry, object
 storage, or host-specific observability. A `ContextTracer` port object exposes
 methods only — `failOnError` is bound when the factory creates the tracer, not

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.
 import { type StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { type StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { RunEvent, RunTree, RunTreeConfig } from "langsmith/run_trees";
+import { startObservation as bundledLangfuseStartObservation } from "@langfuse/tracing";
+import type { LangfuseChain, LangfuseGeneration, LangfuseObservation, LangfuseTool } from "@langfuse/tracing";
 import { z } from "zod/v4";
 export type TextBlock = TextBlockParam;
 export type ImageBlock = ImageBlockParam;
@@ -153,6 +155,27 @@ export type LangSmithContextTracerOptions = {
     redact?: (event: ContextTraceEvent) => ContextTraceEvent | undefined;
     failOnError?: boolean;
 };
+export type LangfuseKVMap = Record<string, unknown>;
+export type LangfuseObservationLike = LangfuseObservation;
+export type LangfuseChainLike = LangfuseChain;
+export type LangfuseGenerationLike = LangfuseGeneration;
+export type LangfuseToolLike = LangfuseTool;
+export type LangfuseStartObservation = typeof bundledLangfuseStartObservation;
+/** Drained by the Langfuse tracer's flush()/close(); a LangfuseSpanProcessor satisfies this. */
+export type LangfuseFlushableSpanProcessor = {
+    forceFlush(): Promise<void>;
+};
+export type LangfuseContextTracerOptions = {
+    /** Defaults to the bundled @langfuse/tracing startObservation; inject a compatible function for custom runtimes or tests. */
+    startObservation?: LangfuseStartObservation;
+    /** Span processor drained on flush()/close() — pass the LangfuseSpanProcessor registered with your OpenTelemetry setup. */
+    spanProcessor?: LangfuseFlushableSpanProcessor;
+    name?: string;
+    tags?: string[];
+    metadata?: LangfuseKVMap;
+    redact?: (event: ContextTraceEvent) => ContextTraceEvent | undefined;
+    failOnError?: boolean;
+};
 export type ModelMessage = {
     role: "user" | "assistant";
     content: string | ContentBlock[];
@@ -804,6 +827,16 @@ export declare function createJsonlContextTracer(options: JsonlContextTracerOpti
 export declare function createCompositeAgentHooks<TContext = unknown>(hooks: Array<AgentHooks<TContext> | undefined | null>): AgentHooks<TContext>;
 export declare function createCompositeContextTracer(tracers: Array<ContextTracer | undefined | null>): ContextTracer;
 export declare function createLangSmithContextTracer(options?: LangSmithContextTracerOptions): ContextTracer;
+/**
+ * Langfuse trace sink built on the current @langfuse/tracing (v5) SDK. The SDK
+ * is OpenTelemetry-based: the host registers a LangfuseSpanProcessor (from
+ * @langfuse/otel) with a tracer provider, and this adapter maps context trace
+ * events onto observations — a chain per agent run, a generation per model
+ * turn, a tool observation per tool call, and event observations for
+ * everything else. Pass the registered span processor so flush()/close() can
+ * drain pending spans before a short-lived process exits.
+ */
+export declare function createLangfuseContextTracer(options?: LangfuseContextTracerOptions): ContextTracer;
 export declare function skill(input: SkillInput): SkillDefinition;
 export declare function loadSkill(path: string): Promise<SkillDefinition>;
 export declare function createMCPTools(client: MCPClient, options?: MCPToolsOptions): Promise<Array<ToolDefinition<Record<string, unknown>>>>;