Bringing more agent harnesses and frameworks to Cloudflare, starting with Flue

将更多代理框架和工具引入 Cloudflare，从 Flue 开始

2026-06-17

• Thomas Gauvin

8 分钟阅读

2026 年是代理框架进入生产环境的一年。控制模型访问外部世界的软件（如 Codex、Claude Code、OpenCode、Pi 和 Project Think 等框架）已经成熟到足以让团队将代理作为真正的、承载负载的基础设施部署，而不仅仅是原型。

但构建能够经受生产环境考验的代理并不容易。

我们在构建第一个内部代理框架 Project Think 时亲身体验到了这一点。在与客户合作运行生产环境中的代理时，我们发现了一组常见的分布式系统问题，每个代理在云端运行时都会面临这些问题。当代理被中断时，如何自动且优雅地从中断处恢复，而不会丢失上下文或浪费 token？如何安全地运行不受信任的代码？如何使用代理所训练的工具？

单靠一个框架无法解决这些问题。这些问题与状态、存储和计算相关，这意味着它们依赖于代理运行的平台。因此，我们正在将强化 Project Think 以适应生产环境的经验带入 Cloudflare Agents SDK，作为基础层。现在，任何基于 Agents SDK 构建的框架都可以使用持久执行、动态代码执行、持久文件系统和动态工作流。

与此同时，框架之上又出现了一层新的结构。像 Flue 这样的框架通过项目结构、惯例、集成和开发者体验，将代理的构建变得高效。

为了解决这些扩展挑战，一个用于构建生产级 AI 的三层架构正在逐渐形成。以下是各部分如何组合在一起，从面向用户的开发者体验到底层平台原语：

• 框架（Flue）——用于构建代理的项目结构、惯例、集成、CLI 和开发者体验。

• 框架（Pi、Project Think）——负责调用工具、读取结果、管理上下文并持续运行直到任务完成的代理循环。

• 运行时/平台（Cloudflare Agents SDK）——所有上层依赖的计算、状态和存储原语。

Agents SDK 是最底层：它为任何框架和任何代理框架提供了诸如持久执行等原语。Flue 是我们新推出的开源框架，由 Astro 团队打造，是第一个基于它构建的框架。以下是它的实现方式。

Flue

本周，Flue 发布了 1.0 Beta 版本，基于 Pi 框架，与 OpenClaw 使用的相同框架。作为代理框架，它与其他框架的不同之处在于其方法：你不是脚本化代理的行为，而是描述代理所知道的内容。定义代理所需的上下文——其模型、技能、沙箱和指令——然后它会自主地解决你给予它的任何任务。你不需要编写任何编排循环。

这种声明式模型使得编写代理变得简单：以下是一个三重代理，它拦截错误报告，在沙箱中重现错误，并在不到 25 行代码中诊断问题。

Flue 的开发者体验

Flue 的强大之处在于代理并不孤立存在。它们是构建在你用户已经工作的环境中，并与你偏好的工具集成：

• 任意位置代理：通过预配置的通道，将代理部署到 Slack、GitHub、Linear 或 Discord 中，这些通道会自动处理事件验证和分发模板。

• 无头但具备 UI 能力：代理不应处于黑盒中。Flue 代理可以完全无头运行以处理后台任务，但 @flue/react 提供了原生的前端钩子，可以将代理的状态、工具执行和实时消息直接流式传输到前端应用中，无需你从零开始构建自定义的实时通信。

• 与生态系统兼容：Flue 使添加和升级集成变得简单，例如使用 flue add channel slack 命令，生成一个 Markdown 蓝图，你的编码代理可以读取、修改并干净地集成到代码库中。

为生产环境而设计，而不仅仅是原型

将代理从本地终端移动到生产环境会引入传统的分布式系统故障。主机崩溃、LLM 提供商的 API 超时以及意外重启可能会导致运行中的代理的短期记忆被清除。

Flue 通过 Durable Streams 解决了这个问题。执行历史中的每个事件都会被添加到一个只追加的日志中。通过将每个提示、工具响应和模型选择处理为不可更改的账本，代理的状态永远不会是易失的。如果某个进程崩溃，另一个进程只需从日志中继续执行，从它上次停止的精确步骤继续。

任意地方部署，包括 Cloudflare

Flue 是一个多云框架。在 Node.js 上，每个代理作为一个长期运行的进程运行。你可以将其部署到任何虚拟机或容器中，运行在 GitHub Actions 中，或者嵌入到现有服务器中。但当你以 Cloudflare 为目标时，每个代理就变成了一个 Durable Object。

通过将每个 Flue 代理运行在自己的 Durable Object 中，Cloudflare 可以自动扩展到你需要的任意数量的代理，每个代理都有自己的独立存储和计算资源。你不需要配置服务器、管理粘性会话，也不必担心邻居干扰。当 Flue 代理部署到 Cloudflare 时，它们通过 Agents SDK 的 runFiber()、stash() 和 onFiberRecovered() 方法实现持久执行。Flue 还使用了 @cloudflare/codemode 和 @cloudflare/shell 对持久工作区进行沙盒代码执行。

代理平台需要为 harness 提供什么

Flue 的 Cloudflare 目标之所以如此有效，是因为它与我们构建到 Agents SDK 中的核心原语清晰地映射。你甚至可以深入 Flue 的源代码，了解底层的 harness Pi 是如何适配到 Cloudflare Agents SDK 上运行的。

以下是 Flue 如何利用 Agents SDK 的内部机制，以及实现现代代理 harness 在大规模运行时所需的条件。

每个代理 harness 都需要持久执行

代理的一次执行不是一个单一的请求。模型会流式传输令牌，调用工具，等待结果，可能请求人类批准，或将工作委托给子代理。这个过程可能需要几秒或几分钟，任何时刻都可能被中断或崩溃。当发生这种情况时，所有在内存中的代理状态都会丢失：流式连接、待处理的工具调用、代理在执行过程中的位置。当然，对话历史会被持久化到磁盘上，但用户会看到一个永远无法完成的旋转图标。这是一种糟糕的用户体验。

Fibers 通过在 Agent 的底层 Durable Object 中提供原生的检查点机制来解决这个问题。runFiber() 在 Agent 转换开始之前，将进度记录到 Durable Object 的 SQLite 存储中，并随着转换的推进使用 stash() 进行检查点记录。当 Agent 实例在中断后重新启动时，onFiberRecovered() 会传递最后一个检查点，这样你的 Agent 就知道转换被中断了，中断的位置在哪里，并可以决定如何继续。

import { Agent } from "agents";
import type { FiberRecoveryContext } from "agents";

class MyAgent extends Agent {
  async doWork() {
    await this.runFiber("my-task", async (ctx) => {
      const step1 = await expensiveOperation();
      ctx.stash({ step1 });

      const step2 = await anotherExpensiveOperation(step1);
      this.setState({ ...this.state, result: step2 });
    });
  }

  async onFiberRecovered(ctx: FiberRecoveryContext) {
    if (ctx.name !== "my-task") return;

    const { step1 } = (ctx.snapshot ?? {}) as { step1?: unknown };
    if (step1) {
      const step2 = await anotherExpensiveOperation(step1);
      this.setState({ ...this.state, result: step2 });
    }
  }
}

Flue 在其 Cloudflare 目标上使用 runFiber() 正是为了这个目的。通过 onFiberRecovered() 钩子，你的框架可以决定如何恢复转换的执行，无论是尝试像 Project Think 这样的完整重建模型来修复转换状态，还是重放转换的某些部分。

执行代码比通过工具加载 Agent 更好

Agent 框架通过工具为模型提供对外部世界的访问。但工具的界面增长迅速，随着工具列表变长，上下文窗口被工具定义填满，模型选择正确工具的能力会变差。更好的模式是：为模型提供一个执行代码的工具。模型编写一个 TypeScript 函数，调用其所需的 API，框架运行该函数。我们在引入 Code Mode 时已经讨论过这一点。

问题是这段代码在何处运行。为了安全地运行 LLM 生成的代码，你需要一个沙箱。但典型的沙箱运行速度慢、成本高，每次调用工具时效率低下。这就是为什么 Agents SDK 提供了 @cloudflare/codemode，它封装了 Dynamic Workers，以便在自己的 Worker 隔离环境中运行 LLM 生成的代码，仅使用你提供的绑定。

Code Mode 为每个代码片段创建一个新的 Dynamic Worker，运行它，然后丢弃它。隔离环境启动时间少于 10 毫秒，每次加载成本为 $0.002，这使得执行成本远低于每次 Agent 需要执行一小段代码时启动容器的成本。Flue 在其 Cloudflare 目标上使用 @cloudflare/codemode 来为其代码工具提供支持。Agent 在工作区中编写 JavaScript 并通过 Code Mode 运行它。

对于大多数工作区任务，你不需要完整的容器

Agent 框架通常需要文件系统，无论是读取文件、写入输出、搜索代码还是理解差异。特别是编码 Agent，它们生活在文件系统中。但如果框架运行在无服务器环境中，它如何获得一个在执行之间持久化的耐用文件系统呢？

通常的答案是使用容器。这确实可行，但考虑到 Agent 主要执行的任务，这成本太高了。Agent 转换中的大多数文件系统操作都是文本。考虑一个审查 Agent，它读取文件、在源代码中进行搜索，或者编写一个补丁。你不需要为这些操作启动完整的 Linux 系统。

@cloudflare/shell 为代理提供了一个持久的虚拟文件系统，该文件系统位于其 Durable Object 中，并由 SQLite 支持。它提供了类型化的文件操作 —— 读取、写入、编辑、搜索、grep、diff —— 代理可以利用这些操作作为工具。

而不是调用单独的工具，运行在 Cloudflare 目标上的 Flue 代理会针对工作区虚拟文件状态 API 编写 JavaScript。通过在 Durable Object 中运行更多操作，代理可以利用隔离模型更高效的执行过程，完全避免容器开销：

async () => {
  const files = await state.glob("src/**/*.ts");
  const results = [];
  for (const file of files) {
    const content = await state.readFile(file);
    const todos = content.match(/\/\/ TODO:.*/g);
    if (todos) results.push({ file, todos });
  }
  return results;
}

这为需要运行 shell 和文件系统操作以完成工作的代理提供了一个更快且更节省成本的沙箱环境。对于需要完整操作系统以运行 npm install、git 或编译器的代理，Cloudflare Containers 提供了这些功能。我们还在构建 @cloudflare/workspace，以保持特定 Durable Object 的虚拟文件系统与容器的同步，从而在需要时实现从轻量级 Workers 到 Linux 环境的无缝过渡。

动态工作流：让代理编写自己的工作流以一致地重复任务

但是，当代理需要执行的操作不仅仅是读取文件或执行单个代码片段时会发生什么？当它需要协调一个大规模的、多步骤的流水线，并且需要在一段时间内持续一致地重复执行，例如成功解决错误的代码审查或产生良好结果的研究工作流时，又会发生什么呢？一个代理本身无法提供持久的多步骤执行。它需要平台来持久化每一步操作，重试失败的操作，并在中断后恢复执行。

这种模式正在变得越来越流行。Claude Code 最近推出了动态工作流，其中 Claude 在运行时生成一个 JavaScript 脚本，将工作分配给数十个子代理，运行时会持久化地执行该脚本。@cloudflare/dynamic-workflows 为运行在 Agents SDK 上的任何代理都提供了这一功能。你的代理在运行时生成一个工作流，工作流引擎会持久化每一步操作，重试失败的操作，并可以休眠数小时或等待外部事件，如人工批准。

从 Agent 类中，runWorkflow() 将你的代理连接到工作流引擎。代理启动工作流后可以进入休眠状态。工作流通过 RPC 调用代理，以报告进度、更新状态或请求批准。当工作流完成时，代理会醒来并获取结果。

直接访问 Cloudflare 生态系统

除了计算和存储，代理还需要访问外部功能：网络浏览、电子邮件、内存、搜索、推理。代理不应该需要单独集成这些功能，为每个功能管理 API 密钥，或担心代理生成的代码导致凭证泄露。

Agent 类通过绑定（bindings）让你的 harness 能够访问 Cloudflare 的其他功能：AI Gateway 用于每个 Agent 的支出跟踪和限制，Browser Run 用于网页自动化，Email Service 用于收件箱工作流程，Agent Memory 用于持久化回忆，AI Search 用于检索，Containers 用于需要完整操作系统的任务负载，以及支持 14 多个模型提供商的推理。绑定赋予能力而无需暴露凭证：你的 Agent 使用它们，但密钥永远不会进入由 Agent 生成的代码中。

将你的 Agent 带入 Agent 云

我们知道这种方法有效，因为它正是我们构建 Project Think 所使用的架构基础，这是我们首款原生 Cloudflare Agent 的 harness。虽然 Project Think 仍然是我们高度优化的开箱即用解决方案，用于原生 Cloudflare Agent 体验，但 Agents SDK 确保了更广泛的开源生态系统可以利用这些经过实战验证的相同基础组件，包括 Flue。

如果你今天使用 Flue 构建 Agent，只需几次点击即可部署到 Cloudflare。如果你正在构建自己的 Agent harness 或者 Agent 框架，请针对 Agents SDK 进行开发，可免费获得平台集成。

• Agents SDK: developers.cloudflare.com/agents

• Flue: flueframework.com , npm install @flue/runtime

• Think: docs

• Cloudflare 社区: community.cloudflare.com

[if astro]>server-island-start<![endif]

AI

Cloudflare Workers

开发者

开发者平台

Durable Objects

SDK

MCP