fix(sdk): detect interrupt for Python agents (#2285)

Author: christian-bromann

.changeset/flat-apricots-laugh.md

@@ -0,0 +1,9 @@
+---
+"@langchain/angular": patch
+"@langchain/react": patch
+"@langchain/svelte": patch
+"@langchain/vue": patch
+"@langchain/langgraph-sdk": patch
+---
+
+fix(sdk): detect interrupt for Python agents

libs/sdk-angular/src/index.ts

@@ -598,6 +598,14 @@ export type {
   ToolCallFromTool,
   ToolCallsFromTools,
 } from "@langchain/langgraph-sdk";
+export type {
+  HeadlessToolImplementation,
+  AnyHeadlessToolImplementation,
+  ToolEvent,
+  HeadlessToolInterrupt,
+  OnToolCallback,
+  FlushPendingHeadlessToolInterruptsOptions,
+} from "@langchain/langgraph-sdk";
 
 export {
   SubagentManager,
@@ -606,3 +614,13 @@ export {
   extractParentIdFromNamespace,
   isSubagentNamespace,
 } from "@langchain/langgraph-sdk/ui";
+export {
+  isHeadlessToolInterrupt,
+  parseHeadlessToolInterruptPayload,
+  filterOutHeadlessToolInterrupts,
+  findHeadlessTool,
+  executeHeadlessTool,
+  handleHeadlessToolInterrupt,
+  headlessToolResumeCommand,
+  flushPendingHeadlessToolInterrupts,
+} from "@langchain/langgraph-sdk";

libs/sdk-react/src/index.ts

@@ -105,6 +105,7 @@ export {
 } from "@langchain/langgraph-sdk/ui";
 export {
   isHeadlessToolInterrupt,
+  parseHeadlessToolInterruptPayload,
   filterOutHeadlessToolInterrupts,
   findHeadlessTool,
   executeHeadlessTool,

libs/sdk-svelte/src/index.ts

@@ -456,6 +456,14 @@ export type {
   ToolCallFromTool,
   ToolCallsFromTools,
 } from "@langchain/langgraph-sdk";
+export type {
+  HeadlessToolImplementation,
+  AnyHeadlessToolImplementation,
+  ToolEvent,
+  HeadlessToolInterrupt,
+  OnToolCallback,
+  FlushPendingHeadlessToolInterruptsOptions,
+} from "@langchain/langgraph-sdk";
 
 export {
   SubagentManager,
@@ -464,3 +472,13 @@ export {
   extractParentIdFromNamespace,
   isSubagentNamespace,
 } from "@langchain/langgraph-sdk/ui";
+export {
+  isHeadlessToolInterrupt,
+  parseHeadlessToolInterruptPayload,
+  filterOutHeadlessToolInterrupts,
+  findHeadlessTool,
+  executeHeadlessTool,
+  handleHeadlessToolInterrupt,
+  headlessToolResumeCommand,
+  flushPendingHeadlessToolInterrupts,
+} from "@langchain/langgraph-sdk";

libs/sdk-vue/src/index.ts

@@ -505,6 +505,14 @@ export type {
   ToolCallFromTool,
   ToolCallsFromTools,
 } from "@langchain/langgraph-sdk";
+export type {
+  HeadlessToolImplementation,
+  AnyHeadlessToolImplementation,
+  ToolEvent,
+  HeadlessToolInterrupt,
+  OnToolCallback,
+  FlushPendingHeadlessToolInterruptsOptions,
+} from "@langchain/langgraph-sdk";
 
 export {
   SubagentManager,
@@ -513,3 +521,13 @@ export {
   extractParentIdFromNamespace,
   isSubagentNamespace,
 } from "@langchain/langgraph-sdk/ui";
+export {
+  isHeadlessToolInterrupt,
+  parseHeadlessToolInterruptPayload,
+  filterOutHeadlessToolInterrupts,
+  findHeadlessTool,
+  executeHeadlessTool,
+  handleHeadlessToolInterrupt,
+  headlessToolResumeCommand,
+  flushPendingHeadlessToolInterrupts,
+} from "@langchain/langgraph-sdk";

libs/sdk/src/headless-tools.ts

@@ -3,6 +3,10 @@ import type { Interrupt } from "./schema.js";
 /**
  * Represents a headless tool interrupt payload emitted by LangChain's
  * schema-only `tool({ ... })` overload.
+ *
+ * Servers may serialize the nested tool call as `toolCall` (JS) or
+ * `tool_call` (Python). Use {@link parseHeadlessToolInterruptPayload} to
+ * normalize either shape before reading fields.
  */
 export interface HeadlessToolInterrupt {
   type: "tool";
@@ -13,6 +17,42 @@ export interface HeadlessToolInterrupt {
   };
 }
 
+/**
+ * Parses a headless-tool interrupt `value` from the graph. Accepts both
+ * `toolCall` (LangChain JS) and `tool_call` (Python / JSON snake_case).
+ */
+export function parseHeadlessToolInterruptPayload(
+  value: unknown
+): HeadlessToolInterrupt | null {
+  if (typeof value !== "object" || value == null) {
+    return null;
+  }
+  const v = value as Record<string, unknown>;
+  if (v.type !== "tool") {
+    return null;
+  }
+
+  const rawTc = v.toolCall ?? v.tool_call;
+  if (typeof rawTc !== "object" || rawTc == null) {
+    return null;
+  }
+  const tc = rawTc as Record<string, unknown>;
+  if (typeof tc.name !== "string") {
+    return null;
+  }
+
+  const id = typeof tc.id === "string" ? tc.id : undefined;
+
+  return {
+    type: "tool",
+    toolCall: {
+      id,
+      name: tc.name,
+      args: tc.args,
+    },
+  };
+}
+
 /**
  * Client-side implementation returned by `headlessTool.implement(...)`.
  */
@@ -55,17 +95,7 @@ export function filterOutHeadlessToolInterrupts<T extends { value?: unknown }>(
 export function isHeadlessToolInterrupt(
   interrupt: unknown
 ): interrupt is HeadlessToolInterrupt {
-  if (typeof interrupt !== "object" || interrupt == null) {
-    return false;
-  }
-
-  const value = interrupt as Record<string, unknown>;
-  return (
-    value.type === "tool" &&
-    typeof value.toolCall === "object" &&
-    value.toolCall != null &&
-    typeof (value.toolCall as Record<string, unknown>).name === "string"
-  );
+  return parseHeadlessToolInterruptPayload(interrupt) != null;
 }
 
 export function findHeadlessTool<Args = unknown, Output = unknown>(
@@ -204,8 +234,10 @@ export function flushPendingHeadlessToolInterrupts(
   const defer = options.defer ?? ((run) => run());
 
   for (const interrupt of interrupts as Interrupt[]) {
-    if (!isHeadlessToolInterrupt(interrupt.value)) continue;
-    const headlessInterrupt = interrupt.value;
+    const headlessInterrupt = parseHeadlessToolInterruptPayload(
+      interrupt.value
+    );
+    if (!headlessInterrupt) continue;
 
     const interruptId = interrupt.id ?? headlessInterrupt.toolCall.id ?? "";
     if (handledIds.has(interruptId)) continue;

libs/sdk/src/index.ts

@@ -79,6 +79,7 @@ export type {
 } from "./headless-tools.js";
 export {
   isHeadlessToolInterrupt,
+  parseHeadlessToolInterruptPayload,
   filterOutHeadlessToolInterrupts,
   findHeadlessTool,
   executeHeadlessTool,

libs/sdk/src/react/index.ts

@@ -80,6 +80,7 @@ export {
 } from "../ui/subagents.js";
 export {
   isHeadlessToolInterrupt,
+  parseHeadlessToolInterruptPayload,
   filterOutHeadlessToolInterrupts,
   findHeadlessTool,
   executeHeadlessTool,

libs/sdk/src/ui/hitl-interrupt-payload.test.ts

@@ -6,6 +6,7 @@ import {
   filterOutHeadlessToolInterrupts,
   flushPendingHeadlessToolInterrupts,
   headlessToolResumeCommand,
+  parseHeadlessToolInterruptPayload,
 } from "../headless-tools.js";
 
 async function flushMicrotasks(count = 4) {
@@ -142,6 +143,54 @@ describe("headless tool interrupt helpers", () => {
     ]);
   });
 
+  it("treats Python snake_case tool_call as headless for filtering", () => {
+    const interrupts = [
+      {
+        id: "tool-int",
+        value: {
+          type: "tool" as const,
+          tool_call: {
+            id: "call-1",
+            name: "geolocation_get",
+            args: { high_accuracy: null },
+          },
+        },
+      },
+      {
+        id: "hitl-int",
+        value: {
+          action_requests: [
+            { action_name: "approve", args: {}, description: "" },
+          ],
+        },
+      },
+    ];
+
+    expect(filterOutHeadlessToolInterrupts(interrupts)).toEqual([
+      interrupts[1],
+    ]);
+  });
+
+  it("normalizes Python tool_call via parseHeadlessToolInterruptPayload", () => {
+    expect(
+      parseHeadlessToolInterruptPayload({
+        type: "tool",
+        tool_call: {
+          id: "call_heTfkJwAH7gjuxHXMANzQKTJ",
+          name: "geolocation_get",
+          args: { high_accuracy: null },
+        },
+      })
+    ).toEqual({
+      type: "tool",
+      toolCall: {
+        id: "call_heTfkJwAH7gjuxHXMANzQKTJ",
+        name: "geolocation_get",
+        args: { high_accuracy: null },
+      },
+    });
+  });
+
   it("builds a keyed resume command for tool call results", () => {
     expect(
       headlessToolResumeCommand({
@@ -237,4 +286,46 @@ describe("headless tool interrupt helpers", () => {
 
     expect(resumeSubmit).not.toHaveBeenCalled();
   });
+
+  it("flushes headless tool interrupts serialized with Python tool_call", async () => {
+    const handled = new Set<string>();
+    const onTool = vi.fn();
+    const resumeSubmit = vi.fn();
+
+    flushPendingHeadlessToolInterrupts(
+      {
+        __interrupt__: [
+          {
+            id: "py-headless",
+            value: {
+              type: "tool",
+              tool_call: {
+                id: "call-1",
+                name: "get_location",
+                args: { high_accuracy: false },
+              },
+            },
+          },
+        ],
+      },
+      [
+        {
+          tool: { name: "get_location" },
+          execute: async () => ({ latitude: 1, longitude: 2 }),
+        },
+      ],
+      handled,
+      { onTool, resumeSubmit }
+    );
+
+    await flushMicrotasks();
+
+    expect(resumeSubmit).toHaveBeenCalledWith({
+      resume: {
+        "call-1": { latitude: 1, longitude: 2 },
+      },
+    });
+    expect(handled.has("py-headless")).toBe(true);
+    expect(onTool).toHaveBeenCalledTimes(2);
+  });
 });