@atbash/atbash-langgraph

Add Atbash as a safety guard inside a LangGraph workflow.

This package adds a guard node before tool execution and an audit node after, using native LangGraph interrupt semantics for HOLD verdicts.

Installation

npm install @atbash/atbash-langgraph

Peer dependencies:

npm install @langchain/core @langchain/langgraph

When To Use It

Use this package when:

• your app already uses LangGraph
• your graph has a distinct agent phase and tools phase
• you want HOLD to pause execution using LangGraph interrupt semantics
• you want audit logging after the tool phase

Quick Start

import { loadAgent } from "@atbash/sdk";
import { StateGraph, START, END, MemorySaver } from "@langchain/langgraph";
import { AtbashStateAnnotation, addAtbashSafety } from "@atbash/atbash-langgraph";

const builder = new StateGraph(AtbashStateAnnotation)
  .addNode("agent", agentNode)
  .addNode("tools", toolsNode)
  .addEdge(START, "agent")
  .addConditionalEdges("agent", routeAfterAgent);

addAtbashSafety(builder, {
  privkey: process.env.ATBASH_AGENT_PRIVKEY,
});

const app = builder.compile({ checkpointer: new MemorySaver() });

API

addAtbashSafety(builder, opts)

Convenience helper that wires atbash_guard and atbash_audit into your graph.

Assumes your graph has nodes named agent and tools. If your layout differs, use createGuardNode() and createAuditNode() directly.

| Option | Type | Description | |---|---|---| | privkey | string | Agent private key (falls back to ATBASH_AGENT_PRIVKEY env var) | | agent | AgentAuth | Pre-loaded agent (alternative to privkey) | | endpoint | string | Override Atbash endpoint |

createGuardNode(opts)

Creates the pre-tool safety node. Calls client.auditToolCall() for every tool call in the last AI message.

Returns a node function that writes atbashVerdict, atbashReason, atbashToolCallId to state.

createAuditNode(opts)

Creates the post-tool audit node. Fire-and-forget call to logToolCall() — errors are suppressed so they never break the graph.

AtbashStateAnnotation

Extends MessagesAnnotation with Atbash fields:

| Field | Type | Description | |---|---|---| | atbashVerdict | string \| null | Last verdict from the guard node | | atbashReason | string \| null | Reason from the judge | | atbashToolCallId | string \| null | Tool call ID for polling or HOLD resume | | atbashConfidence | number \| null | Confidence score |

createJudgeTool(agent, endpoint?)

Optional: creates an atbash_safety_check LangChain tool for direct LLM access to the judge.

Verdict Handling

| Verdict | Meaning | Graph Behavior | |---|---|---| | ALLOW | Safe to proceed | Routes to tools node | | HOLD | Needs human review | Graph interrupts; resume with Command({ resume: "approve" }) | | BLOCK | Policy violation | Injects blocked ToolMessage; routes back to agent | | ERROR | Judge unreachable | Treated as BLOCK — fail closed |

HOLD / Resume Pattern

import { Command, isInterrupted } from "@langchain/langgraph";

const result = await app.invoke(input, config);

if (isInterrupted(result)) {
  const payload = result.__interrupt__[0]?.value;
  // show payload to operator ...

  const approved = await app.invoke(
    new Command({ resume: "approve" }),
    config,
  );
}

Environment Variables

| Variable | Required | Description | |---|---|---| | ATBASH_AGENT_PRIVKEY | Yes (if not passing agent) | Your Atbash agent private key | | ATBASH_ENDPOINT | No | Override the default Atbash endpoint (https://atbash.ai) |

What This Package Does Not Do

• It does not invent your graph structure.
• It does not automatically find your tool node if you use a custom layout.
• It does not execute operator review — it only exposes pause/resume mechanics.

Example

A runnable example is in examples/langgraph-runtime-agent/.

npm install && npm run build
ATBASH_AGENT_PRIVKEY=your_key_here node examples/langgraph-runtime-agent/run.mjs