说起来你可能不信，我写了个跑在浏览器里的 ai agent 框架

大家好啊我是 HOHO，最近搞了个小玩意出来给大家汇报一下。

前言

这两年大家一聊 agent 开发，默认脑子里浮现出来的基本都是服务端方案：

开发大头都在后端、上任务队列、上数据库、云函数、代理层，再来一套复杂到第二天自己都看不懂的编排系统。然后前端负责做个聊天框，点一下按钮，把请求发上去，把响应 show 出来就结束了。

当然哈，也不是说这种方案不对。但假设说，有些能力不在服务端呢？

比如说目前非常流行的各种 coding cli，本质上就是一个客户端 agent，各种逻辑和编排都是在本地处理的，而服务端只有很薄的一层 llm 封装。

为什么这么搞？因为能力都在客户端上，终端在本地、代码在本地、用户决策需要本地完成。你把这些逻辑放在后端，相当于绕了个大圈去解决问题。

那 web 端呢？

阅读当前页面、告诉用户现在是在看什么，下一步该干什么。
告诉用户他想要的功能在哪个路由
直接调用前端已经有的 api 封装，直接代替 CURD 列表页
利用一些注入特殊能力的 JS API（例如浏览器插件、office 插件）完成特定领域的任务
...

诶？那么有没有一个 agent 框架，能够在浏览器这个客户端就把这些需求闭环掉？

所以这个项目就出来了：

Github: HoPGoldy/web-agent-runtime
Npm：web-agent-runtime - npm

它是干嘛的？

简单说，web-agent-runtime 是一个面向浏览器宿主环境的 agent runtime。

它就是用来实现上面提到的需求的。你可以把它理解成一个 coding agent，只不过跑在浏览器里。这个框架把一套 agent 真正跑起来时最麻烦的那部分东西准备好了，比如：

agent loop
事件流
tool call
session 管理
上下文压缩、分叉、steer、followup
浏览器端持久化

但与此同时，它又该死的灵活和开放：

UI 你自己决定，框架只提供内核级的 api 和一套发布订阅的事件机制。React、Vue、Svelte、原生 js 都行。
模型接入你自己决定，内置只给了一个方便本地验证的 OpenAI 兼容 provider。
工具定义你自己决定，想操作页面、导航路由，调用 API都可以。
数据存储你自己决定，开箱即用的提供一个基于 Indexdb 的存储，但是你可以通过接口把数据保存到任何位置。

怎么上手？

上手其实很直接：

bash 复制代码

npm install web-agent-runtime

然后你可以先用内置的 provider 和本地工具快速把东西跑起来：

ts 复制代码

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-4.1-mini" },
  llmProvider: createUnsafeOpenAiProvider({
    apiKey: "your-api-key",
    baseUrl: "https://api.openai.com/v1",
  }),
  tools: createLocalStorageTools(),
});

这样一个可以自由读写 localstorage 的 agent 就开发好了：

ts 复制代码

const unsubscribe = agent.subscribe((event) => {
  console.log("assistant message:", event);
});

await agent.prompt("往 localStorage 里写入 demo:greeting=hello");

unsubscribe();
await agent.destroy();

当然这里要说清楚，createUnsafeOpenAiProvider 这个只是让你可以快速开发原型的哈，永远不要让 key 出现在前端逻辑里。生产环境你需要自己搞一个 llmProvider 对接到你的后端服务。

更多的什么会话管理、上下文操作这里就不赘述了，各位可以看项目或者直接让 ai 读 ts 声明。

你啥都提供了，我用这个包还需要干什么？

首先第一点，你需要根据后端接口开发一个 llm provider。

然后你需要根据自己的场景，写 system 提示词和开发一套 tool set。然后慢慢调教知道能满足你的业务需求。

就这些。这个包只实现了 agent 运行所需要的核心逻辑，业务层则完全交给你发挥创意。

用了什么技术？

项目整体是 TypeScript，核心包零运行时依赖 ，构建用 tsup，测试用 vitest。

另外仓库里还带了一个 demo，可以直接拿来验证：

浏览器侧工具调用
runtime event 流
session 创建和持久化
模型输出渲染

如果你准备把它接进自己的产品里，先跑一下 demo，基本就能很快判断这套抽象是不是你要的。

最后

最后还要提一下，这个包并不是希望做一个新时代的 langchain 或者其他大包大揽的 ai 框架。它只是给在浏览器（以及各种 webview 或者纯 js 环境）提供一个运行 agent 的底层能力支持。

后端当然重要，但不是所有问题都该用同一套方案去解决。真正做过服务端 agent 的人应该都知道实现后台会话运行和用户确认有多恶心。

如果你正好就在做浏览器插件、内部系统助手，或者任何一种"能力主要长在前端"的 agent 产品，那这个项目可能能帮你少走不少弯路。

Github: HoPGoldy/web-agent-runtime
Npm：web-agent-runtime - npm

欢迎尝试，有问题随时 issue 或者评论区交流。