tools

A headless tool that always interrupts agent execution on the server.

The implementation is provided separately on the client via useStream({ tools: [...] }) using .implement().

Configuration fields for creating a headless tool.

A tool implementation that pairs a headless tool with its execution function.

Created by calling .implement() on a HeadlessTool. Pass to useStream({ tools: [...] }) on the client side.

Unified tool primitive for LangChain agents.

Enhances the tool function from @langchain/core/tools with a headless overload: when called without an implementation function, the tool interrupts agent execution and lets the client supply the implementation.

Normal tool — pass an implementation function as the first argument:

import { tool } from "langchain/tools";
import { z } from "zod";

const getWeather = tool(
  async ({ city }) => `The weather in ${city} is sunny.`,
  {
    name: "get_weather",
    description: "Get the weather for a city",
    schema: z.object({ city: z.string() }),
  }
);

Headless tool — omit the implementation; the client provides it later:

import { tool } from "langchain/tools";
import { z } from "zod";

// Server: define the tool shape — no implementation needed
export const getLocation = tool({
  name: "get_location",
  description: "Get the user's current GPS location",
  schema: z.object({
    highAccuracy: z.boolean().optional().describe("Request high accuracy GPS"),
  }),
});

// Server: register with the agent
const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [getLocation],
});

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