LangChain security guide

What is the LangChain security guide?

LangChain is one of the most widely used agent frameworks. You define tools, wire a model, and call invoke() or ainvoke() to run a turn. The model reads user messages and may call those tools to query databases, send email, or call APIs. Any untrusted text in the conversation—support tickets, uploaded files, retrieved documents—can try to steer those calls. That is prompt injection.

You need two separate controls. Screen inbound text before the agent starts, then gate tool calls with rules you define before the side effect runs. LangChain also offers human-in-the-loop middleware and interrupts for confirmation. Those pause for a person; they don't replace an action gate on every tool invocation.

Arcjet Guard is a runtime policy layer for AI agents. You define rules—prompt-injection detectors, rate limits, PII checks, allowlists—and Guard allows or denies inbound text and tool calls before side effects run. The examples below use Guard for both controls.

This guide covers LangChain 1.2+ JavaScript (langchain, @langchain/core) and LangChain 1.3+ Python (langchain, langchain-core, langgraph). The two runtimes share a job and don't share an import. These examples wrap LangChain agent tools—not LangGraph StateGraph plus ToolNode (see the LangGraph security guide) and not Vercel AI SDK tool() handlers.

Work through these eight topics in order. Each one is a control you can verify, not a slogan.

• Patch and lock dependencies. Stay on LangChain 1.x.
• Keep API keys off the client and out of LangSmith traces.
• Screen user text before invoke / ainvoke.
• Don't treat humanInTheLoopMiddleware or callbacks as a policy gate.
• Wrap authored tools that you call yourself, or put agent-wide policy on middleware.
• Narrow args_schema before you wrap so the model can't invent extra fields.
• Correlate the run with a caller-owned thread or session ID.
• Catch issues in the editor and in CI before they ship.

For shorter wiring recipes, see How do I secure a LangChain Python agent? and the LangChain JS agent guard. For the Guard helpers used in the Python examples, see the LangChain agent guard.

How do you keep LangChain dependencies safe?

Apply patches on a schedule you actually keep, and out of band for a critical advisory. Commit a lockfile so every environment installs the same graph. LangChain 1.0 is an LTS line—stay on 1.x until 2.0 ships, then plan the upgrade. Legacy 0.3 is in maintenance until December 2026; don't start an app there.

JavaScript wrapToolCall only sees runtime.configurable.thread_id as of LangChain 1.2.34. That is why the JS peer floor is higher than @langchain/core. Install the provider package your model string needs (@langchain/openai for "openai:gpt-4o").

Python extras are split on purpose. The langchain extra is guard_tool on a BaseTool. The langchain-agents extra adds middleware for create_agent and pulls LangGraph. Don't install the agents extra if you only wrap tools that you call yourself. See trivial packages for the cost of a convenience extra that you don't use.

How should LangChain secrets be handled?

Model keys such as OPENAI_API_KEY and ANTHROPIC_API_KEY belong on the server, loaded at process start. Don't put them in a client bundle, a LangSmith example, or a prompt template that later lands in a trace.

LangSmith and callback handlers can serialize tool arguments. Redact before export. See redacting sensitive data from logs and storing secrets in environment variables.

How do you screen inbound LangChain text?

LangChain doesn't expose a dedicated inbound hook, so screen in your route handler, job, or webhook before you call invoke, ainvoke, or stream. That is where a pasted ticket or fetched webpage still lives as plain text—before the model treats it as instructions. wrapModelCall, beforeModel, and afterModel intercept the model call, not user text.

With Guard, call arcjet.guard() / arcjet.guard_sync() with prompt-injection rules on that string. Pair the async Guard client with ainvoke() and the sync client with invoke(). launch_arcjet_sync is for Flask, Django, and other sync Python. Direct guard() / guard_sync() fails open: an ALLOW isn't proof the rules ran, so gate on hasFailedOpen() / has_failed_open() when this call site must fail closed. On deny, don't start the agent.

JavaScript:

1
import { detectPromptInjection } from "@arcjet/guard";
2
import { langchainContext } from "@arcjet/guard/langchain/v1";
3
import { arcjet } from "./arcjet.js";
4

5
const inbound = detectPromptInjection();
6
const config = { configurable: { thread_id: conversationId } };
7

8
const decision = await arcjet.guard({
9
  label: "message.received",
10
  rules: [inbound(userText)],
11
  ...langchainContext(config),
12
});
13

14
if (decision.conclusion === "DENY" || decision.hasFailedOpen()) {
15
  throw new Error("message blocked");
16
}

Python: call guard() / guard_sync() with label="message.received" the same way, then create_agent(...).ainvoke(...). Pass config={"configurable": {"arcjet_correlation_id": session_id}} so middleware and guarded tools share one Sequence. The helpers don't use the LangChain run_id.

Why isn't human-in-the-loop a security policy?

LangChain can pause an agent and wait for a person to approve the next tool call. That is human-in-the-loop (HITL): useful for workflows where a reviewer needs full context. It isn't a substitute for evaluating every tool call against policy before it runs.

JavaScript humanInTheLoopMiddleware and interrupt() pause for a person. Python callbacks and LangGraph interrupts do the same. They are confirmation, not a remote allow or deny.

A handler that logs on_tool_start can't refuse the send. LangChain ignores callback return values. ArcjetCaptureHandler is observe-only. See human approval is not a security policy.

How do you gate LangChain tools?

Once the agent is running, tools are where side effects happen. LangChain offers several surfaces depending on whether you call a tool yourself or let the agent pick it. Pick the helper that matches what you hold when the effect would run.

Python:

• Any callable: guard_action / guard_action_sync in core arcjet.guard.
• A BaseTool that you call yourself: guard_tool (arcjet[langchain]).
• An agent from create_agent: ArcjetMiddleware plus ToolPolicy (arcjet[langchain-agents]).
• Observe only: ArcjetCaptureHandler. It can't deny.

Configure args_schema, handle_tool_error, and response_format before you wrap. Changes after wrapping don't reach the tool. Narrow the schema with extra="forbid" so the model can't invent a recipient.

1
from langchain.agents import create_agent
2
from arcjet.guard import TokenBucket, launch_arcjet
3
from arcjet.guard.langchain import ArcjetMiddleware, ToolPolicy
4

5
arcjet = launch_arcjet(key=ARCJET_KEY)
6
send_limit = TokenBucket(
7
    refill_rate=5,
8
    interval_seconds=60,
9
    max_tokens=5,
10
    bucket="email",
11
)
12

13
agent = create_agent(
14
    model="openai:gpt-4o",
15
    tools=[send_email, search_orders],
16
    middleware=[
17
        ArcjetMiddleware(
18
            guard=arcjet,
19
            policies={
20
                "send_email": ToolPolicy(
21
                    action="email.sent",
22
                    rules=[send_limit(key="email", requested=1)],
23
                )
24
            },
25
            tools=[send_email, search_orders],
26
        )
27
    ],
28
)

A typo or a renamed @tool function leaves that tool unguarded. Pass tools= the same sequence that you gave create_agent. On deny, ArcjetMiddleware raises ArcjetDeniedError. guard_tool raises ArcjetToolDeniedError, or follows handle_tool_error when you configured that before wrapping. Alert on ArcjetUnavailableError / ArcjetToolUnavailableError; a denial is the system working.

Python guard_tool and ArcjetMiddleware compose: a guarded tool called from a guarded agent evaluates once per policy. Pick the surface that matches what you hold. You don't need both for the same tool.

JavaScript:

• Authored tool(): guardTool. Returns a plain ArcjetDenialResult. Don't throw. Don't fabricate a ToolMessage.
• Agent-wide: guardMiddleware as createMiddleware({ wrapToolCall }). Returns a real ToolMessage with JSON content and default status. A bare object crashes the reducer. Don't set status: "error".
• Policy sits on wrapToolCall only. The middleware skips branded (guardTool) tools when it can look them up.

1
import { createAgent } from "langchain";
2
import { tool } from "@langchain/core/tools";
3
import { z } from "zod";
4
import { localDetectSensitiveInfo, tokenBucket } from "@arcjet/guard";
5
import { guardMiddleware, guardTool } from "@arcjet/guard/langchain/v1";
6
import { arcjet } from "./arcjet.js";
7

8
const lookupLimit = tokenBucket({
9
  bucket: "lookups",
10
  refillRate: 10,
11
  intervalSeconds: 60,
12
  maxTokens: 10,
13
});
14
const detectPii = localDetectSensitiveInfo();
15

16
const lookupOrder = guardTool(
17
  arcjet,
18
  tool(
19
    async ({ orderNumber, note }) => ({
20
      orderNumber,
21
      note,
22
      status: "shipped",
23
    }),
24
    {
25
      name: "lookup_order",
26
      description: "Look up an order by number",
27
      schema: z.object({
28
        orderNumber: z.string(),
29
        note: z.string(),
30
      }),
31
    },
32
  ),
33
  {
34
    action: "order.looked-up",
35
    rules: (input) => [
36
      lookupLimit({ key: input.orderNumber, requested: 1 }),
37
      detectPii(input.note),
38
    ],
39
  },
40
);
41

42
const agent = createAgent({
43
  model: "openai:gpt-4o",
44
  tools: [lookupOrder],
45
  middleware: [guardMiddleware(arcjet, { sessionId: conversationId })],
46
});

Scan the free-text note. An opaque orderNumber doesn't trip email, phone, card, or IP detection.

How does the editor and CI catch LangChain security bugs?

Turn on TypeScript strict or Pyright, a linter, and secret scanning in the editor. Run the same scanners in CI that you run locally—an editor warning that isn't a CI failure will be ignored.

Fail the build on secrets in the diff and on known vulnerable dependencies. None of these replace a review of the tools that you passed to create_agent / createAgent and the tools that you actually wrapped. They catch the mistakes that are cheap to find automatically.

What do you do after this guide?

Confirm each item against one sensitive turn: a prompt that asks for a refund, an authored tool that you call yourself, and a tool that the model picks by name. Then apply the LangGraph security guide if you own a StateGraph, and AI agent runtime security for sequence, budget, and identity controls.