大家好啊，我是HOHO。Zui近这段时间，我一直在琢磨一件事情，那就是我们到底该如何geng优雅地在浏览器端去实现那些复杂的AI交互逻辑。说实话，现在的开发环境虽然卷得厉害，但hen多工具其实并没有完全解决开发者的痛点。经过一段时间的闭关修炼，我总算是搞出了一个小玩意儿，今天特地拿出来给大家汇报一下顺便聊聊这背后的思考。

当我们在谈论Agent开发时我们在谈论什么？

这就hen有意思了大家不妨回想一下这两年只要一提到Agent开发，绝大多数人脑子里蹦出来的第一反应是什么？我想，大概dou是那一套厚重的服务端方案吧。这几乎成了一种思维定势。

你kan啊，现在的常规操作是什么样的：开发的重心几乎全部压在了后端。你需要上任务队列来处理异步任务，得搞数据库来存储会话状态，还得配置云函数，甚至为了那一层逻辑，你得专门搭个代理层。Zui让人头大的是往往还得整一套复杂到第二天自己doukan不懂的编排系统。而前端呢？前端在这个架构里扮演的角色简直太卑微了无非就是画个聊天框，用户点一下发送按钮，前端把请求发上去，然后把后端返回的响应展示出来就完事了。这真的合理吗？

当然我并不是说后端不重要，后端当然重要，它是基石。但是并不是所有的问题dou适合用同一套臃肿的方案去解决。真正在一线Zuo过服务端Agent的朋友应该深有体会，实现后台的会话运行机制，特别是涉及到需要用户频繁确认的环节，那过程简直Ke以用“恶心”来形容。你为了一个简单的逻辑，绕了这么大一个圈子，真的值得吗？

为什么我们需要浏览器端的Agent？

这就引出了我的核心观点：为什么这么搞？因为hen多时候，Neng力其实dou在客户端上。

试想一下Ru果你的终端就在本地，代码逻辑也在本地，甚至用户的决策dou需要在本地瞬间完成，这时候你非要把这些逻辑扔到后端去处理，那不就相当于为了买瓶酱油非要绕地球一圈吗？这完全是在绕弯路解决问题。

举个hen现实的例子，目前市面上非常流行的各种Coding CLI工具，本质上这就是一个典型的客户端Agent。你kan它的各种逻辑判断、任务编排，全dou是在本地处理的，服务端对于它来说仅仅是一层hen薄的LLM封装而Yi。这种架构多清爽，多直接。

那么问题来了那Web端呢？

诶？有没有可Neng，我们也需要一个Agent框架，Neng够服务端的架构反而成了累赘。

Web-Agent-Runtime：为浏览器而生的运行时

所以这个项目就顺理成章地诞生了。简单来说web-agent-runtime就是一个专门面向浏览器宿主环境的Agent运行时。它就是用来实现上面提到的那些需求的。

你Ke以把它理解成一个跑在浏览器里的Coding Agent。这个框架的初衷非常纯粹，就是把一套Agent真正跑起来时Zui麻烦、Zui琐碎的那部分东西给你准备好。至于业务层怎么玩，那就完全交给你发挥创意了。

Zui后还要特别强调一下这个包并不是希望Zuo一个新时代的LangChain，也不是想搞那种大包大揽、什么dou要管一把的AI框架。它只是给在浏览器提供一个运行Agent的底层Neng力支持。它足够小，足够专注。

技术栈与架构设计

项目整体是使用TypeScript编写的，这对于类型安全至关重要。而且，核心包是零运行时依赖的，这意味着你把它引进来的时候，不用担心包体积爆炸，也不会有莫名其妙的版本冲突。在构建方面我使用了tsup，测试则选用了vitest，整个工具链dou是现代且高效的。

上手其实hen直接：从零开始构建

别kan我说了这么多理论，这东西上手其实一点dou不难。咱们直接来点实际的。

你需要把包装进你的项目里：

npm install web-agent-runtime

装好之后你Ke以先用内置的Provider和本地工具快速把东西跑起来kankan效果。仓库里其实还带了一个Demo，大家Ke以直接拿来Zuo验证，非常方便。

geng多的什么会话管理、上下文操作这些细节，我这里就不赘述了毕竟文档里dou有，各位Ke以直接去kan项目，或者干脆让AI帮你读一下TypeScript的声明文件，那是Zui快的。

构建你的第一个Agent

咱们来kan一段代码，这基本上就是启动一个Agent的全部流程了：

import { createAgentRuntime } from "web-agent-runtime";
import { createLocalStorageTools } from "web-agent-runtime/local-storage";
import { createUnsafeOpenAiProvider } from "web-agent-runtime/unsafe-openai";
const agent = await createAgentRuntime({
  model: { id: "gpt-4o-mini" },
  llmProvider: createUnsafeOpenAiProvider({
    apiKey: "your-api-key",
    baseUrl: "https://api.openai.com/v1",
  }),
  tools: createLocalStorageTools,
});

kan，就这么几行，一个Ke以自由读写LocalStorage的Agent就开发好了。是不是比想象中简单多了？

安全警告：关于Unsafe Provider

不过这里我得把丑话说在前头，大家一定要注意安全。代码里用到的createUnsafeOpenAiProvider，这个名字里的“Unsafe”可不是开玩笑的。这个Provider仅仅是为了让你在开发原型的时候Neng够快速上手，永远不要让你的API Key出现在前端的生产环境逻辑里，这是大忌！

Ru果你真的要把它接进自己的产品里或者部署到生产环境，那你需要根据你的实际场景，自己写一个LLM Provider，把它对接到你的后端服务中去。这样你的Key才是安全的。这是第一步，也是Zui重要的一步。

交互与事件流：让Agent活起来

Agent跑起来之后怎么跟它交互呢？这就得说说事件订阅了。你Ke以监听Agent发出的各种事件，比如：

const unsubscribe = agent.subscribe => {
  console.log;
});
await agent.prompt;
unsubscribe;
await agent.destroy;

通过这种方式，你Ke以非常细粒度地控制Agent的行为，获取它的每一步输出，甚至在它执行某些危险操作前进行拦截。这种灵活性，正是这个框架的魅力所在。

定制化：打造属于你的智Neng体

虽然框架提供了基础Neng力，但真正的灵魂还是在于你的定制。你需要根据自己的业务场景，去精心编写System提示词，这是决定Agent智商的关键。同时你还需要开发一套属于自己的Tool Set。

这就像养孩子一样，框架给了你一个健康的身体，但它的性格和技Neng需要你慢慢去调教，直到它Neng完美满足你的业务需求。这中间可Neng需要反复的调试，但一旦调通了那种成就感是无与伦比的。

它是否适合你？

当然哈，我也不是说传统的服务端方案就不对，那肯定是有它的道理的。但假设说你的核心Neng力不在服务端，或者你就是想在前端把事情搞定，那这个框架可Neng就是为你量身定Zuo的。

它既保持了极简的核心，又该死的灵活和开放。Ru果你准备把它接进自己的产品里我的建议是先跑一下Demo。基本跑一遍，你就Nenghen快判断这套抽象是不是你想要的那个味儿。

就这些了。这个包只实现了Agent运行所需要的核心逻辑，剩下的舞台留给你们。欢迎各位尝试，Ru果在折腾的过程中遇到了什么问题，随时提Issue或者去评论区交流，咱们一起把这个东西打磨得geng好。

---