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.
shieldChatModelwraps a chat model, such asChatOpenAIorChatAnthropic. 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.ShieldCallbackHandlerchecks 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 guardedOn each call, Shield follows the shared steps. Specific to LangChain.js:
- System messages are every
SystemMessageand everyChatMessagewith rolesystemordeveloper. 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_callsentry'sargs. Providers keep copies of the arguments in content blocks,tool_call_chunks, and OpenAI'sadditional_kwargs.tool_calls. Each copy takes the guarded arguments of the tool call with the same id, so a finding is reported once. Each ofinvalid_tool_callsis guarded on its own. - When anything is redacted, Shield rebuilds the generation's
textand removeslogprobsfrom itsgenerationInfoand the message'sresponse_metadata.
ShieldCallbackHandler
import { ShieldCallbackHandler } from "@zeroleaks/shield/langchain";
const shield = new ShieldCallbackHandler({
throwOnLeak: true,
blockOnOutputFindings: true,
});
const result = await agent.invoke(input, { callbacks: [shield] });| Callback | What it checks | On a finding |
|---|---|---|
handleChatModelStart | Human 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 |
handleToolEnd | A tool's result: a string, a ToolMessage's content, or the string values of anything else | Throws InjectionDetectedError with source: "tool", and the tool call fails |
handleRetrieverEnd | The pageContent of each retrieved document | Throws InjectionDetectedError with source: "tool" |
handleLLMEnd | The model's text and tool call arguments, for prompt leaks, credentials, exfiltration links, and a canary | Calls 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:
| Option | API | Difference |
|---|---|---|
systemPrompt | shieldChatModel | Defaults to the text of the first system message, before hardening |
systemPrompt | ShieldCallbackHandler | Defaults to the run's first system message |
streamingChunkSize | shieldChatModel | Not used |
harden, streamingSanitize, streamingChunkSize, parallelDetection | ShieldCallbackHandler | Not accepted |
canary | ShieldCallbackHandler | Only 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:
| Mode | Behavior |
|---|---|
"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_generateand_streamResponseChunksthrows aTypeErrorthrough the Proxy. - A model that produces output without going through
_generateor_streamResponseChunksis 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
shieldChatModelwherever 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.