如果将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:strtool(get_weather,descriptionGet specified citys weater,args_schemaGetWeatherInput,)defget_weather(city:str,runtime:ToolRuntime)-Any:returninterrupt({type:tool,tool_call:{id:runtime.tool_call_id,name:get_weather,args:{city:city},},})agentcreate_agent(modelChatOpenAI(modelgpt-5.4-mini),tools[get_weather],checkpointerMemorySaver(),)configRunnableConfig({configurable:{thread_id:123}})resultagent.invoke(input{messages:[{role:user,content:根据苏州天气提供着装建议}]},configconfig,versionv2)defget_weather_client(city:str)-str:returnf{city}, 晴气温35摄氏度irpt:Interruptresult.interrupts[-1]print(f\ Interrupt hanppens ID:{irpt.id}, Value:{irpt.value})resultagent.invoke(inputCommand(resumeget_weather_client(**irpt.value[tool_call][args]),),configconfig)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组件。下面这个表格对两种的对比做了一个总结维度无头工具 (Headless Tools)AG-UI 客户端工具 (Agentic/Generative UI)主要目的安全地获取客户端专有数据或触发设备底层硬件 API。在聊天流中直接渲染出丰富、直观、可交互的前端原生组件。用户可见性完全不可见完全在浏览器后台静默运行。高度可见在聊天时间线中直接卡片式挂载 UI 块。数据流向客户端 ➡️ 服务器把本地原生数据/状态喂回给大模型。服务器 ➡️ 客户端把大模型生成的结构化参数作为 Props 传给前端渲染。所处阶段处于大模型的推理/思考循环Reasoning Loop之中。处于大模型的输出/流式展现Streaming Phase之中。底层机制服务器interrupt中断与客户端resume恢复握手。生成式 UI 组件流式传输如 Vercel AI SDK 或 LangChain Stream。