无头工具

无头工具使您的智能体能够调用那些必须在用户应用程序中而非在服务器上实际执行的工具。智能体看到的仍然是一个普通的工具模式，但其具体实现位于前端，因此它可以访问浏览器 API，如 IndexedDB、地理位置、剪贴板、画布或文件选择器。当数据需要保存在设备本地时，这种模式特别有用。本页上的 Playground 示例使用了一套基于 IndexedDB 的小型浏览器记忆工具包，以及一个完全在客户端运行的地理位置工具。

无头工具的工作原理

从高层次看，无头工具将工具模式与仅在浏览器端运行的实现分离开来。

在智能体上注册一个工具，该工具立即调用 interrupt() 以将执行推迟到前端。
在前端的定义中映射相同的工具名称和参数字段。
使用 .implement(...) 在前端实现匹配的工具，并将它们传递给 useStream({ tools: [...] })。
当智能体调用一个匹配的工具时，客户端处理该操作并使用工具结果恢复被中断的运行。

在智能体上注册工具

Playground 定义了一小组遵循相同模式的客户端工具：智能体暴露一个工具模式，前端负责实际执行。在服务器上定义常规工具，这些工具立即调用 interrupt()，然后在前端的 tools.ts 文件中映射相同的工具名称和参数字段。

agent.py

from typing import Any

from langchain import create_agent
from langchain.tools import ToolRuntime, tool
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import interrupt
from pydantic import BaseModel


class MemoryPutInput(BaseModel):
    key: str
    value: Any


class MemoryGetInput(BaseModel):
    key: str


class GeolocationGetInput(BaseModel):
    save: bool = True


def _interrupt_for_client(
    tool_name: str,
    args: dict[str, Any],
    runtime: ToolRuntime,
) -> Any:
    return interrupt({
        "type": "tool",
        "tool_call": {
            "id": runtime.tool_call_id,
            "name": tool_name,
            "args": args,
        },
    })


@tool(
    "memory_put",
    description="在用户的浏览器中存储记忆。",
    args_schema=MemoryPutInput,
)
def memory_put(key: str, value: Any, runtime: ToolRuntime) -> Any:
    return _interrupt_for_client(
        "memory_put",
        {"key": key, "value": value},
        runtime,
    )


@tool(
    "memory_get",
    description="查找存储在用户浏览器中的记忆。",
    args_schema=MemoryGetInput,
)
def memory_get(key: str, runtime: ToolRuntime) -> Any:
    return _interrupt_for_client("memory_get", {"key": key}, runtime)


@tool(
    "geolocation_get",
    description="从浏览器获取用户当前位置。",
    args_schema=GeolocationGetInput,
)
def geolocation_get(runtime: ToolRuntime, save: bool = True) -> Any:
    return _interrupt_for_client(
        "geolocation_get",
        {"save": save},
        runtime,
    )

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[memory_put, memory_get, geolocation_get],
    checkpointer=MemorySaver(),
)

每个工具都使用一个结构化的有效载荷进行中断，前端可以处理该载荷，然后返回在运行恢复时提供的值。在客户端映射相同的工具名称和模式，以便前端可以附加实现。

tools.ts

import * as z from "zod";
import { tool } from "langchain";

// 在客户端映射 Python 工具的名称和模式。
export const memoryPut = tool({
  name: "memory_put",
  description: "在用户的浏览器中存储记忆。",
  schema: z.object({
    key: z.string(),
    value: z.unknown(),
  }),
});

export const memoryGet = tool({
  name: "memory_get",
  description: "查找存储在用户浏览器中的记忆。",
  schema: z.object({
    key: z.string(),
  }),
});

export const geolocationGet = tool({
  name: "geolocation_get",
  description: "从浏览器获取用户当前位置。",
  schema: z.object({
    save: z.boolean().optional(),
  }),
});

实现浏览器行为

将仅限客户端的行为放在一个单独的模块中，并使用 .implement(...) 将其附加。真实的 Playground 包含了一个更完整的 IndexedDB 存储，具有搜索、列表、过期和删除操作。以下示例在更高层次上展示了相同的结构：

impl.ts

import {
  geolocationGet as geolocationGetDefinition,
  memoryGet as memoryGetDefinition,
  memoryPut as memoryPutDefinition,
} from "./tools";

async function saveMemory(key: string, value: unknown) {
  localStorage.setItem(`agent-memory:${key}`, JSON.stringify(value));
}

async function getMemory(key: string) {
  const value = localStorage.getItem(`agent-memory:${key}`);
  return value ? JSON.parse(value) : null;
}

export const memoryPut = memoryPutDefinition.implement(async ({ key, value }) => {
  await saveMemory(key, value);
  return { success: true, key };
});

export const memoryGet = memoryGetDefinition.implement(async ({ key }) => {
  const value = await getMemory(key);
  return value === null ? { found: false, key } : { found: true, key, value };
});

export const geolocationGet = geolocationGetDefinition.implement(
  async ({ save = true }) => {
    const position = await new Promise<GeolocationPosition>((resolve, reject) =>
      navigator.geolocation.getCurrentPosition(resolve, reject),
    );

    const location = {
      latitude: position.coords.latitude,
      longitude: position.coords.longitude,
      accuracy: position.coords.accuracy,
    };

    if (save) {
      await saveMemory("user_location", location);
    }

    return location;
  },
);

将实现连接到 `useStream`

将已实现的工具传递给 useStream。当智能体发出匹配的工具调用时，该钩子会运行客户端实现并为您恢复运行。定义一个匹配您智能体状态模式的 TypeScript 接口，并将其作为类型参数传递给 useStream，以便类型安全地访问状态值：

types.ts

export interface AgentState {
  messages: BaseMessage[];
}

import { useStream } from "@langchain/react";

import { geolocationGet, memoryGet, memoryPut } from "./impl";
import type { AgentState } from "./types";

const AGENT_URL = "http://localhost:2024";

export function Chat() {
  const stream = useStream<AgentState>({
    apiUrl: AGENT_URL,
    assistantId: "headless_tools",
    tools: [memoryPut, memoryGet, geolocationGet],
  });

  return <ChatView messages={stream.messages} toolCalls={stream.toolCalls} />;
}

<script setup lang="ts">
import { useStream } from "@langchain/vue";

import { geolocationGet, memoryGet, memoryPut } from "./impl";
import type { AgentState } from "./types";

const AGENT_URL = "http://localhost:2024";

const stream = useStream<AgentState>({
  apiUrl: AGENT_URL,
  assistantId: "headless_tools",
  tools: [memoryPut, memoryGet, geolocationGet],
});
</script>

<template>
  <ChatView
    :messages="stream.messages.value"
    :tool-calls="stream.toolCalls.value"
  />
</template>

<script lang="ts">
  import { useStream } from "@langchain/svelte";

  import { geolocationGet, memoryGet, memoryPut } from "./impl";
  import type { AgentState } from "./types";

  const AGENT_URL = "http://localhost:2024";

  const { messages, toolCalls } = useStream<AgentState>({
    apiUrl: AGENT_URL,
    assistantId: "headless_tools",
    tools: [memoryPut, memoryGet, geolocationGet],
  });
</script>

<ChatView messages={$messages} toolCalls={$toolCalls} />

import { Component } from "@angular/core";
import { useStream } from "@langchain/angular";

import { geolocationGet, memoryGet, memoryPut } from "./impl";
import type { AgentState } from "./types";

const AGENT_URL = "http://localhost:2024";

@Component({
  selector: "app-chat",
  template: `
    <app-chat-view
      [messages]="stream.messages()"
      [toolCalls]="stream.toolCalls()"
    />
  `,
})
export class ChatComponent {
  stream = useStream<AgentState>({
    apiUrl: AGENT_URL,
    assistantId: "headless_tools",
    tools: [memoryPut, memoryGet, geolocationGet],
  });
}

内联渲染工具活动

Playground 将每个记忆或地理位置操作渲染为独立的卡片，并在输入框附近保留一个小型记忆统计面板。关键步骤是将 stream.toolCalls 中的每个条目映射回触发它的 AI 消息：

import type { ToolCallWithResult, DefaultToolCall } from "@langchain/react";

function Message({ message, toolCalls }: {
  message: AIMessage,
  toolCalls: ToolCallWithResult[]
}) {
  const messageToolCalls = toolCalls.filter((tc) =>
    message.tool_calls?.some((call) => call.id === tc.call.id),
  );

  return (
    <div>
      {message.text && <p>{message.text}</p>}
      {messageToolCalls.map((tc) => (
        <HeadlessToolCard key={tc.call.id} toolCall={tc} />
      ))}
    </div>
  );
}

这与工具调用中更丰富的 UI 模式配合得很好，其中每个工具结果都可以渲染为专门的卡片，而不是原始的 JSON。

用例

当工作依赖于仅存在于客户端的 API 或数据时，使用无头工具：

在 IndexedDB 或 localStorage 中的本地记忆
设备 API，如地理位置、剪贴板、摄像头或文件选择器
画布、音频或其他仅限浏览器的渲染原语
应保留在用户设备上的隐私敏感数据
需要直接访问内存中前端状态的 UI 操作

最佳实践

保持工具小巧且类型化。优先使用多个窄范围的工具，而不是一个通用的“运行任意浏览器代码”工具。
返回 JSON 可序列化的结果。不要尝试返回 DOM 节点、文件句柄或其他不可序列化的浏览器对象。
共享定义，分离实现。智能体和客户端应就工具名称和模式达成一致，但只有客户端应加载浏览器 API。
在 UI 中呈现工具状态。使用 stream.toolCalls 和 onTool 来显示待处理、成功和错误状态。
在需要时添加审查。对于敏感的客户端操作，将此模式与人在环中结合使用。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

无头工具的工作原理

在智能体上注册工具

实现浏览器行为

将实现连接到 `useStream`

内联渲染工具活动

用例

最佳实践

​无头工具的工作原理

​在智能体上注册工具

​实现浏览器行为

​将实现连接到 useStream

​内联渲染工具活动

​用例

​最佳实践

无头工具的工作原理

在智能体上注册工具

实现浏览器行为

将实现连接到 `useStream`

内联渲染工具活动

用例

最佳实践