@pleach/langchain (preview)

A vine bridging your trellis to the LangChain one. @pleach/langchain wires LangChain primitives into a @pleach/core session. LangChain Tool instances become Pleach tool definitions, BaseMessage arrays become event log rows, and an AgentExecutor can run inside a Pleach session with its calls flowing through the audit ledger.

Pre-1.0 — pin a tight range. The package is published below 1.0.0 and the surface will move before it cuts. Treat every minor as potentially breaking and pin via ~0.x.y (patch only). The warning is in the package itself; it is repeated here because the migration cost of an unintended major-jump on this adapter is the highest of any sibling.

This page vs the migration guide

This page is the reference for the active adapter — for hosts keeping a LangChain tool, agent, or history backend in production and running it alongside Pleach primitives. The adapter is the bridge.

If you're moving wholesale off LangChain, the right page is Migrating from LangChain. That guide is one-time work: rewrite chains as runtime calls, retire the LangChain dependency, end with no adapter in the tree. This page is the opposite shape — long-lived integration, both libraries in package.json, deliberate boundary between them.

Install

npm install @pleach/langchain
# peer deps:
npm install langchain @langchain/core

The langchain and @langchain/core ranges are declared as peer dependencies so the adapter doesn't pin a LangChain version on top of the one the host already uses. Mismatches surface as peer-dep warnings at install time — don't ignore them; the converters key off LangChain type shapes that vary across majors.

import {
  fromLangChainTool,
  fromLangChainTools,
  toLangChainTool,
  LangChainProvider,
  LangGraphCheckpointerAdapter,
  LangGraphStoreAdapter,
  HarnessCheckpointSaver,
  HarnessEventLogCallback,
} from "@pleach/langchain";

The adapter exposes converters in both directions — LangChain tools become Pleach ToolDefinitions and vice versa — plus a LangChainProvider that exposes a LangChain chat model as a Pleach provider, plus LangGraph-shaped checkpointer/store adapters in each direction. The package README on npm carries the version-current constructor options.

Bridging a LangChain tool into a Pleach session

A LangChain Tool (or StructuredTool) instance wraps a callable plus a schema. The adapter converts it into a ToolDefinition usable on the Pleach side — registrable through setOrchestratorRegistry or a plugin's contributeTools.

import { fromLangChainTool } from "@pleach/langchain";
import { definePleachPlugin } from "@pleach/core";
import { DynamicStructuredTool } from "@langchain/core/tools";

const lcSearch = new DynamicStructuredTool({
  name: "search_db",
  description: "Search the product catalog.",
  schema: searchSchema,
  func: async (input) => productDb.query(input),
});

const pleachSearch = fromLangChainTool(lcSearch);

// Register through a plugin's `contributeTools` — the ergonomic path.
// Pass the plugin to `SessionRuntime({ plugins: [...] })`.
const langchainTools = definePleachPlugin("langchain-tools", {
  tools: [pleachSearch],
});

For bulk conversion use fromLangChainTools(tools) — same converter, applied across an array.

Conversion notes documented in the package README cover the LangChain features without a Pleach equivalent — callbacks scoped to the tool, the returnDirect flag, the tags/metadata pass- through. Anything the adapter can't carry across becomes a no-op on the Pleach side; the converter doesn't silently change semantics.

The reverse — Pleach ToolDefinition → LangChain Tool — ships as toLangChainTool(def). Use it when a LangChain-driven agent needs to call a Pleach-native tool:

import { toLangChainTool } from "@pleach/langchain";

const lcTool = toLangChainTool(myPleachToolDef);
// pass `lcTool` into a LangChain AgentExecutor's tools array.

Calling a LangChain chat model as a Pleach provider

LangChainProvider wraps any LangChain BaseChatModel and exposes it through the Pleach AgentAdapter provider contract. Use this when the host already owns a configured LangChain model (custom provider, LCEL chain composed upstream of the chat call, callback wiring) and wants the Pleach runtime to drive the agent loop against that model.

import { LangChainProvider } from "@pleach/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { createPleachRuntime } from "@pleach/core/runtime";

const lcModel = new ChatOpenAI({ model: "gpt-4o-mini" });
// The constructor is positional: `new LangChainProvider(model, maxSteps=10)`.
const provider = new LangChainProvider(lcModel);

const runtime = createPleachRuntime({
  // `provider` is a top-level config slot on createPleachRuntime.
  provider,
});

Tool calls round-trip via the fromLangChainTool / toLangChainTool converters, so LangChain-native streaming tool_call_chunks surface to Pleach as the same final tool_calls shape the runtime expects.

LangGraph-shaped storage adapters

Two adapter pairs let LangGraph storage co-exist with Pleach's checkpointer + store contracts:

• LangGraphCheckpointerAdapter — wraps a LangGraph BaseCheckpointSaver so Pleach's SessionRuntime uses LangGraph storage as its checkpointer backend.
• LangGraphStoreAdapter — wraps a LangGraph BaseStore so Pleach's memory contract reads/writes against LangGraph's store.
• HarnessCheckpointSaver — the reverse: a LangGraph-shaped BaseCheckpointSaver backed by a Pleach checkpointer.
• HarnessEventLogCallback — a LangGraph BaseCallbackHandler that writes LangGraph callback events into the Pleach event log.

import {
  LangGraphCheckpointerAdapter,
  LangGraphStoreAdapter,
} from "@pleach/langchain";
import { MemorySaver, InMemoryStore } from "@langchain/langgraph";

const checkpointer = new LangGraphCheckpointerAdapter(new MemorySaver());
const store        = new LangGraphStoreAdapter(new InMemoryStore());

const runtime = createPleachRuntime({ checkpointer, store, /* ... */ });

The reverse direction (Pleach storage exposed as LangGraph storage) is useful for a host running a LangGraph agent that wants the Pleach event log as its callback sink and the Pleach checkpointer as its state store — without rewriting the agent body.

Not yet shipping

The 0.x surface is intentionally narrow. Two converters described in early scoping notes are NOT in the published dist:

• fromLangChainMessages / BaseMessage[] → event-log rows. No bulk message-history importer ships. Hosts cutting over from a LangChain ChatMessageHistory backend write the row-shape mapping themselves against runtime.eventLog.append(...) (see the Event log reference). On the roadmap; not present.
• wrapLangChainExecutor / AgentExecutor wrap. No executor wrapper ships. The migration story uses LangChainProvider plus fromLangChainTools to run the Pleach loop against the LangChain model + tools, rather than wrapping LangChain's agent loop. If you need to keep an AgentExecutor running, instrument it with HarnessEventLogCallback so its callbacks land in the Pleach event log alongside the Pleach loop's rows.

Back-compat boundary

The package sits below 1.0.0 because the converter signatures are still settling. Pin patch-only:

{
  "dependencies": {
    "@pleach/langchain": "~0.3.2"
  }
}

Kinds of changes consumers should expect across minors before 1.0:

• Export renames. Function names may shift as the surface consolidates pre-1.0; pin patch-only against the npm README.
• Converter signature tweaks. Optional-argument shapes for the three converters are still narrowing — expect new required options as edge cases get formalized.
• Peer-dep range tightening. Supported langchain and @langchain/core ranges may narrow as LangChain itself moves through majors.
• Roadmap for AgentExecutor wrap + message-history import. Neither converter is in the 0.x dist today (see "Not yet shipping" above). If they land, the API will be additive — none of the converters currently shipping change shape.

Read the package CHANGELOG before each upgrade. The release notes flag any breaking change in the minor that introduces it.

Not in scope

• LangSmith parity. Distributed-tracing parity with LangSmith is out of scope for this adapter. For tracing, use OTel via Observability — the audit ledger plus an OTel exporter covers the same trace store role.
• LangGraph node-level bridging. The adapter operates at the tool / message / executor boundary, not at the LangGraph state- graph node level. A LangGraph migration is the migration guide's territory.
• Vector store / retriever wrapping. LangChain's retrieval surface stays inside LangChain; expose it to Pleach as a defineTool call, the same way the migration guide describes.

Where to go next