[AG-UI详解-08]AG-UI客户端工具 V.S. LangChain的Headless工具

如果将Agent发布为AG-UI Server，意味着前端应用可以提供在本地执行的工具函数，具体的编程模式可以参考我的文章AG-UI详解-07:AG-UI针对MAF的客户端实现。LangChain提供了另一种在客户端执行工具函数的能力，被成为Headless工具。

1. 什么是Headless工具

Headless工具允许Agent调用那些实际执行必须在用户应用而非服务器端进行的工具。Agent仍然可以看到标准的工具架构，但实际实现位于前端，因此它可以访问浏览器 API，例如IndexedDB、地理位置、剪贴板、画布或文件选择器。当数据需要保留在设备本地时，这种模式尤其有用。本页的示例使用了一个基于IndexedDB的小型浏览器内存工具包，以及一个完全在客户端运行的地理位置工具。

Headless（无头）这个词是计算机科学领域的一个经典行业术语，其核心含义是剥离了前端展示层或用户界面的系统 。这里的头（Head）指的就是用户可以直接看到和交互的界面或执行终点。在传统架构中，Agent的工具是有头有身体的完整个体------定义和实际执行代码都在服务器端。

而在 Headless工具中，LangChain把工具斩首 了：留在服务器端（工具的Schema）的是没有实际执行身体的隐形头。它只用来告诉大模型这个工具叫什么、有什么用。移到客户端的（工具的实现）是真正干活的身体。因为在服务器端的Agent看来，这个工具只有声明、没有本地执行实体（没有具体的代码落脚点），就像一个悬空的无头概念，真正的执行必须去别的地方（客户端）寻找身体。

2. Headless工具的工作原理

从宏观层面来看，Headless工具将工具的Schema与客户端提供的实现分开，具体的实现原理如下：

• 在Agent上注册一个工具，工具的实现会生成一个中断，并将工具调用相关信息（工具函数名称、调用ID和参数列表）作为中断值；
• 客户端调用Agent并捕捉中断，并提取工具调用信息在本地指向具体的操作，最后结果作为Resume Value再次发起回复调用。

以如下这个演示程序为例。我们在调用create_agent函数时注册了工具函数get_weather根据指定的城市提取当前的天气信息。但是该函数并没有提供真正的实现，而是调用interrupt函数产生一个中断。作为中断值的对象是一个字段，我们通过将type字段设置为tool表明这是一个针对工具调用的中断，并通过tool_call字段提供具体的工具调用信息。

from typing import Any

from langchain.agents import create_agent
from langchain.tools import ToolRuntime, tool
from langgraph.checkpoint.memory import MemorySaver
from langchain_openai  import ChatOpenAI
from langgraph.types import Command, interrupt, Interrupt
from langchain_core.runnables import RunnableConfig
from pydantic import BaseModel
from dotenv import load_dotenv

load_dotenv()

class GetWeatherInput(BaseModel):
    city: str

@tool(
    "get_weather",
    description="Get specified city's weater",
    args_schema=GetWeatherInput,
)
def get_weather(city: str, runtime: ToolRuntime) -> Any:
    return interrupt({
           "type": "tool",
           "tool_call": {
               "id": runtime.tool_call_id,
               "name": "get_weather",
               "args": {"city":city},
           },
       })

agent = create_agent(
    model=ChatOpenAI(model="gpt-5.4-mini"),
    tools=[get_weather],
    checkpointer=MemorySaver(),
)

config = RunnableConfig({"configurable":{"thread_id":"123"}})
result = agent.invoke(
    input={"messages":[{"role":"user", "content":"根据苏州天气提供着装建议"}]},
    config=config,
    version="v2")

def get_weather_client(city:str)->str:
    return f"{city}, 晴，气温35摄氏度"

irpt:Interrupt = result.interrupts[-1]
print(f"""\
Interrupt hanppens
    ID: {irpt.id}, 
    Value: {irpt.value}""")

result = agent.invoke(input= Command(resume=  get_weather_client(**irpt.value["tool_call"]["args"]),) ,config=config)
for msg in result["messages"]:
    msg.pretty_print()

由于中断涉及基于Checkpointing的持久化，所以我们注册了了一个MemorySaver对象作为Checkpointer。我们创建了一个封装了ThreadId的RunnableConfig，并将其作为参数对Agent发起调用，指定的提示词为根据苏州天气提供着装建议。我们从调用结果中提取中断对象并将其输出，具体的输出形式如下：

Interrupt hanppens
    ID: 36a23e62f0e1384fd8ad3c82553ea36b, 
    Value: {'type': 'tool', 'tool_call': {'id': 'call_Q3Wc4ztMeS5GWDvRjrPX9Mse', 'name': 'get_weather', 'args': {'city': '苏州'}}}

然后我们提取工具调用的参数，并将其作为输入调用客户端函数get_weather_client返回真正的天气信息。我们使用同一个RunnableConfig对Agent发起恢复调用，并将作为客户端函数执行结果的天气信息作为Resume Value。在得到调用结果后，我们提取出对话历史并将其打印出来。 从如下的输出看出，这与我们常规注册服务端工具函数并无不同。

================================ Human Message =================================

根据苏州天气提供着装建议
================================== Ai Message ==================================
Tool Calls:
  get_weather (call_Q3Wc4ztMeS5GWDvRjrPX9Mse)
 Call ID: call_Q3Wc4ztMeS5GWDvRjrPX9Mse
  Args:
    city: 苏州
================================= Tool Message =================================
Name: get_weather

苏州, 晴，气温35摄氏度
================================== Ai Message ==================================

苏州现在是**晴天，35°C**，天气比较炎热，建议这样穿：

- **上衣**：短袖T恤、薄款衬衫、透气速干衣
- **下装**：短裤、薄长裤或轻薄裙装
- **鞋子**：透气运动鞋、凉鞋或休闲鞋
- **配件**：太阳镜、遮阳帽、防晒霜，尽量带水

补充建议：
- 白天尽量选择**浅色、宽松、透气**的面料
- 如果长时间在户外，记得**防晒和补水**
- 室内空调较强的话，可随身带一件**薄外套**以防温差

如果你愿意，我也可以按**通勤 / 运动 / 约会**场景给你更具体的穿搭建议。

3. AG-UI客户端和Headless工具的区别

在现代 AI Agent架构中，Headless工具和AG-UI客户端工具都是为了解决让工具代码运行在用户前端（如浏览器、手机 App）而非服务器端而设计的。但它们的核心意图和在大模型推理流中的位置截然不同：

• Headless工具 ：专注于数据与能力获取。它扩展的是Agent的思考能力。大模型通过中断机制，向前端索要服务器拿不到的数据（如本地剪贴板、GPS、本地数据库）。用户通常"看不见"这个工具的执行过程，只能看到大模型拿到数据后生成的最终文本答案；
• AG-UI客户端工具 ：专注于交互与视觉呈现 。它扩展的是Agent的表达能力。大模型通过输出结构化数据，直接在聊天界面中渲染出一个动态的、可交互的组件（如座位挑选器、动态股票图表、支付按钮）。用户会直观地看到并操作这个UI组件。

两者在技术实现方面也不一样：

• Headless工具的数据管道：大模型在思考时因为遇到中断而卡住并暂停。它向前端要数据，等前端以Resume Value的形式喂回来后，大模型继续往下思考；
• AG-UI客户端工具渲染管道：大模型已经完成了思考，生成了一个包含组件参数的工具调用。后端把这个工具调用以JSON形式传给前端，前端根据这个JSON在聊天框里挂载对应的React/Vue组件。

下面这个表格对两种的对比做了一个总结：

维度	无头工具 (Headless Tools)	AG-UI 客户端工具 (Agentic/Generative UI)
主要目的	安全地获取客户端专有数据或触发设备底层硬件 API。	在聊天流中直接渲染出丰富、直观、可交互的前端原生组件。
用户可见性	完全不可见（完全在浏览器后台静默运行）。	高度可见（在聊天时间线中直接卡片式挂载 UI 块）。
数据流向	客户端 ➡️ 服务器（把本地原生数据/状态喂回给大模型）。	服务器 ➡️ 客户端（把大模型生成的结构化参数作为 Props 传给前端渲染）。
所处阶段	处于大模型的 推理/思考循环（Reasoning Loop） 之中。	处于大模型的 输出/流式展现（Streaming Phase） 之中。
底层机制	服务器 interrupt（中断）与客户端 resume（恢复）握手。	生成式 UI 组件流式传输（如 Vercel AI SDK 或 LangChain Stream）。