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 应用通过两种方式之一访问它:

传输方式适用场景如何配置
urlNode 服务器、其他平台上的容器,或本地开发Web 应用环境里的 AGENT_SERVICE_URL
containerCloudflare 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_disabledagent-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 也照常进行。见后台任务。

相关文件

src/server/agent-host/availability.ts
src/server/agent-host/repository.ts
src/server/services/agent-api-bridge.service.ts
src/server/services/agent-route-readiness.service.ts
src/server/platform/agent-service-container.ts
apps/agent-service/src/main.ts
apps/agent-service/src/server.ts
apps/agent-service/Dockerfile
packages/agent-runtime/src/runtime.ts
packages/agent-runtime/src/runtime-contracts.ts
packages/agent-contracts/src/run.ts
packages/agent-contracts/src/api.ts
scripts/validate/optional-agent.ts
scripts/validate/dsh-runtime.ts
scripts/validate/sqlite-transactions.ts

下一步