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

HOHO
0 阅读4分钟

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

前言

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

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

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

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

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

那 web 端呢？

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

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

所以这个项目就出来了：

它是干嘛的？

简单说，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 的存储，但是你可以通过接口把数据保存到任何位置。

怎么上手？

上手其实很直接：

npm install web-agent-runtime

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

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 就开发好了：

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 产品，那这个项目可能能帮你少走不少弯路。

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

avatar
文章
阅读
粉丝