[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字段提供具体的工具调用信息。

fromtypingimportAnyfromlangchain.agentsimportcreate_agentfromlangchain.toolsimportToolRuntime,toolfromlanggraph.checkpoint.memoryimportMemorySaverfromlangchain_openaiimportChatOpenAIfromlanggraph.typesimportCommand,interrupt,Interruptfromlangchain_core.runnablesimportRunnableConfigfrompydanticimportBaseModelfromdotenvimportload_dotenv load_dotenv()classGetWeatherInput(BaseModel):city:str@tool("get_weather",description="Get specified city's weater",args_schema=GetWeatherInput,)defget_weather(city:str,runtime:ToolRuntime)->Any:returninterrupt({"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")defget_weather_client(city:str)->str:returnf"{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)formsginresult["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组件。

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