1. 从“不可能”到“可能”为什么要在浏览器里跑 AI Agent你可能觉得我疯了。AI Agent这个听起来就带着“云端算力”、“分布式推理”、“复杂编排”光环的概念怎么就和浏览器——这个我们每天用来刷网页、看视频的“轻量级”客户端扯上关系了传统的AI Agent框架无论是LangChain、AutoGPT还是微软的Semantic Kernel它们的典型部署场景都是服务器端。一个强大的后端服务连接着OpenAI、Anthropic等大模型的API处理着复杂的任务分解、工具调用和状态管理然后通过一个Web界面或者API把结果呈现给用户。这似乎是天经地义的架构。但我在实际工作中遇到了几个让我重新思考这个“天经地义”的痛点。首先是成本与延迟。每一次Agent的思考、每一次工具调用都意味着一次网络往返。对于需要快速交互、低延迟反馈的场景比如一个智能表单填写助手、一个实时代码审查插件这种延迟是难以忍受的。更别提那些按Token计费的API调用复杂的多轮思考链会迅速烧光预算。其次是数据隐私与安全性。很多场景下用户的数据极其敏感比如处理本地文档、分析个人财务表格、或者操作企业内部系统。把这些数据一股脑发送到云端Agent进行处理从合规和信任角度都存在巨大风险。用户和企业的第一反应往往是“我的数据能不能不出我的设备”最后是部署与集成的复杂性。为一个轻量级的小工具或一个内部效率插件去搭建和维护一整套后端Agent服务包括服务器、反向代理、依赖管理、监控告警这无疑是杀鸡用牛刀。开发者的初衷可能只是想给现有网页加一点“智能”却被迫陷入了基础设施的泥潭。正是这些痛点让我开始思考Agent的核心推理逻辑是否有可能完全在用户的浏览器环境中完成答案是肯定的而且时机已经成熟。现代浏览器特别是基于Chromium内核的如Chrome、Edge、新版Edge已经是一个功能极其强大的运行时环境。它支持WebAssembly可以本地运行高性能计算它提供了完善的Web API能够访问文件系统通过File API、麦克风、摄像头、地理位置它通过Service Worker支持后台任务和离线能力更重要的是它原生支持JavaScript/TypeScript而后者正是当前AI应用开发中最活跃的语言生态之一。于是“Web-Agent-Runtime”这个想法诞生了。这不是要取代强大的云端Agent而是开辟一个新的战场将AI Agent的能力“边缘化”、“轻量化”直接注入到最终用户交互的第一线——浏览器中。它不处理需要万亿参数模型完成的创造性写作但它非常适合处理那些基于清晰规则、本地数据、确定性工具调用的自动化任务。比如自动分析你上传的CSV文件并生成图表根据你正在浏览的网页内容自动提取关键信息并填充到笔记软件或者作为一个浏览器插件智能帮你填写重复的网页表单。这个框架的目标是让前端开发者也能以极低的门槛构建出拥有自主决策和行动能力的“智能体”并且保证这一切都在用户可控、可信的本地环境中发生。听起来是不是有点意思了接下来我就带你拆解一下这样一个“跑在浏览器里的AI Agent框架”到底是怎么造出来的。2. 核心架构拆解在沙箱中构建“大脑”与“手脚”把一个AI Agent塞进浏览器绝不是简单地把Python代码用Transcrypt转译成JavaScript那么简单。它需要一套全新的架构设计来适应浏览器环境的独特约束和优势。我设计的这个框架核心思想是**“轻量级内核”与“模块化工具链”**的结合。整个框架的运行时架构可以概括为以下几个层次2.1 推理引擎层LLM的本地化接入这是Agent的“大脑”。在浏览器中我们无法部署一个完整的百亿参数大模型但我们可以巧妙地利用两种资源本地小型语言模型通过WebAssembly或WebGPU可以运行像Gemma 2B、Phi-2、Qwen1.5-1.8B这样经过高度量化如GGUF格式的“小模型”。这些模型参数在1B到7B之间经过量化后模型文件可能在几百MB到几个GB虽然能力无法与GPT-4媲美但对于理解用户指令、进行简单的逻辑推理和规划已经足够。框架需要集成一个通用的模型加载器和推理器例如基于transformers.js或专门优化的WASM推理库如llama.cpp的Web版本。云端大模型的“瘦客户端”对于更复杂的思考我们仍然可以调用云端API。但框架的设计关键在于“智能分流”。简单的、对延迟敏感的任务由本地小模型处理复杂的、需要创造性的任务则由框架代理发起对云端API的调用。框架需要统一这两者的接口让上层的Agent逻辑无需关心思考到底发生在哪里。一个核心的优化是缓存与预热将常见的指令-回复对或思维链模板缓存在IndexedDB中下次遇到类似请求时直接复用极大减少对云端或本地模型的调用。2.2 工具系统层赋予Agent“手脚”这是Agent能与外界交互的关键。浏览器的Web API本身就是一套强大的工具集。我的框架将常用能力封装成了标准的“工具”接口BrowserTool控制浏览器本身如导航到新页面、点击元素、填写输入框、读取DOM内容。这依赖于框架注入的Content Script如果作为扩展或直接使用document.querySelector等API。FileSystemTool通过File API读取用户选择的文件内容文本、CSV、JSON甚至通过File System Access API在用户授权后对本地文件进行读写。NetworkTool发起跨域请求需处理CORS或同源请求获取网络数据。这可以用来调用一些开放的REST API。CalculationTool进行数学计算、日期处理、字符串操作等纯逻辑任务。StorageTool利用localStorage或sessionStorage进行键值对存储让Agent拥有“记忆”。每个工具都实现一个统一的execute(params)方法并提供一个清晰的description用于让LLM理解该工具的功能。例如BrowserTool.click的描述可能是“点击页面上与给定CSS选择器匹配的第一个元素”。2.3 任务规划与执行层Agent的“中枢神经”这一层负责将用户的自然语言指令转化为一系列具体的工具调用。它包含几个核心模块指令解析器接收用户输入调用LLM本地或云端进行意图识别和任务分解。例如用户说“帮我把这个页面上的产品价格保存成表格”解析器需要输出一个任务链[“提取所有价格元素” “整理成结构化数据” “生成CSV文件” “触发下载”]。规划器为任务链中的每一步动态选择最合适的工具并生成调用参数。这通常通过一个特定的“规划”提示词模板让LLM根据当前状态和可用工具列表来决定下一步行动。框架需要维护一个工具注册表动态地向规划器报告当前可用的工具。状态执行器按顺序执行规划好的工具调用。这是最需要稳健性的部分。它需要处理工具执行失败如元素未找到、网络超时、权限拒绝等异常并能根据预设策略进行重试或回退到替代方案。执行器还需要维护一个共享状态供不同工具之间传递数据。比如BrowserTool提取的文本可以存入状态然后被FileSystemTool用来生成文件。2.4 安全沙箱与生命周期管理层这是在浏览器环境中独有的、至关重要的层。浏览器是一个多标签页、事件驱动的环境Agent不能阻塞主线程也不能无限制运行。异步与中断所有耗时的操作LLM推理、网络请求、大文件读取都必须是异步的基于Promise/async-await。框架必须提供优雅的中断机制允许用户随时停止一个长时间运行的Agent任务。权限隔离作为浏览器扩展或运行在特定网页中的脚本其权限受到严格限制。框架必须明确声明所需的权限如activeTab,storage,webRequest等并在工具调用时处理权限不足的异常引导用户授权。资源管理需要监控内存和CPU使用防止本地模型推理耗尽用户设备资源。可以设置推理时间上限、自动清理中间状态等。这个架构的核心是将AI Agent从厚重的“云端服务”解构为一个个可以在浏览器安全沙箱内协同工作的“功能模块”。开发者就像拼乐高一样为自己的场景组合需要的工具和规划逻辑。3. 实战从零构建一个“智能数据提取”Agent理论说再多不如动手写一行代码。让我们用这个框架假设我们把它命名为WebAgent来构建一个真实的场景一个浏览器插件能够智能识别网页上的表格或列表数据并一键导出为结构化的JSON或CSV文件。3.1 环境准备与项目初始化首先我们创建一个新的浏览器扩展项目。使用TypeScript可以获得更好的类型提示这对于构建复杂的Agent状态机非常有帮助。mkdir web-agent-extension cd web-agent-extension npm init -y npm install typescript types/chrome web-agent-runtime --save-dev # 假设我们的框架已经发布为 npm 包 web-agent-runtime创建基本的扩展清单文件manifest.json{ manifest_version: 3, name: 智能数据提取助手, version: 1.0, permissions: [activeTab, scripting, storage], action: { default_popup: popup.html }, background: { service_worker: background.js }, content_scripts: [ { matches: [all_urls], js: [content-script.js] } ] }这里我们申请了activeTab权限来操作当前标签页scripting权限用于注入脚本storage用于保存配置或历史记录。3.2 定义核心工具DOM提取器我们首先实现一个最核心的工具——DomExtractorTool。它负责从网页中提取可能包含结构化数据的元素。// tools/DomExtractorTool.ts import { BaseTool, ToolExecutionResult } from web-agent-runtime; export interface DomExtractorParams { selector?: string; // 可选的CSS选择器如未提供则由LLM推断 strategy: table | list | key-value; // 提取策略 } export class DomExtractorTool extends BaseToolDomExtractorParams { name dom_extractor; description 从当前网页中提取结构化数据。支持三种策略 - table: 提取表格table元素数据。 - list: 提取列表ul, ol元素数据。 - key-value: 提取类似键值对的文本内容。 你需要根据页面内容选择最合适的策略。; async execute(params: DomExtractorParams): PromiseToolExecutionResult { // 通过content script与页面DOM交互 // 这里是一个简化示例实际需要更复杂的DOM遍历和清洗逻辑 const data await chrome.tabs.query({ active: true, currentWindow: true }).then(([tab]) { return chrome.tabs.sendMessage(tab.id!, { type: EXTRACT_DOM, payload: params }); }); return { success: true, output: 已成功提取数据共${data.length}条记录。数据预览${JSON.stringify(data.slice(0, 2), null, 2)}, data: data // 原始数据附加在结果中供后续工具使用 }; } }这个工具本身不直接操作DOM而是向content-script.js发送消息由后者在页面上下文中执行具体的提取操作这是浏览器扩展的标准通信模式。3.3 实现Agent规划逻辑接下来我们创建Agent的核心逻辑。它需要理解用户指令如“提取这个页面的产品列表”并规划出工具使用序列。// agents/DataExtractionAgent.ts import { Agent, Planner, LocalLLMEngine } from web-agent-runtime; import { DomExtractorTool } from ../tools/DomExtractorTool; import { DataFormatterTool } from ../tools/DataFormatterTool; // 假设还有一个格式化工具 import { FileSaverTool } from ../tools/FileSaverTool; // 假设还有一个文件保存工具 export class DataExtractionAgent extends Agent { private planner: Planner; private llmEngine: LocalLLMEngine; constructor() { super(); // 初始化一个本地小模型引擎例如使用预训练的轻量模型 this.llmEngine new LocalLLMEngine({ modelPath: /models/qwen1.5-1.8b-int4.gguf, // 模型文件需预先下载 wasmPath: /wasm/llama.cpp.wasm // WASM运行时 }); this.planner new Planner(this.llmEngine); // 注册该Agent可用的工具 this.registerTool(new DomExtractorTool()); this.registerTool(new DataFormatterTool()); this.registerTool(new FileSaverTool()); } async run(userInstruction: string): Promisestring { // 步骤1指令解析与任务规划 const plan await this.planner.createPlan(userInstruction, this.getAvailableTools()); // 步骤2按顺序执行计划 let finalResult ; let sharedState {}; // 用于在工具间传递数据 for (const step of plan.steps) { const tool this.getTool(step.toolName); if (!tool) { throw new Error(工具 ${step.toolName} 未找到); } const result await tool.execute({ ...step.params, _state: sharedState }); if (!result.success) { // 处理错误可以重试或调整计划 return 步骤【${step.description}】执行失败${result.output}; } // 将本次执行的结果数据存入共享状态供后续步骤使用 if (result.data) { sharedState.lastOutputData result.data; } finalResult result.output \n; } return 任务执行完成\n${finalResult}; } }在这个run方法中Planner是关键。它会根据用户指令和当前可用的工具列表生成一个步骤序列。例如对于“提取并保存为CSV”这个指令规划器可能生成{ toolName: dom_extractor, params: { strategy: table }, description: 提取页面上的主要表格数据 }{ toolName: data_formatter, params: { format: csv }, description: 将提取的数据格式化为CSV字符串 }{ toolName: file_saver, params: { fileName: extracted_data.csv }, description: 触发浏览器下载CSV文件 }3.4 构建用户界面与集成最后我们需要一个简单的UI来触发这个Agent。在popup.html中!DOCTYPE html html body h3智能数据提取/h3 textarea idinstruction placeholder例如提取本页所有商品的价格和名称保存为JSON rows3/textarea button idextractBtn开始提取/button div idresult stylemargin-top: 10px; white-space: pre-wrap;/div script srcpopup.js/script /body /html在popup.js中import { DataExtractionAgent } from ./agents/DataExtractionAgent.js; document.getElementById(extractBtn).addEventListener(click, async () { const instruction document.getElementById(instruction).value; const resultDiv document.getElementById(result); resultDiv.textContent 思考中...; try { const agent new DataExtractionAgent(); // 注意在实际中大型模型加载是异步的可能需要一个加载状态 const result await agent.run(instruction); resultDiv.textContent result; } catch (error) { resultDiv.textContent 出错啦${error.message}; } });至此一个具备基础能力的浏览器内AI Agent就搭建完成了。用户点击按钮输入自然语言指令Agent便会自动分析页面、提取数据、格式化并保存。整个过程没有数据离开浏览器响应速度也远比调用云端API要快。4. 深入细节框架设计中的关键决策与踩坑实录构建这样一个框架远不止是把代码拼起来那么简单。每一个设计决策背后都是与浏览器环境特性搏斗的结果。下面分享几个最核心的“坑”和我们的解决方案。4.1 状态管理的困境与破局Agent在执行一个多步骤任务时需要维护状态。例如第一步提取的原始数据需要传递给第二步进行格式化。在服务器端这很简单保存在内存或Redis里就行。但在浏览器中页面可能刷新扩展的Popup可能关闭Service Worker可能休眠。踩坑经历最初我把状态简单地存在Agent类的内存变量里。结果就是当用户最小化再打开Popup或者切换到其他标签页再切回来时Agent的上下文完全丢失任务半途而废。解决方案实现一个分层状态管理系统。会话状态对于单次任务执行过程中的中间状态使用一个内存中的Map来存储键是任务ID。这保证了单次任务链的流畅。持久化状态对于需要跨会话保存的数据如用户偏好、历史任务记录使用chrome.storage.local扩展或localStorage网页进行持久化。框架需要提供统一的抽象接口让工具和Agent可以方便地读写。状态序列化由于工具执行结果可能是复杂的对象如DOM节点列表、数组必须设计一个可序列化的状态格式。我们规定存入共享状态的数据必须是纯JSON可序列化的数字、字符串、布尔值、数组、简单对象。对于DOM元素这类特殊对象工具在返回前必须将其转换为纯数据表示如{ tagName: div, textContent: ..., attributes: {...} }。4.2 工具执行的异步与并发控制浏览器是单线程主线程事件循环模型但Agent的任务可能涉及多个异步操作LLM推理可能很慢、网络请求、文件读取。如果让这些操作阻塞主线程页面就会卡死。踩坑经历早期版本中一个复杂的DOM提取操作比如遍历一个非常大的表格如果同步进行会导致Popup界面完全冻结用户以为插件崩溃了。解决方案全链路异步化 Web Workers。所有工具的execute方法都必须是async的。将最耗时的操作——本地LLM推理——放到Web Worker中执行。这样模型加载和计算完全在后台线程进行不影响UI响应。框架需要封装一个WorkerLLMEngine类通过postMessage与主线程通信。对于可能长时间运行的工具如处理一个非常大的文档框架需要支持进度反馈。我们设计了一个ProgressEvent系统工具可以在执行过程中发射进度事件如{ progress: 0.5, message: 正在解析表格行... }UI层可以监听并更新进度条。4.3 规划器的稳定性如何让LLM“听话”地选择工具让LLM尤其是本地小模型稳定地输出结构化的工具调用计划是整个框架最棘手的问题之一。它经常“放飞自我”输出不符合格式的JSON或者选择根本不存在的工具。解决方案提示词工程 输出约束 后备方案。结构化提示词模板我们为规划器设计了极其详细的提示词明确列出所有可用工具的名称、描述、参数格式并给出多个清晰的示例Few-shot Learning。例如你是一个任务规划助手。根据用户指令和可用工具生成一个JSON格式的行动计划。 可用工具 - dom_extractor: 从网页提取数据。参数: { strategy: table|list|key-value } - data_formatter: 格式化数据。参数: { format: json|csv } ... 示例 用户指令“把页面上的价格表保存为CSV。” 输出{steps: [{toolName: dom_extractor, params: {strategy: table}, description: 提取价格表格}, {toolName: data_formatter, params: {format: csv}, description: 转为CSV格式}, ...]}输出解析与验证规划器收到LLM的回复后不是直接相信而是用JSON.parse尝试解析并验证每个步骤的toolName是否在注册表中参数是否符合工具定义的接口。如果解析失败或验证不通过则进入“修复”流程将错误信息连同原始指令再次发送给LLM要求它纠正。通常最多两轮就能得到有效计划。确定性后备规则对于一些非常常见、模式固定的指令如“刷新页面”、“返回上一页”我们完全绕过LLM规划直接映射到预定义的工具调用序列。这既提高了速度也保证了100%的可靠性。4.4 安全边界与权限管理在浏览器中安全是重中之重。一个恶意的工具脚本可能会试图窃取用户数据或进行不当操作。解决方案沙箱化工具执行 显式权限声明。工具沙箱对于执行任意代码风险较高的工具比如一个允许执行用户提供JavaScript代码的“计算工具”我们使用iframe沙箱或Worker进行隔离限制其访问document、window等敏感对象的能力。权限声明每个工具在注册时必须声明其所需的浏览器权限如“需要访问当前页面DOM”、“需要下载文件权限”。在Agent运行前框架会检查当前上下文是扩展的Popup、Content Script还是普通网页是否具备这些权限。如果不具备则向用户发出清晰的授权请求或者跳过该工具并提供备选方案。输入净化所有从LLM规划器传来的、即将作为参数传递给工具执行的字符串都必须经过严格的净化防止XSS攻击。特别是当参数用于构建CSS选择器或动态HTML时。5. 性能优化与进阶思考让浏览器Agent真正可用一个框架不能只停留在“能跑通”还必须“跑得好”。在资源受限的浏览器环境中性能优化至关重要。5.1 模型加载与推理加速本地小模型的加载和首次推理速度是用户体验的关键瓶颈。模型量化与裁剪优先使用4-bit或8-bit量化的GGUF格式模型这能将模型大小减少60%-75%同时内存占用和推理速度都有巨大提升。对于特定领域如数据提取甚至可以尝试对通用小模型进行LoRA微调使其在该领域表现更精准从而可以用更小的模型尺寸。预加载与缓存在扩展安装后或页面加载的闲时后台Service Worker可以静默预下载和初始化模型文件。模型参数可以缓存在IndexedDB中下次启动时直接加载避免重复网络请求。推理批处理与流式输出对于需要处理多个独立但类似任务的场景如分析一个页面上的多个相似组件可以将它们批处理成一个提示词发送给LLM减少上下文切换开销。对于生成式任务支持流式输出token by token可以更快地给用户反馈。5.2 工具执行的效率提升工具本身的效率也影响整体体验。DOM操作优化浏览器中的DOM操作非常昂贵。DomExtractorTool这类工具必须使用最有效的查询方式如querySelector比getElementsByTagName更精确高效并避免在循环中进行重复的DOM查询或样式计算。尽可能一次性获取所需数据然后进行纯JavaScript处理。并行化与懒加载如果任务计划中的多个步骤没有严格的先后依赖关系框架可以尝试分析依赖图让它们并行执行。同时不是所有工具都需要在Agent初始化时加载可以按需动态加载工具模块。5.3 生态构建与开发者体验一个框架的成功离不开丰富的工具生态和友好的开发者体验。工具开发套件提供一套标准的工具开发模板和脚手架让开发者能轻松地封装自己的业务逻辑为Agent工具。包括类型定义、参数验证模板、错误处理范例等。可视化调试器开发一个运行在浏览器中的Agent调试面板可以实时查看任务规划过程、每一步的工具调用输入输出、共享状态的变化以及LLM的原始思考过程。这对开发和排查问题至关重要。工具市场建立一个社区驱动的工具市场开发者可以发布自己编写的工具如JiraTicketCreatorTool、NotionPageUpdaterTool其他开发者可以一键安装使用快速扩展自己Agent的能力边界。5.4 与云端Agent的协同最后必须明确浏览器内Agent不是万能的它是混合AI架构中的“边缘节点”。它的定位是处理低延迟、高隐私、确定性强的任务。对于需要庞大知识库、复杂逻辑推理或创造性生成的任务仍然需要与云端Agent协同。框架应该设计好“逃生舱口”或“协同接口”。当本地Agent判断任务超出自身能力例如LLM返回的置信度很低或者用户明确要求时可以将任务上下文经过脱敏处理后无缝移交到预设的云端Agent服务并将云端返回的结果接续处理。这种“云边协同”的模式才是未来AI应用最合理的架构。回过头看“在浏览器里跑AI Agent”这个想法从最初的“不信”到一步步实现核心在于对浏览器能力极限的不断试探和对传统架构的大胆解构。它不是为了炫技而是为了解决真实场景下的痛点成本、延迟、隐私和易用性。这个框架目前还是一个早期项目但它打开了一扇门让AI能力可以像JavaScript库一样被前端开发者轻松引入创造出更即时、更私密、更融合于Web体验的智能应用。如果你也对在浏览器边缘探索AI的可能性感兴趣不妨一起参与到这个生态的建设中来它的未来远比我们目前想象的更广阔。 
长河君 · 2026/8/9 21:06:49 · 阅读 1.2k 浏览器端AI Agent框架：实现低延迟、高隐私的Web智能应用
1. 从“不可能”到“可能”为什么要在浏览器里跑 AI Agent你可能觉得我疯了。AI Agent这个听起来就带着“云端算力”、“分布式推理”、“复杂编排”光环的概念怎么就和浏览器——这个我们每天用来刷网页、看视频的“轻量级”客户端扯上关系了传统的AI Agent框架无论是LangChain、AutoGPT还是微软的Semantic Kernel它们的典型部署场景都是服务器端。一个强大的后端服务连接着OpenAI、Anthropic等大模型的API处理着复杂的任务分解、工具调用和状态管理然后通过一个Web界面或者API把结果呈现给用户。这似乎是天经地义的架构。但我在实际工作中遇到了几个让我重新思考这个“天经地义”的痛点。首先是成本与延迟。每一次Agent的思考、每一次工具调用都意味着一次网络往返。对于需要快速交互、低延迟反馈的场景比如一个智能表单填写助手、一个实时代码审查插件这种延迟是难以忍受的。更别提那些按Token计费的API调用复杂的多轮思考链会迅速烧光预算。其次是数据隐私与安全性。很多场景下用户的数据极其敏感比如处理本地文档、分析个人财务表格、或者操作企业内部系统。把这些数据一股脑发送到云端Agent进行处理从合规和信任角度都存在巨大风险。用户和企业的第一反应往往是“我的数据能不能不出我的设备”最后是部署与集成的复杂性。为一个轻量级的小工具或一个内部效率插件去搭建和维护一整套后端Agent服务包括服务器、反向代理、依赖管理、监控告警这无疑是杀鸡用牛刀。开发者的初衷可能只是想给现有网页加一点“智能”却被迫陷入了基础设施的泥潭。正是这些痛点让我开始思考Agent的核心推理逻辑是否有可能完全在用户的浏览器环境中完成答案是肯定的而且时机已经成熟。现代浏览器特别是基于Chromium内核的如Chrome、Edge、新版Edge已经是一个功能极其强大的运行时环境。它支持WebAssembly可以本地运行高性能计算它提供了完善的Web API能够访问文件系统通过File API、麦克风、摄像头、地理位置它通过Service Worker支持后台任务和离线能力更重要的是它原生支持JavaScript/TypeScript而后者正是当前AI应用开发中最活跃的语言生态之一。于是“Web-Agent-Runtime”这个想法诞生了。这不是要取代强大的云端Agent而是开辟一个新的战场将AI Agent的能力“边缘化”、“轻量化”直接注入到最终用户交互的第一线——浏览器中。它不处理需要万亿参数模型完成的创造性写作但它非常适合处理那些基于清晰规则、本地数据、确定性工具调用的自动化任务。比如自动分析你上传的CSV文件并生成图表根据你正在浏览的网页内容自动提取关键信息并填充到笔记软件或者作为一个浏览器插件智能帮你填写重复的网页表单。这个框架的目标是让前端开发者也能以极低的门槛构建出拥有自主决策和行动能力的“智能体”并且保证这一切都在用户可控、可信的本地环境中发生。听起来是不是有点意思了接下来我就带你拆解一下这样一个“跑在浏览器里的AI Agent框架”到底是怎么造出来的。2. 核心架构拆解在沙箱中构建“大脑”与“手脚”把一个AI Agent塞进浏览器绝不是简单地把Python代码用Transcrypt转译成JavaScript那么简单。它需要一套全新的架构设计来适应浏览器环境的独特约束和优势。我设计的这个框架核心思想是**“轻量级内核”与“模块化工具链”**的结合。整个框架的运行时架构可以概括为以下几个层次2.1 推理引擎层LLM的本地化接入这是Agent的“大脑”。在浏览器中我们无法部署一个完整的百亿参数大模型但我们可以巧妙地利用两种资源本地小型语言模型通过WebAssembly或WebGPU可以运行像Gemma 2B、Phi-2、Qwen1.5-1.8B这样经过高度量化如GGUF格式的“小模型”。这些模型参数在1B到7B之间经过量化后模型文件可能在几百MB到几个GB虽然能力无法与GPT-4媲美但对于理解用户指令、进行简单的逻辑推理和规划已经足够。框架需要集成一个通用的模型加载器和推理器例如基于transformers.js或专门优化的WASM推理库如llama.cpp的Web版本。云端大模型的“瘦客户端”对于更复杂的思考我们仍然可以调用云端API。但框架的设计关键在于“智能分流”。简单的、对延迟敏感的任务由本地小模型处理复杂的、需要创造性的任务则由框架代理发起对云端API的调用。框架需要统一这两者的接口让上层的Agent逻辑无需关心思考到底发生在哪里。一个核心的优化是缓存与预热将常见的指令-回复对或思维链模板缓存在IndexedDB中下次遇到类似请求时直接复用极大减少对云端或本地模型的调用。2.2 工具系统层赋予Agent“手脚”这是Agent能与外界交互的关键。浏览器的Web API本身就是一套强大的工具集。我的框架将常用能力封装成了标准的“工具”接口BrowserTool控制浏览器本身如导航到新页面、点击元素、填写输入框、读取DOM内容。这依赖于框架注入的Content Script如果作为扩展或直接使用document.querySelector等API。FileSystemTool通过File API读取用户选择的文件内容文本、CSV、JSON甚至通过File System Access API在用户授权后对本地文件进行读写。NetworkTool发起跨域请求需处理CORS或同源请求获取网络数据。这可以用来调用一些开放的REST API。CalculationTool进行数学计算、日期处理、字符串操作等纯逻辑任务。StorageTool利用localStorage或sessionStorage进行键值对存储让Agent拥有“记忆”。每个工具都实现一个统一的execute(params)方法并提供一个清晰的description用于让LLM理解该工具的功能。例如BrowserTool.click的描述可能是“点击页面上与给定CSS选择器匹配的第一个元素”。2.3 任务规划与执行层Agent的“中枢神经”这一层负责将用户的自然语言指令转化为一系列具体的工具调用。它包含几个核心模块指令解析器接收用户输入调用LLM本地或云端进行意图识别和任务分解。例如用户说“帮我把这个页面上的产品价格保存成表格”解析器需要输出一个任务链[“提取所有价格元素” “整理成结构化数据” “生成CSV文件” “触发下载”]。规划器为任务链中的每一步动态选择最合适的工具并生成调用参数。这通常通过一个特定的“规划”提示词模板让LLM根据当前状态和可用工具列表来决定下一步行动。框架需要维护一个工具注册表动态地向规划器报告当前可用的工具。状态执行器按顺序执行规划好的工具调用。这是最需要稳健性的部分。它需要处理工具执行失败如元素未找到、网络超时、权限拒绝等异常并能根据预设策略进行重试或回退到替代方案。执行器还需要维护一个共享状态供不同工具之间传递数据。比如BrowserTool提取的文本可以存入状态然后被FileSystemTool用来生成文件。2.4 安全沙箱与生命周期管理层这是在浏览器环境中独有的、至关重要的层。浏览器是一个多标签页、事件驱动的环境Agent不能阻塞主线程也不能无限制运行。异步与中断所有耗时的操作LLM推理、网络请求、大文件读取都必须是异步的基于Promise/async-await。框架必须提供优雅的中断机制允许用户随时停止一个长时间运行的Agent任务。权限隔离作为浏览器扩展或运行在特定网页中的脚本其权限受到严格限制。框架必须明确声明所需的权限如activeTab,storage,webRequest等并在工具调用时处理权限不足的异常引导用户授权。资源管理需要监控内存和CPU使用防止本地模型推理耗尽用户设备资源。可以设置推理时间上限、自动清理中间状态等。这个架构的核心是将AI Agent从厚重的“云端服务”解构为一个个可以在浏览器安全沙箱内协同工作的“功能模块”。开发者就像拼乐高一样为自己的场景组合需要的工具和规划逻辑。3. 实战从零构建一个“智能数据提取”Agent理论说再多不如动手写一行代码。让我们用这个框架假设我们把它命名为WebAgent来构建一个真实的场景一个浏览器插件能够智能识别网页上的表格或列表数据并一键导出为结构化的JSON或CSV文件。3.1 环境准备与项目初始化首先我们创建一个新的浏览器扩展项目。使用TypeScript可以获得更好的类型提示这对于构建复杂的Agent状态机非常有帮助。mkdir web-agent-extension cd web-agent-extension npm init -y npm install typescript types/chrome web-agent-runtime --save-dev # 假设我们的框架已经发布为 npm 包 web-agent-runtime创建基本的扩展清单文件manifest.json{ manifest_version: 3, name: 智能数据提取助手, version: 1.0, permissions: [activeTab, scripting, storage], action: { default_popup: popup.html }, background: { service_worker: background.js }, content_scripts: [ { matches: [all_urls], js: [content-script.js] } ] }这里我们申请了activeTab权限来操作当前标签页scripting权限用于注入脚本storage用于保存配置或历史记录。3.2 定义核心工具DOM提取器我们首先实现一个最核心的工具——DomExtractorTool。它负责从网页中提取可能包含结构化数据的元素。// tools/DomExtractorTool.ts import { BaseTool, ToolExecutionResult } from web-agent-runtime; export interface DomExtractorParams { selector?: string; // 可选的CSS选择器如未提供则由LLM推断 strategy: table | list | key-value; // 提取策略 } export class DomExtractorTool extends BaseToolDomExtractorParams { name dom_extractor; description 从当前网页中提取结构化数据。支持三种策略 - table: 提取表格table元素数据。 - list: 提取列表ul, ol元素数据。 - key-value: 提取类似键值对的文本内容。 你需要根据页面内容选择最合适的策略。; async execute(params: DomExtractorParams): PromiseToolExecutionResult { // 通过content script与页面DOM交互 // 这里是一个简化示例实际需要更复杂的DOM遍历和清洗逻辑 const data await chrome.tabs.query({ active: true, currentWindow: true }).then(([tab]) { return chrome.tabs.sendMessage(tab.id!, { type: EXTRACT_DOM, payload: params }); }); return { success: true, output: 已成功提取数据共${data.length}条记录。数据预览${JSON.stringify(data.slice(0, 2), null, 2)}, data: data // 原始数据附加在结果中供后续工具使用 }; } }这个工具本身不直接操作DOM而是向content-script.js发送消息由后者在页面上下文中执行具体的提取操作这是浏览器扩展的标准通信模式。3.3 实现Agent规划逻辑接下来我们创建Agent的核心逻辑。它需要理解用户指令如“提取这个页面的产品列表”并规划出工具使用序列。// agents/DataExtractionAgent.ts import { Agent, Planner, LocalLLMEngine } from web-agent-runtime; import { DomExtractorTool } from ../tools/DomExtractorTool; import { DataFormatterTool } from ../tools/DataFormatterTool; // 假设还有一个格式化工具 import { FileSaverTool } from ../tools/FileSaverTool; // 假设还有一个文件保存工具 export class DataExtractionAgent extends Agent { private planner: Planner; private llmEngine: LocalLLMEngine; constructor() { super(); // 初始化一个本地小模型引擎例如使用预训练的轻量模型 this.llmEngine new LocalLLMEngine({ modelPath: /models/qwen1.5-1.8b-int4.gguf, // 模型文件需预先下载 wasmPath: /wasm/llama.cpp.wasm // WASM运行时 }); this.planner new Planner(this.llmEngine); // 注册该Agent可用的工具 this.registerTool(new DomExtractorTool()); this.registerTool(new DataFormatterTool()); this.registerTool(new FileSaverTool()); } async run(userInstruction: string): Promisestring { // 步骤1指令解析与任务规划 const plan await this.planner.createPlan(userInstruction, this.getAvailableTools()); // 步骤2按顺序执行计划 let finalResult ; let sharedState {}; // 用于在工具间传递数据 for (const step of plan.steps) { const tool this.getTool(step.toolName); if (!tool) { throw new Error(工具 ${step.toolName} 未找到); } const result await tool.execute({ ...step.params, _state: sharedState }); if (!result.success) { // 处理错误可以重试或调整计划 return 步骤【${step.description}】执行失败${result.output}; } // 将本次执行的结果数据存入共享状态供后续步骤使用 if (result.data) { sharedState.lastOutputData result.data; } finalResult result.output \n; } return 任务执行完成\n${finalResult}; } }在这个run方法中Planner是关键。它会根据用户指令和当前可用的工具列表生成一个步骤序列。例如对于“提取并保存为CSV”这个指令规划器可能生成{ toolName: dom_extractor, params: { strategy: table }, description: 提取页面上的主要表格数据 }{ toolName: data_formatter, params: { format: csv }, description: 将提取的数据格式化为CSV字符串 }{ toolName: file_saver, params: { fileName: extracted_data.csv }, description: 触发浏览器下载CSV文件 }3.4 构建用户界面与集成最后我们需要一个简单的UI来触发这个Agent。在popup.html中!DOCTYPE html html body h3智能数据提取/h3 textarea idinstruction placeholder例如提取本页所有商品的价格和名称保存为JSON rows3/textarea button idextractBtn开始提取/button div idresult stylemargin-top: 10px; white-space: pre-wrap;/div script srcpopup.js/script /body /html在popup.js中import { DataExtractionAgent } from ./agents/DataExtractionAgent.js; document.getElementById(extractBtn).addEventListener(click, async () { const instruction document.getElementById(instruction).value; const resultDiv document.getElementById(result); resultDiv.textContent 思考中...; try { const agent new DataExtractionAgent(); // 注意在实际中大型模型加载是异步的可能需要一个加载状态 const result await agent.run(instruction); resultDiv.textContent result; } catch (error) { resultDiv.textContent 出错啦${error.message}; } });至此一个具备基础能力的浏览器内AI Agent就搭建完成了。用户点击按钮输入自然语言指令Agent便会自动分析页面、提取数据、格式化并保存。整个过程没有数据离开浏览器响应速度也远比调用云端API要快。4. 深入细节框架设计中的关键决策与踩坑实录构建这样一个框架远不止是把代码拼起来那么简单。每一个设计决策背后都是与浏览器环境特性搏斗的结果。下面分享几个最核心的“坑”和我们的解决方案。4.1 状态管理的困境与破局Agent在执行一个多步骤任务时需要维护状态。例如第一步提取的原始数据需要传递给第二步进行格式化。在服务器端这很简单保存在内存或Redis里就行。但在浏览器中页面可能刷新扩展的Popup可能关闭Service Worker可能休眠。踩坑经历最初我把状态简单地存在Agent类的内存变量里。结果就是当用户最小化再打开Popup或者切换到其他标签页再切回来时Agent的上下文完全丢失任务半途而废。解决方案实现一个分层状态管理系统。会话状态对于单次任务执行过程中的中间状态使用一个内存中的Map来存储键是任务ID。这保证了单次任务链的流畅。持久化状态对于需要跨会话保存的数据如用户偏好、历史任务记录使用chrome.storage.local扩展或localStorage网页进行持久化。框架需要提供统一的抽象接口让工具和Agent可以方便地读写。状态序列化由于工具执行结果可能是复杂的对象如DOM节点列表、数组必须设计一个可序列化的状态格式。我们规定存入共享状态的数据必须是纯JSON可序列化的数字、字符串、布尔值、数组、简单对象。对于DOM元素这类特殊对象工具在返回前必须将其转换为纯数据表示如{ tagName: div, textContent: ..., attributes: {...} }。4.2 工具执行的异步与并发控制浏览器是单线程主线程事件循环模型但Agent的任务可能涉及多个异步操作LLM推理可能很慢、网络请求、文件读取。如果让这些操作阻塞主线程页面就会卡死。踩坑经历早期版本中一个复杂的DOM提取操作比如遍历一个非常大的表格如果同步进行会导致Popup界面完全冻结用户以为插件崩溃了。解决方案全链路异步化 Web Workers。所有工具的execute方法都必须是async的。将最耗时的操作——本地LLM推理——放到Web Worker中执行。这样模型加载和计算完全在后台线程进行不影响UI响应。框架需要封装一个WorkerLLMEngine类通过postMessage与主线程通信。对于可能长时间运行的工具如处理一个非常大的文档框架需要支持进度反馈。我们设计了一个ProgressEvent系统工具可以在执行过程中发射进度事件如{ progress: 0.5, message: 正在解析表格行... }UI层可以监听并更新进度条。4.3 规划器的稳定性如何让LLM“听话”地选择工具让LLM尤其是本地小模型稳定地输出结构化的工具调用计划是整个框架最棘手的问题之一。它经常“放飞自我”输出不符合格式的JSON或者选择根本不存在的工具。解决方案提示词工程 输出约束 后备方案。结构化提示词模板我们为规划器设计了极其详细的提示词明确列出所有可用工具的名称、描述、参数格式并给出多个清晰的示例Few-shot Learning。例如你是一个任务规划助手。根据用户指令和可用工具生成一个JSON格式的行动计划。 可用工具 - dom_extractor: 从网页提取数据。参数: { strategy: table|list|key-value } - data_formatter: 格式化数据。参数: { format: json|csv } ... 示例 用户指令“把页面上的价格表保存为CSV。” 输出{steps: [{toolName: dom_extractor, params: {strategy: table}, description: 提取价格表格}, {toolName: data_formatter, params: {format: csv}, description: 转为CSV格式}, ...]}输出解析与验证规划器收到LLM的回复后不是直接相信而是用JSON.parse尝试解析并验证每个步骤的toolName是否在注册表中参数是否符合工具定义的接口。如果解析失败或验证不通过则进入“修复”流程将错误信息连同原始指令再次发送给LLM要求它纠正。通常最多两轮就能得到有效计划。确定性后备规则对于一些非常常见、模式固定的指令如“刷新页面”、“返回上一页”我们完全绕过LLM规划直接映射到预定义的工具调用序列。这既提高了速度也保证了100%的可靠性。4.4 安全边界与权限管理在浏览器中安全是重中之重。一个恶意的工具脚本可能会试图窃取用户数据或进行不当操作。解决方案沙箱化工具执行 显式权限声明。工具沙箱对于执行任意代码风险较高的工具比如一个允许执行用户提供JavaScript代码的“计算工具”我们使用iframe沙箱或Worker进行隔离限制其访问document、window等敏感对象的能力。权限声明每个工具在注册时必须声明其所需的浏览器权限如“需要访问当前页面DOM”、“需要下载文件权限”。在Agent运行前框架会检查当前上下文是扩展的Popup、Content Script还是普通网页是否具备这些权限。如果不具备则向用户发出清晰的授权请求或者跳过该工具并提供备选方案。输入净化所有从LLM规划器传来的、即将作为参数传递给工具执行的字符串都必须经过严格的净化防止XSS攻击。特别是当参数用于构建CSS选择器或动态HTML时。5. 性能优化与进阶思考让浏览器Agent真正可用一个框架不能只停留在“能跑通”还必须“跑得好”。在资源受限的浏览器环境中性能优化至关重要。5.1 模型加载与推理加速本地小模型的加载和首次推理速度是用户体验的关键瓶颈。模型量化与裁剪优先使用4-bit或8-bit量化的GGUF格式模型这能将模型大小减少60%-75%同时内存占用和推理速度都有巨大提升。对于特定领域如数据提取甚至可以尝试对通用小模型进行LoRA微调使其在该领域表现更精准从而可以用更小的模型尺寸。预加载与缓存在扩展安装后或页面加载的闲时后台Service Worker可以静默预下载和初始化模型文件。模型参数可以缓存在IndexedDB中下次启动时直接加载避免重复网络请求。推理批处理与流式输出对于需要处理多个独立但类似任务的场景如分析一个页面上的多个相似组件可以将它们批处理成一个提示词发送给LLM减少上下文切换开销。对于生成式任务支持流式输出token by token可以更快地给用户反馈。5.2 工具执行的效率提升工具本身的效率也影响整体体验。DOM操作优化浏览器中的DOM操作非常昂贵。DomExtractorTool这类工具必须使用最有效的查询方式如querySelector比getElementsByTagName更精确高效并避免在循环中进行重复的DOM查询或样式计算。尽可能一次性获取所需数据然后进行纯JavaScript处理。并行化与懒加载如果任务计划中的多个步骤没有严格的先后依赖关系框架可以尝试分析依赖图让它们并行执行。同时不是所有工具都需要在Agent初始化时加载可以按需动态加载工具模块。5.3 生态构建与开发者体验一个框架的成功离不开丰富的工具生态和友好的开发者体验。工具开发套件提供一套标准的工具开发模板和脚手架让开发者能轻松地封装自己的业务逻辑为Agent工具。包括类型定义、参数验证模板、错误处理范例等。可视化调试器开发一个运行在浏览器中的Agent调试面板可以实时查看任务规划过程、每一步的工具调用输入输出、共享状态的变化以及LLM的原始思考过程。这对开发和排查问题至关重要。工具市场建立一个社区驱动的工具市场开发者可以发布自己编写的工具如JiraTicketCreatorTool、NotionPageUpdaterTool其他开发者可以一键安装使用快速扩展自己Agent的能力边界。5.4 与云端Agent的协同最后必须明确浏览器内Agent不是万能的它是混合AI架构中的“边缘节点”。它的定位是处理低延迟、高隐私、确定性强的任务。对于需要庞大知识库、复杂逻辑推理或创造性生成的任务仍然需要与云端Agent协同。框架应该设计好“逃生舱口”或“协同接口”。当本地Agent判断任务超出自身能力例如LLM返回的置信度很低或者用户明确要求时可以将任务上下文经过脱敏处理后无缝移交到预设的云端Agent服务并将云端返回的结果接续处理。这种“云边协同”的模式才是未来AI应用最合理的架构。回过头看“在浏览器里跑AI Agent”这个想法从最初的“不信”到一步步实现核心在于对浏览器能力极限的不断试探和对传统架构的大胆解构。它不是为了炫技而是为了解决真实场景下的痛点成本、延迟、隐私和易用性。这个框架目前还是一个早期项目但它打开了一扇门让AI能力可以像JavaScript库一样被前端开发者轻松引入创造出更即时、更私密、更融合于Web体验的智能应用。如果你也对在浏览器边缘探索AI的可能性感兴趣不妨一起参与到这个生态的建设中来它的未来远比我们目前想象的更广阔。