浏览器中跑 AI Agent：WASM 运行时方案来了

阻碍开源 Agent 得到更广泛采用和实验的一大障碍，是它们依赖额外的工具与框架，必须先安装这些依赖，才能运行 Agent。在本文中，我们将介绍 Wasm Agents 蓝图，展示如何把 Agent 编写成 HTML 文件：只需在浏览器中打开即可运行，不需要任何额外依赖。这仍然是一个实验性项目，但我们决定尽早分享，让大家既能测试它的能力，也能基于它构建新的应用。

在开发 agent-factory 工具时，我们一直在思考：怎样才能把 Agent 打包起来，使其可以轻松分享，并在不同的系统上运行。过去，无论是在尝试通过代码示例传达我们的想法时，还是在介绍用于算法时间线的新工具时，我们都曾使用 marimo 解决过类似的问题。在这两种情况下，最大的优势都是人们可以直接在自己的设备上运行代码——更准确地说，是在自己的浏览器中运行。这得益于 marimo 可以将 notebook 导出为由 WebAssembly 和 Pyodide 驱动的独立 HTML 文件。

WebAssembly（Wasm）是一种二进制指令格式，可以让使用 C、C++、Rust 和 Python 等语言编写的代码，以接近原生的速度在 Web 浏览器中运行。Pyodide 是一个完全运行在 WebAssembly 中、面向浏览器的 Python 发行版，让你能够直接在 Web 应用中执行 Python 代码以及它的许多库。由于我们的大多数 Agent 代码都是用 Python 编写的，自然而然地，我们开始考虑采用类似的解决方案。最终成果是一组简单的单文件 Agent：它们运行在浏览器标签页中，运行环境天然具备沙箱隔离能力，而且不需要手动安装额外的库或开发框架。

我们的所有 demo 都是独立的 HTML 文件，同时包含 UI 和 Agent 的运行代码。如果查看它们的源代码，你会看到三处对 pyodide.runPythonAsync 命令的调用。它们分别负责：安装所需的 Python 依赖（使用 Pyodide 的 micropipcustomisation 库）；禁用 traces（目前只有运行 openai-agents 框架时才需要这样做——更多信息可以参阅下文的定制部分）；以及运行真正的 Agent 代码。

Agent 代码无非是一个 Python 脚本，它依赖 openai-agents-python 库来运行 AI Agent，背后使用的是通过 OpenAI-compatible API 提供服务的 LLM。这意味着，它不仅可以开箱即用地配合 OpenAI 运行（默认模型为 gpt-4o），你也可以指定其他自行托管的模型，只要该模型兼容这一 API。例如，这包括通过 HuggingFace TGI、vLLM 提供服务的模型，甚至可以是在你自己的计算机上本地运行的 Ollama。

如果你想试用我们的 Agent，请按照 GitHub 仓库中的设置说明操作。简而言之：如果你已经有一个可用的 OpenAI API key，只需将其粘贴到提供的 config.js 文件中。如果你想尝试本地模型，则需要确保模型已经启动，并且你知道访问它的 URL。例如，如果想通过 Ollama 运行 qwen3:8b，首先需要下载应用，然后下载模型（使用 Ollama pull qwen3:8b）。完成之后，在浏览器中打开任意一个 HTML 文件，并按照其中提供的说明操作：几秒钟后，你的 Agent 就应该能够正常运行了。

我们的 demo 展示了 Wasm Agent 能做的一部分事情，但我认为，我们对它潜力的探索才刚刚触及表面！所以，请把这些仅仅当作一些入门示例。你可以基于它们进行实验，测试其能力，并学习如何用它们构建新的应用。在 /demos 目录中，你会找到以下 HTML 文件：

hello_agent.html：这是一个简单的对话式 Agent，支持自定义 instructions，适合用来理解基于 WASM 的 Agent 的基本原理。

handoff_demo.html：这是一个 multi-agent 系统，会根据 prompt 的特征，将请求路由给专门的 Agent。

tool_calling.html：这是一个更加高级的 Agent，内置了一些用于处理（或多或少算是）实际任务的工具。count_character_occurrences 工具解决了著名的“How many Rs in strawberry?”问题。visit_webpage 工具会下载 Web 内容并将其转换成 markdown，Agent 可以利用它直接从 Web 上查找与问题有关的最新信息。

ollama_local.html：这是一个依赖 Ollama 所提供的本地模型运行的 Agent，适合离线任务，也适合你不希望自己的信息泄露给外部 AI 服务的场景。

注意：如果你希望运行从其他服务器获取信息并加载到 HTML 页面中的工具（例如 visit_webpage 工具或 Ollama 服务器本身），就需要确保这些服务器已经启用 CORS。更多信息请参阅 GitHub 仓库中的故障排查部分。

我们之所以这么早就分享这些 demo，是因为我们对它们非常兴奋。不过，我们也清楚，目前分享的示例在应用范围上仍然比较有限。尤其是以下几个方面：

我们受限于 openai-agents 框架：OpenAI 的框架只是众多框架中的一个（这正是我们构建 any-agent 的原因）。之所以选择它，是因为它的所有依赖都能配合 Pyodide 正常工作。即便如此，我们仍然不得不作出妥协，禁用 Agent traces——它原本非常有助于理解 Agent 的工作方式——因为 traces 会导致解释器崩溃。我们也尝试过其他框架，但每个框架都有自己的问题。例如，smolagents 的 traces 实现在浏览器中运行良好，但它通过 LiteLLM 提供对非 HuggingFace 模型的支持，而 Pyodide 并不支持 LiteLLM。

到处都是 CORS：在代码中混合使用从不同 URL 获取的信息，默认是不安全的，现代浏览器通常也会阻止这种行为。因此，只要开始启用那些需要获取 Web 页面，甚至需要访问本地 inference engine 的工具，你就必须禁用 CORS（并且记得在使用结束后重新启用它！）。

依赖 inference engine：我们认为，目前这仍然是一个很强的前提假设，因为如果想使用开源模型，你仍然必须额外完成一套安装流程。不过，我们相信 Firefox Webextension AI API 等项目或许能让这一步变得更简单。

模型很重：并不是每个人都能运行大模型，我们希望充分考虑到这一点。我们提供的本地示例可能无法在你的硬件上运行。遇到这种情况，我们建议你尝试更小的模型或更短的 context length（参见下一部分）。

考虑到上一节的内容，我们相应地修改了这一节的标题 😁，并建议你：

学习它的工作原理：所有代码都在那里。除了基于 OpenAI 的示例之外，一切都在你的计算机上运行。因此，请多次运行所有示例，并修改、尝试其中的代码，直到你确信自己已经掌握了基本原理。

尝试不同的 prompt：查看下面的示例，了解如何挑战 LLM，并验证 tool calling 究竟有没有帮助。

理解非确定性：多次询问时，LLM 通常不会对同一个问题给出完全相同的答案。所有答案都是正确的吗？很可能不是。

了解不同模型的特性：如果你可以通过 Ollama 运行自行托管的模型，请尝试不同的 LLM，并了解哪个模型最适合你的使用场景。例如，thinking mode 能改善模型的回答吗？（提示：你可以添加 /think 或 /no_think，在 qwen3 上显式启用或禁用它。）又或者，所有模型都擅长 tool calling 吗？（提示：显然不是，但哪一个最好？）

测试模型以及硬件的极限：声称“我们使用了 x 和 y，因此理论上支持任何模型”（相对来说）很容易。然而，真正在你的硬件上运行任意模型，就没那么容易了。我可以在 M3 MacBook 上运行 qwen3:8b，甚至使用（其实没必要的）40K tokens context length；但在配备 8GB RAM 的 Raspberry Pi 5 上，我勉强只能运行 1.7b 模型，而且 context 还要短得多。除非调高 Agent 的 timeout 值，否则它根本无法及时返回响应。至于 0.6b 模型就更别提了：它会产生大量 thinking，最终却返回错误答案。

尝试其他 Agent 框架：我们相信，弄清楚哪个框架效果最好，以及是否值得帮助那些目前还不能在浏览器中运行的库支持 Wasm 版本，绝对是有价值的。

工具、工具、还是工具：能在浏览器中运行的东西显然存在一些限制。我的假设是，最近让 Agent 变得如此热门的能力——也就是通过工具增强 LLM——在这里会受到相当大的限制。我无法想象自己会从一个浏览器标签页里启动新的 MCP server，但我十分确信，只要人们能够动手修改一些简单、自包含的代码，现在就已经有许多事情可以做。不过，我仍然想看看事情会从哪里开始出问题，以及在这些限制之内，我们究竟能做到什么。

就我个人而言，我还不知道 WebAssembly Agent 究竟是一个绝妙的想法，还是一个有趣的小把戏。但它与许多我所在意的理念产生了强烈共鸣——（我可以说“我们”吗？）拥有自己的工具、被允许动手改造它们、在本地运行程序、保护自己的数据，甚至还有久违的 powerbrowsing！因此，我认为，如果不尽快把它们分享出来，实在太可惜了。我们很想知道你是否玩得开心，也很想了解你从中学到了什么。所以，欢迎在 Discord、GitHub 上联系我们，也可以直接联系我。与此同时，祝你玩转自己的 Wasm Agent！