@escouade/graph-trace-langchain

LangChain / LangGraph callback adapter for @escouade/graph-trace. Attach it to any LangChain or LangGraph run and the trace is captured for you — no manual event plumbing.

• Native callback handler — extends BaseCallbackHandler; attach via config.callbacks.
• Captures the whole run — LLM turns (handleChatModelStart/handleLLMEnd) and tools (handleToolStart/End/Error), even in graph mode where the stream hides them.
• Graph-node attribution — reads LangGraph's langgraph_node metadata so each event knows which node emitted it.
• Auto-closes the run — from the root chain end/error (run.end ok/error), so you never pose it by hand.

This is the only piece coupled to LangChain; the @escouade/graph-trace core stays runtime-agnostic.

Install

npm install @escouade/graph-trace-langchain @escouade/graph-trace @langchain/core

@langchain/core is a peer dependency.

Usage

Open a trace from a graph-trace collector, wrap it with the adapter, and attach it to the run.

import { TraceCollector } from '@escouade/graph-trace';
import { FileExporter } from '@escouade/graph-trace-file-exporter';
import { langChainTraceHandler } from '@escouade/graph-trace-langchain';

const collector = new TraceCollector({
  exporters: [new FileExporter({ resolvePath: (doc) => `./traces/${doc.meta.traceId}.json` })],
});

// At app shutdown — drain all buffered runs:
process.on('SIGTERM', async () => {
  await collector.shutdown();
  process.exit(0);
});

const trace = collector.createTrace({
  provider: 'anthropic', // known at LLM client init, not in input
  model: 'claude-sonnet-4-6', // idem
  workflow,
  systemPrompt: input.systemPrompt,
  context: input.context ?? '',
  history: input.messages, // your graph state's message list
  tags: { agent: 'assistant' }, // optional free-form metadata
});

try {
  await graph.invoke(input, { callbacks: [langChainTraceHandler(trace)] });
} catch (err) {
  trace.fail(err); // safety net if the error was thrown before any chain ran
  throw err;
}

langChainTraceHandler(recorder) returns a LangChainTraceHandler (also exported as a class). It feeds the TraceRecorder from graph-trace; pass several handlers in callbacks if you need your own alongside it.

Tagging runs

Pass tags in createTrace to attach free-form string → string metadata. Tags are forwarded to TraceTurn.tags in the projected document.

const trace = collector.createTrace({
  // …
  tags: {
    agent: 'planner',
    env: process.env.NODE_ENV,
    userId: session.userId,
  },
});

See graph-trace tagging docs for details.

Resources

• @escouade/graph-trace core
• @escouade/graph-trace-file-exporter
• Document format reference — graph-trace/v1
• Writing a provider adapter

License

MIT