web-agent-runtime

English | 简体中文

web-agent-runtime 是一个面向浏览器宿主环境的 agent runtime，适合在 Web 场景里实现类似 Claude Code 的交互式客户端 agent 行为。

本项目是给谁设计的

如果你需要完成如下任务，那么本项目就是为你设计的：

• 在浏览器环境里实现一个交互式 agent
• 开发一个 agent 类型的浏览器插件
• 为指定生态开发插件（如 office）
• 在公司内部 web 系统中集成智能助手
• 希望 agent 助手可以访问当前页面状态和操作 JS API

从本质上来讲，这个项目实现了一个纯 js 的 agent 运行框架，并提供了一些内置功能（如 session 管理、上下文操作等），让你可以专注于 agent 行为设计和工具集成，而不需要从零搭建整个 agent loop。

核心能力

• 🌐 面向浏览器开发的纯 js agent runtime：提供了 agent loop、事件系统、session 管理等核心功能
• 📦 核心包零运行时依赖
• 🖼️ UI 无关，框架无关：你可以在任何前端框架里使用它，也可以直接用原生 js
• 💾 内置 session 增删改查：基于 IndexedDB 的浏览器端 session 持久化
• 🧭 完备的上下文操作：prompt、undo、redo、followUp、steer、fork、compaction、abort...
• 🧩 完全可定制：模型调用、数据存储、工具定义均通过标准的 interface 实现。

安装

npm install web-agent-runtime

开始使用

你可以使用内置的 openai 兼容的 provider 来构建基础的 agent runtime：

import { createAgentRuntime } from "web-agent-runtime";
import { createLocalStorageTools } from "web-agent-runtime/local-storage";
import { createUnsafeOpenAiProvider } from "web-agent-runtime/unsafe-openai";

const OPENAI_API_KEY = "srk-xxx";
const OPENAI_BASE_URL = "https://api.openai.com/v1";
const OPENAI_MODEL_ID = "gpt-4.1-mini";

const agent = await createAgentRuntime({
  model: { id: OPENAI_MODEL_ID },
  llmProvider: createUnsafeOpenAiProvider({
    apiKey: OPENAI_API_KEY,
    baseUrl: OPENAI_BASE_URL,
  }),
  tools: createLocalStorageTools(),
});

注意，不要在生产环境使用 createUnsafeOpenAiProvider 访问 llm，这会直接在前端暴露你的 api key。由自己的后端服务提供 llm 接口。并在前端实现 LlmProvider 类型的 llmProvider 来实现接入。

完成！现在你已经获得了一个功能完备的 agent，你可以通过它的订阅事件把状态绑定到 UI。并使用 prompt 发起请求：

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

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

unsubscribe();
await agent.destroy();

你还可以使用内置的 session 管理功能来创建、更新、分叉会话：

const session = await agent.sessions.create({
  title: "Quick Start Demo",
});

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

await agent.sessions.update(session.id, {
  title: "Quick Start Demo Updated",
});

const sessions = await agent.sessions.list();
console.log("all sessions:", sessions);

const forked = await agent.sessions.fork({
  sourceSessionId: session.id,
  title: "Quick Start Branch",
});

await agent.sessions.open(forked.session.id);

除此之外，web-agent-runtime 还提供了完备的上下文操作，例如：

• agent.prompt()：发送一轮新的用户输入
• agent.continue()：在已有上下文上继续生成，不追加新的用户消息
• agent.followUp()：在当前轮结束后追加下一条跟进消息
• agent.steer()：在运行中插入 steering 消息，尝试重定向当前过程
• agent.compact()：压缩历史上下文，减少后续请求负担
• agent.abort()：中止当前运行会话

Demo

仓库内提供了一个本地 demo，位于 packages/demo/，用来验证：

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

启动方式见 packages/demo/README.md。

多 Session 并发使用

web-agent-runtime 支持多个 session 同时运行。

• 推荐方式：每个会话窗口（或 tab）使用一个独立 runtime 实例，并在该实例中打开一个 session。
• 不同 sessionId 可以并发运行，互不干扰。
• 同一个 sessionId 建议采用单写者模式（仅一个 runtime 发起写入），避免 revision conflict。

示例：

const runtimeA = await createAgentRuntime(options);
const runtimeB = await createAgentRuntime(options);

await runtimeA.sessions.open("session-a");
await runtimeB.sessions.open("session-b");

await Promise.all([
  runtimeA.prompt("继续处理任务 A"),
  runtimeB.prompt("继续处理任务 B"),
]);

本地开发

如果你是在当前仓库里本地开发：

pnpm install
pnpm build
pnpm --filter web-agent-runtime test
pnpm typecheck

感谢

这个项目在设计时参考了 pi-mono 项目的设计。感谢 pi-mono 团队的开源贡献，提供了宝贵的参考和启发。

License

MIT