LangChain.js

@kblockai/client/langchain turns the tools the Gateway lists for your agent into LangChain.js tools. Every call still goes through the Gateway, so policies, approvals and receipts apply as with the TypeScript client; the adapter only translates each outcome into something a LangChain agent understands.

Use it when your agent already runs on LangChain.js (@langchain/core). You pass the tools to your agent as you would any other tools; the model reads K-Block's explanation when a call is held or denied, and your code gets the typed result.

Install

The adapter is a subpath of @kblockai/client, not a separate package. It needs @langchain/core next to it:

npm install --save-exact @kblockai/client@0.1.0-rc.1
npm install @langchain/core@^1

@langchain/core is optional for the main entry point: you only need it if you import @kblockai/client/langchain.

What it provides

Each tool is a DynamicStructuredTool whose name, description and input schema are exactly what the Gateway lists (a tool listed without a description gets its name as description). It calls client.callTool and answers with responseFormat: "content_and_artifact":

• content: text the model can act on, from explainResult: the tool's output when the call completed; for approval_pending, that nothing ran yet and that the same call must be repeated after approval; for denied, the code, detail and the policy's explanation.
• artifact: the typed KBlockCallResult (see Outcomes), available as ToolMessage.artifact when the tool is invoked with a tool call.

Load and run the tools

This complete program loads the tools and runs one the way an agent executor runs a model's tool call, so you can try it without an LLM. Like every example on this page, it reads the Gateway URL and the agent's gateway API key from KBLOCK_GATEWAY_URL and KBLOCK_API_KEY, two environment variables of its own:

import { connectKBlock, type KBlockCallResult } from "@kblockai/client";
import { loadKBlockTools } from "@kblockai/client/langchain";

const client = await connectKBlock({
  gatewayUrl: process.env.KBLOCK_GATEWAY_URL ?? "", // e.g. https://gateway.example.com
  apiKey: process.env.KBLOCK_API_KEY ?? "", // the agent's gateway API key
});

// Every tool the Gateway lists for this agent. Pass `tools` to your agent.
const tools = await loadKBlockTools(client);
console.log(tools.map((t) => t.name));

// For example, a refund tool that your policy holds for approval above some amount.
const refund = tools.find((t) => t.name === "refund");
if (refund !== undefined) {
  // What an agent executor does with a model's tool call:
  const msg = await refund.invoke({
    name: refund.name,
    args: { order_id: "ord_123", amount: "250.00", currency: "USD" },
    id: "call_1",
    type: "tool_call",
  });
  const result = msg.artifact as KBlockCallResult;
  console.log(msg.status, result.status); // "error" "approval_pending" when the call is held
  console.log(String(msg.content)); // the explanation the model reads
}

await client.close();

When you invoke a tool with a tool call (as an agent does), it returns a ToolMessage. When you invoke it with plain arguments (await refund.invoke(args)), it returns only the text.

Refusals are tool errors

Every outcome other than completed (held for approval, denied, rejected, expired, cancelled, unavailable, an upstream that failed…) comes back, for a tool call, as a ToolMessage with status: "error". Code that routes on LangChain's own flag (LangGraph edges, evaluations, tracing) therefore never counts a refusal as a successful tool run. The model still reads the explanation as the message content, and the artifact keeps the exact K-Block status.

Transport errors (KBlockAuthError, KBlockRateLimitedError, KBlockUnavailableError, KBlockHttpError, KBlockProtocolError) throw, whatever the options, with one exception for agents: a call whose outcome is unknown (KBlockUnavailableError with outcomeUnknown: true, or KBlockProtocolError) invoked with a tool call is answered with a ToolMessage with status: "error" whose text says that the action may or may not have run and must not be repeated blindly. Its artifact is a KBlockUnknownOutcome (kblock_status: "outcome_unknown", code, tool, idempotency_key). Agent frameworks hand a thrown error to the model with an invitation to fix and retry, and a repeated call without an idempotency key is a new request that may run the action again. Invoked with plain arguments, the error is thrown. See Errors.

import { KBlockRefusalError, connectKBlock } from "@kblockai/client";
import { loadKBlockTools } from "@kblockai/client/langchain";

const client = await connectKBlock({
  gatewayUrl: process.env.KBLOCK_GATEWAY_URL ?? "",
  apiKey: process.env.KBLOCK_API_KEY ?? "",
});

// For code that runs the tools itself: refusals are thrown instead of answered.
const [refund] = await loadKBlockTools(client, { tools: ["refund"], throwOnRefusal: true });
try {
  console.log(await refund!.invoke({ order_id: "ord_123", amount: "2500.00", currency: "USD" }));
} catch (e) {
  if (e instanceof KBlockRefusalError) console.log("refused:", e.code, e.result.status);
  else throw e;
}

await client.close();

Approvals and repeated calls

The adapter's defaults differ from client.callTool in one important way: it sends no idempotency key unless you ask for one.

• When a call is held, the model reads that nothing ran and that it should call the tool again with exactly the same arguments after approval. An approver approves in the dashboard (Approvals, then Approve and sign).
• When the model repeats the identical call (same tool, same arguments), the Gateway finds the open action by the call's fingerprint and executes it once it is approved.
• Once that call has executed, an identical keyless call is a new request: the policy decides it again, so a call that needed approval needs a new approval and runs nothing until then.

With waitSeconds set, the model's repeat can wait for the decision instead of returning approval_pending again at once. A long wait keeps the agent's turn open for that long.

What can go wrong

Next steps