Skip to Content
ZeroLeaksDocs
Shield SDKProvider wrappers

LangChain.js

Guard LangChain.js chat models with shieldChatModel, and check chains and agents with ShieldCallbackHandler.

@zeroleaks/shield/langchain has two integrations. Both require @langchain/core.

  • shieldChatModel wraps a chat model, such as ChatOpenAI or ChatAnthropic. It hardens system messages, checks human and tool messages, and guards text and tool call arguments on every call, streamed or not. Use it by default.
  • ShieldCallbackHandler checks the runs it is attached to. It can stop a run, but it can't harden a prompt or redact output. Use it for chains and agents whose model you can't wrap.

shieldChatModel

import { ChatOpenAI } from "@langchain/openai";
import { shieldChatModel } from "@zeroleaks/shield/langchain";

const model = shieldChatModel(new ChatOpenAI({ model: "gpt-5.5" }), {
  systemPrompt: "You are a support agent...",
});

const reply = await model.invoke([
  ["system", "You are a support agent..."],
  ["human", userInput],
]);

shieldChatModel returns a Proxy that guards your model's _generate and _streamResponseChunks methods, which invoke, batch, stream, streamEvents, chains, and agents all call. The wrapped model keeps your model's type and class. A model without _generate throws a TypeError.

Runnables built from the wrapped model call the guarded model: bindTools(), withConfig(), withStructuredOutput(), pipe(), withRetry(), withFallbacks(), and the rest. If a method returns a new chat model, or a runnable bound to one, as some bindTools() implementations do, Shield wraps that model with the same options.

const withTools = model.bindTools([searchTool]); // still guarded
const extractor = model.withStructuredOutput(schema); // still guarded

On each call, Shield follows the shared steps. Specific to LangChain.js:

  • System messages are every SystemMessage and every ChatMessage with role system or developer. In content blocks, the text blocks are joined with newlines into the first one and hardened, and other blocks stay where they were.
  • Detection reads human, tool, and function messages: string content, or the text blocks joined. Other blocks are ignored.
  • Shield guards each AI message's text and every string in each tool_calls entry's args. Providers keep copies of the arguments in content blocks, tool_call_chunks, and OpenAI's additional_kwargs.tool_calls. Each copy takes the guarded arguments of the tool call with the same id, so a finding is reported once. Each of invalid_tool_calls is guarded on its own.
  • When anything is redacted, Shield rebuilds the generation's text and removes logprobs from its generationInfo and the message's response_metadata.

ShieldCallbackHandler

import { ShieldCallbackHandler } from "@zeroleaks/shield/langchain";

const shield = new ShieldCallbackHandler({
  throwOnLeak: true,
  blockOnOutputFindings: true,
});

const result = await agent.invoke(input, { callbacks: [shield] });
CallbackWhat it checksOn a finding
handleChatModelStartHuman and tool messages sent to a chat model, including earlier turns. It also records the run's system prompt.Throws InjectionDetectedError, and the model is not called
handleToolEndA tool's result: a string, a ToolMessage's content, or the string values of anything elseThrows InjectionDetectedError with source: "tool", and the tool call fails
handleRetrieverEndThe pageContent of each retrieved documentThrows InjectionDetectedError with source: "tool"
handleLLMEndThe model's text and tool call arguments, for prompt leaks, credentials, exfiltration links, and a canaryCalls onLeakDetected and onOutputFindings. Throws LeakDetectedError with throwOnLeak, and OutputBlockedError with blockOnOutputFindings. Otherwise the output goes through unchanged.

With onDetection: "warn", injections are reported to onInjectionDetected and nothing throws.

The handler sets raiseError, so LangChain waits for it and passes its errors on to the run, after logging them with console.error. A framework that catches tool errors, as LangGraph's ToolNode does by default, sends the model the error message instead of the tool result.

Options

Both take the shared options, with these differences:

OptionAPIDifference
systemPromptshieldChatModelDefaults to the text of the first system message, before hardening
systemPromptShieldCallbackHandlerDefaults to the run's first system message
streamingChunkSizeshieldChatModelNot used
harden, streamingSanitize, streamingChunkSize, parallelDetectionShieldCallbackHandlerNot accepted
canaryShieldCallbackHandlerOnly finds a token you put in the prompt yourself. canary: true creates a token that never appears.

Streaming

shieldChatModel handles the streamingSanitize modes like this:

ModeBehavior
"buffer" (default)Reads every chunk before yielding any. A clean message is replayed unchanged. A redacted one arrives as a single chunk with the whole guarded message.
"chunked"Works like "buffer".
"passthrough"Chunks and tokens pass through with no sanitization or output scanning. Input is still checked.

Tokens the model reports through handleLLMNewToken are buffered, then replayed for the chunks that are yielded, so callback handlers, streamEvents(), and LangGraph's messages stream mode only see guarded text. For a model that streams inside _generate, each generation's guarded text is sent as one token.

streamEvents() without a version produces LangChain's content block events. Shield builds them from the guarded chunks with LangChain's base implementation, so the provider's own are not used.

With ShieldCallbackHandler, handleLLMEnd runs after the text has been streamed. It can fail the run but can't retract that text.

Limitations

shieldChatModel:

  • A model class that keeps state in JavaScript private fields (#field) and reads them in methods other than _generate and _streamResponseChunks throws a TypeError through the Proxy.
  • A model that produces output without going through _generate or _streamResponseChunks is not guarded.
  • A LangChain cache hit returns the stored response without calling the model, so neither the input check nor the output guard runs for it.
  • A provider's own content block events are not used. See Streaming.
  • Reasoning and thinking blocks in the output are not scanned. Images, audio, and files in messages are not read.
  • Tools, retrievers, and other models in the chain are not guarded. Attach a ShieldCallbackHandler to check tool results and retrieved documents.

ShieldCallbackHandler:

  • A callback can't modify the run. Prompts are not hardened and output is not redacted. Output with a finding either stops the run or passes through unchanged. Use shieldChatModel wherever you can wrap the model.
  • LLM runs with a plain string prompt (handleLLMStart), chain inputs and outputs, and anything the handler isn't attached to are not checked.

See Limitations for what no integration scans.

On this page