@zansn/langchain
v0.1.1
Published
Turn LangChain agent runs into portable Zansn evidence packs. Capture traces, tool calls, cost, and readiness with a callback handler.
Maintainers
Readme
@zansn/langchain
Turn a LangChain agent run into a portable Zansn evidence pack. Capture traces, tool calls, cost, and a readiness verdict with a callback handler.
Website: https://zansn.ai
LangChain surfaces a run through callbacks. This adapter gives you a BaseCallbackHandler that records tool calls, token usage, and model/chain spans as they happen, then hands the assembled run to the zansn assurance engine, which runs the same local policy, privacy, cost, latency, and readiness checks and returns the same evidence pack. It runs locally and transmits nothing.
Install
npm install @zansn/langchain zansn @langchain/core@langchain/core and zansn are peer dependencies, so you control their versions.
Quickstart
import { createZansnCollector } from "@zansn/langchain";
// 1. create a collector (holds this run's traces, tool calls, usage)
const zansn = createZansnCollector({
projectId: "support-agent",
policy: { blockedTools: ["delete_record"], maxLatencyMs: 8000 },
});
// 2. pass its handler in the callbacks of any LangChain run
await agentExecutor.invoke(
{ input: "Look up case CASE-40917 and summarise the billing issue." },
{ callbacks: [zansn.handler] },
);
// 3. seal a portable evidence pack from the captured run
const pack = await zansn.finalize();
console.log(pack.summary.readiness); // "ready" | "review" | "blocked"The pack is a ZansnEvidencePack: readiness, findings, traces, cost, and latency. Export it as JSON or Markdown, attach it to a pull request, or later ingest it into hosted Zansn.
Independent, verifiable evidence
Every pack this adapter produces is a standard zansn.evidence-pack.v0, so it can be signed into the open zansn.signed-evidence-pack.v1 standard with the core package:
import { generateSigningKeyPair, signEvidencePack } from "zansn";
const keys = await generateSigningKeyPair();
const signed = await signEvidencePack(pack, keys, { keyId: "acme:prod-2026" });Anyone can then check it offline with the standalone verifier, no Zansn account required: npx zansn-verify signed-pack.json.
API
createZansnCollector(options)
Returns a collector for one LangChain run.
| Option | Type | Notes |
| --- | --- | --- |
| projectId | string | Required. Stable id recorded on the pack. |
| policy | ZansnPolicy | Blocked/allowed tools, sensitive-data patterns, cost and latency ceilings. |
| experimentId, name, description | string | Recorded on the pack. |
| metadata | object | Merged onto the pack metadata. |
| expected, score | | Optional expected output and custom scorer. |
The collector exposes:
handler: a LangChainBaseCallbackHandler. Pass it in thecallbacksarray on your run.finalize({ output }): returns aPromise<ZansnEvidencePack>.toolCallCount: tool calls captured so far.
ZansnCallbackHandler and usageFromLLMResult are also exported for direct use.
What is captured
| LangChain callback | Zansn |
| --- | --- |
| handleToolStart + handleToolEnd / handleToolError | ZansnToolCall (name, args, result, status) |
| handleLLMEnd (LLMResult usage) | ZansnUsage + a model span |
| handleChainEnd | final output |
Token usage is read across the places LangChain providers report it (llmOutput.tokenUsage, llmOutput.usage, message usage_metadata), and missing fields are tolerated.
finalize() feeds the assembled result into ZansnClient.runEvaluation as a single completed task, so every existing check applies with no new assurance code.
Fail a pull request when a run is not deployment-ready
const pack = await zansn.finalize();
if (pack.summary.readiness === "blocked") {
console.error("Deployment blocked by Zansn:");
for (const f of pack.findings) console.error(` [${f.severity}] ${f.kind}: ${f.title}`);
process.exit(1);
}What is and is not in scope
This package produces a portable evidence pack locally. It does not store, compare, or govern packs. Hosted ingestion, run-over-run comparison, team workspaces, and enterprise policy packs are part of the commercial Zansn Assurance Control Plane. You keep calling the same local API; the paid tier adds the evidence graph.
Example
A runnable, no-API-key demo lives in examples/langchain.mjs.
License
Apache-2.0. See LICENSE.

