Agent 运行机制
可选的 agent 服务如何部署,Web 应用如何判断它是否可用,以及运行、工作区、技能和决策之间的关系。
Agent 是 Web 应用旁边的一个独立服务,而且是可选的。不部署它时,Web 应用本身是完整的:AI 任务和对话通过 /app/ai、/app/chat 和 /api/chat 直接调用已配置的渠道。部署了服务之后,Web 应用负责用户鉴权和所有权检查,再把签名请求转发给它。服务执行 agent 循环、沙箱和自己的后台工作器。浏览器始终只请求 Web 应用的 /api/agent/* 路由。
两个进程,单向信任
apps/agent-service 是 agent-starter 模板安装的一个 Node 进程。Web 应用通过两种方式之一访问它:
| 传输方式 | 适用场景 | 如何配置 |
|---|---|---|
url | Node 服务器、其他平台上的容器,或本地开发 | Web 应用环境里的 AGENT_SERVICE_URL |
container | Cloudflare Worker,agent 以 Cloudflare 容器运行 | wrangler.jsonc 里的 AGENT_SERVICE Durable Object 绑定 |
两种方式发送的是同一份签名请求。AGENT_INTERNAL_SIGNING_SECRET 用来认证两个进程之间的请求,AGENT_RESOURCE_GRANT_SECRET 用来签发访问存储文件的短期令牌。服务不接收会话、OAuth 和支付相关的变量,环境里出现这类变量时会拒绝启动,因为它要在沙箱里执行不受信任的代码。
在 Cloudflare 上,所有请求都发往同一个命名的容器实例。服务在内存里持有流订阅、进行中的运行和沙箱池,同一次运行的请求必须落到同一个进程。有未完成的运行时,Worker 的 Cron Trigger 会让这个容器执行一轮维护,同时保持它不休眠。
可用性只有一个答案
getAgentAvailability() 返回这个部署能否运行 agent。它只读插件状态、环境变量和数据库方言,不加载 agent 运行时,所以后台布局在每次导航时都可以调用。
| 原因 | 含义 |
|---|---|
plugin_disabled | agent-starter 插件在 设置 → 插件 中被停用。 |
database_not_transactional | 数据库是 Cloudflare D1,没有交互式事务。 |
service_not_configured | 既没有 AGENT_SERVICE_URL,也没有 AGENT_SERVICE 绑定。 |
signing_secret_missing | 没有设置 AGENT_INTERNAL_SIGNING_SECRET。 |
所有 agent 入口都使用这个结果:
- 带
requires: "agent"的导航项被隐藏。 /app/agent和/app/image说明 agent 服务没有部署,以及下一步该做什么。/api/agent/*返回503和错误码agent_unavailable。
可用不等于就绪。服务是否有模型路由和沙箱,由下文的就绪检查报告。
数据库必须支持事务
接受一次运行、回答问题、处理审批、领取后台任务,每一项都是必须同时成功的多条语句。因此 agent 仓储在读写任何数据之前,就会拒绝不支持交互式事务的数据库,错误码是 agent_requires_transactions。
| 数据库 | Agent |
|---|---|
| Postgres | 支持。在 Worker 上 Web 应用经 Hyperdrive 连接,容器直连。 |
| Node 上的 SQLite | 支持。仓储门面包装了 better-sqlite3 连接,让异步事务回调一个接一个执行。 |
| Cloudflare D1 | 不支持。Web 应用照常运行,agent 入口不出现。 |
运行背后的引擎
packages/agent-runtime 用 DeepSeek Harness 的包(@deepseek-ai/cordis 和 @deepseek-ai/dsh-*)组合出运行循环:agent 循环、以事件日志持久化的会话、上下文压缩、token 计量、旧工具结果裁剪和服务商重试。依赖版本是固定的,其中一个包带有 patches/ 下的补丁,通过 pnpm 的 patchedDependencies 应用。
宿主代码不直接 import 这些包,只依赖 runtime-contracts.ts 里面向产品的合约,所以引擎可以在包内部替换,不影响 src/server 和 apps/agent-service。pnpm validate:dsh-runtime 检查版本固定、业务代码没有直接 import 引擎,并运行引擎的合约测试。
Web 的请求路径不会加载运行时。路由通过窄的子路径导出引用运行时的辅助函数,不引用包入口。pnpm validate:optional-agent 会检查构建产物。
线程、运行与工作区
线程保存对话历史。运行是回答一条消息的一次尝试。POST /api/agent/runs 提交消息、幂等键,以及可选的已有线程、分支或指定技能。每次运行拥有独立工作区。附件和小型工作区文件在模型第一轮之前放入这次运行。后续运行不能读取上一次的工作区。引用旧产物需要显式随新消息传入。
运行会固定主技能、附加能力技能、场景和工具集合。即使 registry 的最新技能版本发生变化,恢复的运行仍使用原来的有效配置。服务解析生效的 AI 场景路由,并通过服务端积分账本结算预留积分。模型、沙箱或存储未配置时会明确报错,不会输出示例结果。一个用户可以同时进行多少次运行,由套餐的 concurrentAgentTasks 权益决定。
创建运行的响应和线程快照都带有 routing:这次运行落到的场景、主技能和插件。工作台用它跟随被自动路由的请求。
状态与决策
| 状态 | 含义 | 后续动作 |
|---|---|---|
queued | 已接受,尚未执行 | 工作器启动;也可能在执行前失败或取消。 |
running | 模型与工具正在执行 | 可能完成、失败、中断,或等待用户。 |
waiting_user | 运行提出问题 | 所有者回答该次用户请求。 |
waiting_approval | 工具动作需要同意 | 所有者批准或拒绝该动作。 |
completed、failed、canceled、interrupted | 终态 | 同一次运行不会回到 running;继续工作需要新的运行。 |
审批请求带有指纹和策略版本,回应时必须连同决定一起带回,所以不能用旧按钮批准已经变化或过期的动作。用户请求是一个问题,走另一个端点。重连流只是恢复对运行的观察,不会创建第二次运行。取消是发给服务的请求,并不保证已经完成的动作可以撤销。
技能、工具与沙箱
平台技能在源码的 agent-skills/ 目录里,能力插件的技能放在插件自己的目录里。pnpm agent:publish-skills 把它们打包到对象存储和技能 registry。运行时读取已授权的已发布版本,不读取本地文件。运行可以自动选择技能,也可以固定某个已授权的版本。agent-skills/ 与 skills/ 相互独立,后者是给编码助手用的工作流。
需要执行代码的工具使用 /admin/config/sandbox 配置的沙箱。搜索和抓取工具使用 /admin/config/search 配置的服务。连接器动作需要各自的账号授权。资源预览和下载使用按所有者签发的短期授权,存储的产物不会变成公开地址。
核心之外的能力(例如图片 agent)是同一个工作台的插件。它们声明场景、技能、卡片和操作,由宿主校验,并随插件一起停用。见插件和 Agent 插件。
就绪与失败边界
Agent 服务的 GET /healthz 报告进程是否存活。GET /readyz 检查数据库可达、schema 版本、对象存储和可用的服务商配置,任何一项必需检查未就绪时返回 503。/app/agent 的输入框有自己更窄的检查:一条生效的 agent.general 文本路由及其引用的密钥,加上已配置的沙箱。搜索和抓取只在用到它们的工具里才需要。就绪检查不会模拟调用服务商。
Web 应用自己的后台工作(履约重试、未完成的 AI 任务)在 Web 应用的定时任务里执行,不在 agent 服务的循环里,所以没有 agent 也照常进行。见后台任务。
相关文件
下一步
- 运行 Agent 启动模板:配置、启动与检查。
- 插件:agent 能力如何安装、启用和停用。
- 积分:预留与结算。