feat(examples): add LangChain createAgent guardrails example

[davidmytton]

Adds examples/langchain-agent: a LangChain JS createAgent support agent protected by Arcjet Guard, alongside the mastra-agent / langgraph-agent / claude-agent siblings. Registered in the root README and scripts/prepare-to-publish.ts.

This is createAgent + wrapToolCall, not LangGraph's StateGraph + ToolNode (that is langgraph-agent). Docs slug is /guards/langchain-js/.

// Authored tool → guardTool. DENY returns a plain ArcjetDenialResult;
// createAgent's baseHandler wraps it in a success ToolMessage.
const lookupOrder = guardTool(arcjet, tool(handler, { name: "lookup_order", schema }), {
  action: "order.looked-up",
  onGuardError: "deny",
  rules: ({ orderId, note }) => [
    lookupLimit({ key: `order:${orderId}`, requested: 1 }),
    ...(note ? [detectPii(note)] : []),
  ],
});

// Unwrapped / MCP-like tool → guardMiddleware. wrapToolCall DENY returns a
// real ToolMessage without calling handler. Branded tools are skipped.
const agent = createAgent({
  model,
  tools: [lookupOrder, notifyWarehouse],
  middleware: [guardMiddleware(arcjet, { onGuardError: "deny", rules })],
});

// No guardInbound: screen before invoke, and act on both outcomes.
const decision = await arcjet.guard({
  label: "message.received",
  rules: [detectInjection(text)],
  ...langchainContext(config),
});
if (decision.conclusion === "DENY" || decision.hasFailedOpen()) return blocked();

await agent.invoke({ messages }, { configurable: { thread_id: conversationId } });

The two denial envelopes stay distinct: guardTool returns a plain object, wrapToolCall must return a real ToolMessage (a bare object crashes the messages reducer). Neither sets status: "error" and neither throws, so denials are read as arcjetDenied on the payload. humanInTheLoopMiddleware is HITL, not a policy gate — it appears only as a comment, and nothing denies in afterModel. thread_id is caller-owned and never minted.

Vendor pin. @arcjet/guard/langchain/v1 merged in arcjet-js#6248 (c49abcc1) but is not on npm yet, so @arcjet/guard is pinned to file:./vendor/arcjet-guard, same as langgraph-agent / claude-agent. SHA is in vendor/SOURCE.txt. Draft until that ships.

Verified. biome lint, tsc --noEmit, npm audit, and npm ci all clean. Behaviour exercised through a real createAgent loop with FakeToolCallingModel: inbound fail-closed, both DENY envelopes with the handler never running, ALLOW still reaching it, and a branded tool guarded exactly once. Also asserted rules receives real tool args — otherwise the rate-limit key would silently be order:undefined and the PII scan would never run.

  

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​langchain/​openai@​1.2.8
	npm/​langchain@​1.5.10
	npm/​@​langchain/​core@​1.2.9

View full report

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

• npm/@langchain/langgraph-checkpoint@1.1.5
• npm/@langchain/openai@1.2.8
• npm/langsmith@0.9.0

View full report

[arcjet-review]

Arcjet Review — 🟡 Medium Risk

Decision: Needs Review

Rationale: Author explicitly marks the PR as Draft pending a published @arcjet/guard release to replace the vendored file: dependency, so this is not ready to merge on that ground alone. Beyond the vendor-pin gate, the change is a new self-contained example (mirrors existing langgraph-agent / claude-agent siblings), introduces a new package.json and Dockerfile (dependency-changes and ci-cd-changes triggers), and ships an intentionally unauthenticated /api/agent demo endpoint. Diff size (>1000 lines) is dominated by the vendored README and SKILL.md rather than executable code. Code-level review of index.ts / lib/agent.ts / lib/arcjet.ts shows input validation, fail-closed defaults on the guard, correct two-envelope denial handling, and no hardcoded secrets — but a human should confirm the vendored dist matches the recorded SHA and repin before merge.

Summary of Changes

Adds examples/langchain-agent, a new standalone LangChain JS createAgent example protected by Arcjet Guard, with an unauthenticated demo HTTP server, a Dockerfile, and a vendored @arcjet/guard build (file:./vendor/arcjet-guard pinned to arcjet/arcjet-js c49abcc1, pending npm release). Registered in the root README and scripts/prepare-to-publish.ts.

Escalation Triggers

• Dependency Changes: New examples/langchain-agent/package.json with langchain, @langchain/core, @langchain/openai, zod, and a file:./vendor/arcjet-guard dependency for an unreleased subpath.
• CI/CD Pipeline: New examples/langchain-agent/Dockerfile (author notes it is unverified because no Docker daemon is available in the devcontainer).

Security Flags

• [LOW] Authentication & Authorization (examples/langchain-agent/index.ts:65): The /api/agent endpoint is unauthenticated and the server binds to 0.0.0.0. This is explicitly documented as a local demo pattern (matching sibling examples) and the README warns against deploying without adding auth/rate limiting, so it is intended behaviour — flagging so a human reader can confirm the demo scope is acceptable for this repo.
• [MEDIUM] Vulnerable Components / Supply Chain (examples/langchain-agent/package.json:29): @arcjet/guard is pinned to a vendored directory (file:./vendor/arcjet-guard) built from arcjet/arcjet-js@c49abcc1 rather than a published npm release. The recorded SHA in vendor/SOURCE.txt should be re-verified against the vendored dist/ before merge, and the pin swapped to the published version once shipped. The Files Changed list does not include vendor/arcjet-guard/dist/**, so a human should confirm the dist/ tree is present in the branch and matches the SHA the author claims to have byte-compared.
• [LOW] Insufficient Logging / Error Handling (examples/langchain-agent/index.ts:78): The /api/agent catch block echoes error.message back to the client with status 500 (e.g. an 'AI_GATEWAY_API_KEY is required' string), which can leak internal configuration hints. Acceptable for a local demo but worth flagging.

Review Focus Areas

• Before merge, confirm the vendor pin has been swapped for a published @arcjet/guard version that actually exports the langchain/v1 subpath, and that peer ranges (langchain >=1.2.0 <2, @langchain/core >=1 <2) still hold.
  Author explicitly states the PR is draft pending this repin; merging with a file: dependency to a vendored monorepo subdirectory is not appropriate for a published example.
• Verify the recorded SHA c49abcc1f9afce7d284b6c294d0dcee5916ada86 matches the vendored dist/ contents (which are not visible in this diff) and that this is a merge commit on arcjet-js main, not a dangling branch build.
  The dist/ tree is what runs; the author's byte-identity claim is the only assurance without a diff of the compiled output.
• Is the unauthenticated /api/agent endpoint plus 0.0.0.0 bind acceptable given how this example is distributed (docker-build.yml matrix excluded, README warning present)?
  Matches sibling langgraph-agent / claude-agent pattern, but worth a conscious human sign-off since it forwards user text into a paid model call.
• In guardMiddleware's rules callback, when readOrderId(input) is undefined the token bucket key falls back to order:${toolName} (i.e. order:notify_warehouse). Is that the intended shared-bucket-per-tool behaviour, or should the middleware skip rate limiting when no orderId is present?
  Silent fallback keys can make a rate limit look scoped-per-order when in fact all callers share one bucket.

Notes

Diff exceeds the 1000-line size threshold, but the bulk is the vendored @arcjet/guard README (~2100 lines) and SKILL.md (~300 lines). Executable example code (index.ts, lib/agent.ts, lib/arcjet.ts, index.html) is well under 800 lines and reads cleanly. vendor/arcjet-guard/dist/** is referenced by package.json's main/types/exports but does not appear in the Files Changed list — either the path filter excluded it or the dist is missing; a human should confirm on the branch.

Path filtering: 77 files excluded by ignore paths. 22 of 99 files included in review.

_{Review: 2abe7c2f | Model: anthropic/claude-opus-4-7 | Powered by Arcjet Review}

[davidmytton]

@SocketSecurity ignore npm/langsmith@0.9.0

[arcjet-rei]

Do we want to vendor the SDK in the GH tree, or create a build job to bootstrap a vendor directory when the build is run on the example on download? The way this is set up right now, a very small percentage of the code is actually the example, and the rest is vendored SDK code.

[davidmytton]

It's vendored temporarily until we do the SDK release. We can remove it all afterwards

[davidmytton]

@SocketSecurity ignore npm/@langchain/openai@1.2.8

[arcjet-rei]

Now that we have a published version of the SDK that includes the LangChain helplers, should this be regenerated to not vendor the SDK?

[davidmytton]

Now that we have a published version of the SDK that includes the LangChain helplers, should this be regenerated to not vendor the SDK?

Yep - removed in c04c433

[davidmytton]

@SocketSecurity ignore npm/@langchain/langgraph-checkpoint@1.1.5