feat(sdk): support headless tools

[Christian Bromann (christian-bromann)]

This enables browser tools on the SDK side.

Most AI agents run entirely server-side, which means they can't touch the device in front of the user: no GPS, no clipboard, no camera, no local storage. Headless tools solve this by splitting tool execution across the boundary. The agent (on the server) decides when to call a tool and what arguments to pass — but the actual execution happens in the browser, where those APIs live. The result is sent back and the agent continues as if the tool had run locally.

The mechanism uses LangGraph's existing interrupt/resume primitive, so no new server infrastructure is needed. When the agent calls a headless tool, the graph pauses and emits an interrupt with the tool call details. useStream picks this up, runs the registered implementation in the browser context, and resumes the graph with the result — automatically, with no manual interrupt handling required by the app developer.

Tools are defined without an implementation on the server using tool() from langchain/tools. The client wires up the implementation separately via .implement():

// Server (agent definition) — no implementation, just the shape
import { tool } from "langchain";

export const getLocation = tool({
  name: "get_location",
  description: "Get the user's current GPS location",
  schema: z.object({ highAccuracy: z.boolean().optional() }),
});

// Client (useStream) — implementation runs in the browser
useStream({
  assistantId: "agent",
  tools: [
    getLocation.implement(async ({ highAccuracy }) =>
      new Promise((resolve, reject) =>
        navigator.geolocation.getCurrentPosition(
          (pos) => resolve({ lat: pos.coords.latitude, lng: pos.coords.longitude }),
          (err) => reject(new Error(err.message)),
          { enableHighAccuracy: highAccuracy }
        )
      )
    ),
  ],
});

The hook handles interrupt detection, execution, error propagation, and resume internally.

To demonstrate the pattern end-to-end, this PR ships two examples:

• Browser memory agent — long-term memory stored entirely in the browser's IndexedDB. Five headless tools (put, get, list, search, forget) persist context across sessions with data that never leaves the device.
• Canvas drawing agent — an agent that drives an HTML <canvas> element directly via sixteen drawing tools (shapes, paths, gradients, transforms, filters). All rendering happens client-side with no image round-trips to the server.

Related

• tool() headless tool primitive in LangChainJS: langchain-ai/langchainjs#10430

[changeset-bot]

🦋 Changeset detected

Latest commit: 8b44f26

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@langchain/langgraph	Minor
@langchain/angular	Minor
@langchain/react	Minor
@langchain/svelte	Minor
@langchain/vue	Minor
@example/ai-elements	Patch
@examples/assistant-ui-claude	Patch
@examples/ui-angular	Patch
langgraph	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@langchain/langgraph-checkpoint

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint@2192

@langchain/langgraph-checkpoint-mongodb

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-mongodb@2192

@langchain/langgraph-checkpoint-postgres

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-postgres@2192

@langchain/langgraph-checkpoint-redis

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-redis@2192

@langchain/langgraph-checkpoint-sqlite

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-sqlite@2192

@langchain/langgraph-checkpoint-validation

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-validation@2192

create-langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/create-langgraph@2192

@langchain/langgraph-api

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-api@2192

@langchain/langgraph-cli

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cli@2192

@langchain/langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph@2192

@langchain/langgraph-cua

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cua@2192

@langchain/langgraph-supervisor

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-supervisor@2192

@langchain/langgraph-swarm

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-swarm@2192

@langchain/langgraph-ui

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-ui@2192

@langchain/langgraph-sdk

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-sdk@2192

@langchain/angular

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/angular@2192

@langchain/react

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/react@2192

@langchain/svelte

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/svelte@2192

@langchain/vue

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/vue@2192

commit: 8b44f26

[Christian Bromann (christian-bromann)]

Enhanced example to show how to combine HITL with frontend tools: