Skip to content

LangChain.js integration

The @inpolicy/langchain package integrates InPolicy into any LangChain.js chain or agent. Two flavors:

  • withInPolicy: wrap an LLM call with a single function. Simplest.
  • InPolicyCallbackHandler: a callback handler you attach to an existing chain.
Terminal window
npm install @inpolicy/langchain @inpolicy/sdk @langchain/core
import { ChatOpenAI } from '@langchain/openai';
import { InPolicyClient } from '@inpolicy/sdk';
import { withInPolicy } from '@inpolicy/langchain';
const ip = new InPolicyClient({ apiKey: process.env.INPOLICY_API_KEY! });
const llm = new ChatOpenAI({ modelName: 'gpt-4o' });
const guarded = withInPolicy(
async ({ system, user }) => {
const res = await llm.invoke([
{ role: 'system', content: system },
{ role: 'user', content: user },
]);
return typeof res.content === 'string' ? res.content : JSON.stringify(res.content);
},
{
client: ip,
sessionId: 'sess_abc',
systemPrompt: 'You are a helpful customer support agent.',
checkOutput: true, // optional; post_inference_checking is on by default for new keys
onBlock: 'throw', // the default with checkOutput; 'return' hands you the block
onUnchecked: 'allow', // the default; 'block' treats an output that could not be checked as blocked
// Optional, sent with the output check:
channel: 'support_chat',
audience: 'external',
authorType: 'ai_agent',
authorRole: 'Customer support agent',
country: 'GB', // sent with both turns
// policyAreaIds: ['<policy-area-id>'], // optional, sent with both turns
},
);
const result = await guarded.invoke({ input: "I'm 16 — can I buy this?" });
console.log(result.output); // the LLM's response
console.log(result.preInferencePolicies); // e.g. ['Policy 4.2', 'Policy 7.1']
console.log(result.decision); // 'allow' | 'warn' | 'block' | null
console.log(result.checked); // false when the output was NOT checked
console.log(result.uncheckedReason); // 'timeout' | 'unavailable' | 'error' | null
console.log(result.postInferenceViolations); // the check's violations, each with policyTitle
console.log(result.suggestedRedaction); // every finding rewritten (safe to send), or null

invoke also takes messages (the conversation so far, oldest first) per call, which overrides the messages option for that call’s check.

What it does on every invocation:

  1. record_turn({ role: 'user', content: input }) → get active policies.
  2. Build system = systemPrompt + '\n\n' + injectionBlock.
  3. Call the wrapped LLM function with { system, user }.
  4. record_turn({ role: 'assistant', content: output, checkOutput }).
  5. With checkOutput and onBlock: 'throw', a block throws InPolicyBlockedError. Otherwise return the output, the policy metadata and the check.

decision and checked come from the output check. Without checkOutput, decision is null and checked is false. A checked: false result is not clean: with checkOutput, it means the check timed out or failed. policyAreaIds, country and the key’s teams scope both turns, so the output check uses the same policies as the user turn.

A reply with no text. A model reply that is empty or only whitespace (for example one that only calls tools) records no assistant turn, since there is nothing to check. With checkOutput, the result is checked: false, uncheckedReason: 'error' and decision: null, and nothing is thrown, whatever onUnchecked says.

suggestedRedaction is not null only when every finding was rewritten cleanly, so you can send it as is; when it is null on a block, regenerate or route to a person.

InPolicyBlockedError carries decision: 'block', checked, uncheckedReason, violations, suggestedRedaction, traceId and the blocked output. Its message names the policies (InPolicy blocked this output: <policy titles>.). It is also thrown when the output could not be checked and the key’s on_check_error is block, or, with onUnchecked: 'block', when the check could not run on your side; its message is then InPolicy could not check this output (<reason>) and onUnchecked is 'block'.

onUnchecked ('allow' by default, or 'block') applies only with checkOutput, when the check could not run on the client side: a network error, a timeout, a 408, 429 or 5xx, or a response with no check result. 'allow' gives decision: null, checked: false, and the output goes through. 'block' gives decision: 'block', checked: false and blockedUnchecked: true, which onBlock handles (by default it throws). It does not change a server-side unchecked result, which follows the key’s on_check_error. The OnUnchecked type is exported.

Errors. Any 4xx from InPolicy except 408 and 429 is thrown from invoke, from either turn, as InPolicyApiError (BudgetExceededError for a 402). That includes a 400 (for example country: 'UK', or an end user’s message that is blank or over 100,000 characters), 401, 402, 403, 404, 409 and 422: the model does not run without its policies. Fix the request or key, or wait for the budget period. A 409 can also mean another turn for the same session was still being saved; retry the call. Network errors, timeouts, 408, 429 and 5xx are logged with console.error and do not break the chain; with checkOutput the result then reads checked: false, decision: null (or block with onUnchecked: 'block') and uncheckedReason: 'error' ('timeout' for a timeout or 408).

InPolicyCallbackHandler: drop into an existing chain

Section titled “InPolicyCallbackHandler: drop into an existing chain”

If you have a complex chain or agent already wired up, use the callback handler instead:

import { ChatOpenAI } from '@langchain/openai';
import { InPolicyClient } from '@inpolicy/sdk';
import { InPolicyCallbackHandler } from '@inpolicy/langchain';
const ip = new InPolicyClient({ apiKey: process.env.INPOLICY_API_KEY! });
const inpolicyHandler = new InPolicyCallbackHandler({
client: ip,
sessionId: 'sess_abc',
recentContextWindow: 3,
checkOutput: true,
onBlock: 'throw', // default with checkOutput: a block rejects the LLM call
onError: (err) => console.error('[InPolicy]', err), // the default
onViolations: (violations) => {
console.warn('[InPolicy]', violations.length, 'violations in assistant output');
},
});
const llm = new ChatOpenAI({
modelName: 'gpt-4o',
callbacks: [inpolicyHandler],
});
// Use `llm` anywhere; the handler fires on every LLM call in the chain.
const result = await llm.invoke('Draft a reply to the Acme account exec.');
// After invocation, read the latest state and check
const latest = inpolicyHandler.getLatest();
console.log(latest?.activePolicies);
const check = inpolicyHandler.getLatestCheck();
console.log(check?.decision, check?.checked);

The handler hooks handleChatModelStart and handleLLMEnd to record turns around every LLM invocation. Attach to any Runnable, chain, or agent; it travels through. It takes the same messages, channel, audience, authorType, authorRole, country, policyAreaIds and onUnchecked options as withInPolicy.

With checkOutput: true, LangChain waits for the handler on every LLM call, so a block (InPolicyBlockedError, unless onBlock: 'return') or any 4xx except 408 and 429 rejects the model call. Network errors, timeouts, 408, 429 and 5xx go to onError and the check reads checked: false (blocked instead with onUnchecked: 'block'). Without checkOutput, the handler never throws and every error goes to onError. It follows LangChain’s own setting for when callbacks run: in the background by default, or awaited when LANGCHAIN_CALLBACKS_BACKGROUND=false (as on serverless runtimes). A blank model reply records no assistant turn; with checkOutput, getLatestCheck() then reads checked: false, uncheckedReason: 'error'. onViolations fires whenever a check returns violations.

Caveat: the callback handler can call record_turn but it can’t modify the system prompt that’s being sent to the LLM. If you want the injection block to actually reach the model, either use withInPolicy (recommended) or have your chain’s prompt template read the injection block from inpolicyHandler.getInjectionBlock() (called after a warm-up turn).

For an agent that calls tools, combine the callback handler with explicit checkToolCall calls in your tool definitions:

import { DynamicStructuredTool } from '@langchain/core/tools';
import { z } from 'zod';
const sendEmailTool = new DynamicStructuredTool({
name: 'send_email',
description: 'Send an email to a recipient',
schema: z.object({
to: z.string(),
subject: z.string(),
body: z.string(),
}),
func: async (args) => {
// Gate the action
const check = await ip.checkToolCall({
sessionId: 'sess_abc', // same session the handler uses
toolName: 'send_email',
arguments: args,
});
if (!check.checked) {
// Not checked: `allow` follows the key's on_check_error and there are
// no violations.
if (!check.allow) return `Not sent: the call could not be checked (${check.uncheckedReason}).`;
} else if (!check.allow) {
const titles = check.violations.map((v) => v.policyTitle ?? v.policyId).join(', ');
return `Blocked by policy: ${titles || 'a policy'}`;
}
// Execute
return await actuallySendEmail(args);
},
});

Not available. Use the REST API directly via requests or httpx; shape is documented in the API reference.