运行 Agent 启动模板

安装 agent 模板,配置模型通道、沙箱与搜索服务商,启动 agent 服务并打开工作台。

agent-starter 模板增加 Agent 工作台和独立的 Node 服务。服务协调运行、审批、用户请求、技能、工具和每次运行独立的工作区。模型调用使用已配置的 AI 通道,积分由服务端预留和结算。Agent 是可选的。不部署这个服务时,Web 应用依然完整,agent 入口会显示服务未部署。本指南说明安装与就绪检查。执行模型见 Agent 运行机制。

模板包含什么

组成位置
agent 契约、运行循环、工具与浏览器客户端packages/agent-{contracts,runtime,tools,client}
沙箱适配与镜像packages/sandbox-adapter、packages/sandbox-adapter/template/Dockerfile
agent 服务(第二个进程)apps/agent-service
运行、会话、消息、技能、审批、工作区与后台任务数据表迁移 0016_agent_starter,SQLite 与 Postgres 各一份
面向浏览器的鉴权接口/api/agent/**
工作台/app/agent
agent-starter 插件:导航入口与路由归属src/plugins/agent-starter
服务商配置页/admin/config/sandbox、/admin/config/search
平台技能与发布脚本agent-skills/、pnpm agent:publish-skills
自带校验器pnpm validate:agent-starter、validate:optional-agent、validate:dsh-runtime、validate:agent-plugin-contract、validate:sqlite-transactions、validate:agent-generation

工作台需要可用的 agent.general 模型路由和已配置沙箱。搜索与抓取服务商只对使用它们的工具必需。配置缺失时工作台会显示缺少的配置,不会模拟服务商响应。

准备工作

  • 底座仓库,或 image-agent、video-agent 业务模板。它们都包含 agent 部分。参见获取 Kernlift。
  • Node 20 或更高版本,以及一个能在本地运行的项目。参见快速开始。
  • Postgres,或运行在 Node 上的 SQLite。 agent 运行需要交互式事务,而 Cloudflare D1 没有。 在 D1 上 web 应用照常运行,agent 入口被隐藏,/api/agent/* 返回 503 agent_unavailable。 参见使用 Postgres 与 Supabase。
  • 拥有 config.read 与 config.write 权限的管理员账号。模板新增的两个配置页沿用后台已有的权限, 不需要再授予新权限。
  • 在 /admin/config/storage 配置好对象存储。 技能包、运行产物与工作区文件都存在那里。 在配置好之前 pnpm agent:publish-skills 不会发布任何内容,并输出原因。pnpm dev:agent 会输出同样的提示, 并照常启动两个进程,以便访问配置页。参见配置文件存储和上传。
  • 如果要让 agent 执行脚本,还需要一个 E2B 兼容的沙箱服务;如果要让它检索网页与提取正文, 还需要 SearXNG 与 crawl4ai。

配置 agent 服务

安装依赖并迁移

pnpm install && pnpm db:migrate

agent 部分已经在仓库里:packages/agent-* 下的工作区包,以及 apps/agent-service 里的独立应用。pnpm install 安装它们的依赖,迁移为所选数据库方言创建 Agent 数据表。如果在快速开始里已经运行过,这两条命令不会再做任何事。

让两个进程找到彼此

.env
# 只放基础设施项。服务商、限额与价格都在 /admin/config/* 中配置。
AGENT_SERVICE_URL=http://127.0.0.1:3001
AGENT_WEB_INTERNAL_URL=http://127.0.0.1:5173
AGENT_INTERNAL_SIGNING_SECRET=
AGENT_RESOURCE_GRANT_SECRET=

运行两次 openssl rand -hex 32。将两个独立的随机值分别填入上面的密钥字段,并在 Web 和 Agent 进程的对应字段中使用同一组值。

AGENT_SERVICE_HOST、AGENT_SERVICE_PORT、AGENT_SERVICE_REQUEST_TIMEOUT_MS 与 AGENT_FLOW_LOG_LEVEL 是可选项,AGENT_SANDBOX_ERROR_LOG_ENABLED 也是,.env.example 中列出了它们与默认值。服务商密钥应在管理后台配置。 这些变量只在运行 agent 时需要。没有 AGENT_SERVICE_URL 和签名密钥时,web 应用把 agent 视为未部署。

两个进程

web 应用负责页面、对每个 /api/agent/** 请求鉴权并转发。apps/agent-service 是一个 Node 进程, 运行 agent 循环、沙箱与后台工作器。两者通过签名 HTTP 通信,使用上面两个密钥。 签名密钥用于两个进程之间的请求鉴别,资源授权密钥用于签发沙箱访问文件或模型时使用的短期令牌。

本地开发时,pnpm dev 只运行 web 应用,下面这条命令同时运行两个进程:

pnpm dev:agent

它会先执行迁移、发布平台技能、构建附件解析器,然后同时运行 Vite 与 agent 服务。 两个密钥未设置或不足 32 字节时,它会为本次会话临时生成,因此第一次运行不需要先准备密钥。 还没有配置对象存储的项目发布不了任何技能。该命令会输出提示并照常启动两个进程, 这样仍可访问 /admin/config/storage 完成配置。

准备沙箱与检索服务

厂商适用场景
E2B在 E2B 运行器中执行脚本
阿里云沙箱使用阿里云运行器镜像
Novita Sandbox使用 Novita 沙箱
SearXNG通过自托管实例搜索
Crawl4AI抓取网页正文

配置服务商

模型通道

打开 /admin/config/ai,为每个 agent 场景配置生效的路由:agent.general 用于普通对话,agent.research 用于以搜索为主的运行,agent.mail 用于邮件助理,agent.audio 用于语音。没有生效通道的场景会被判为未配置, 需要它的运行会失败并提示模型未配置。参见配置 AI 场景。

沙箱

打开 /admin/config/sandbox,启用沙箱,选择服务商与其控制面地址,设置运行器模板与运行时上限,并填入服务商密钥。 密钥只写,保存在后台配置表中,之后不再回显。这里没有 E2B_* 环境变量兜底。没有配置的沙箱报告为不可用, 脚本类工具返回错误。运行器模板所用的镜像来自 packages/sandbox-adapter/template/Dockerfile。

搜索

打开 /admin/config/search 配置 SearXNG(检索)与 crawl4ai(网页正文提取)。两者各有地址、鉴权头、 超时与启用开关,并各带一个 测试连接 按钮,点击后对你填写的服务发起一次真实请求。

平台技能

agent-skills/ 存放 agent 可加载的技能:general-chat 与 mail-assistant。已安装的能力插件(例如图片 Agent) 把技能放在自己的插件目录里,由同一条命令发布。

pnpm agent:publish-skills

该命令会把每个技能打包发布到技能注册表,内容与当前生效版本一致的会跳过。运行从注册表加载技能,不读取磁盘文件, 所以改完技能要重新发布,每次部署也要执行一次。agent-skills/ 和 skills/ 是两个目录,后者是本仓库给编码助手用的文档。

打开工作台

两个进程都启动之后,登录并打开 /app/agent。会话列表、流式对话、审批与产物面板都在这个页面上。 服务商未配置时,页面会显示缺少的配置并禁用不可用的操作。

部署

两个进程分别部署,并且 web 应用必须能访问到 agent 服务。

agent 服务

构建产物,并在 Node 22 或更高版本上直接运行,或放进容器:

pnpm build:agent-service
node apps/agent-service/dist/main.js

只给它数据库连接、AGENT_INTERNAL_SIGNING_SECRET、AGENT_RESOURCE_GRANT_SECRET、 AGENT_WEB_INTERNAL_URL 与监听地址,别的都不要。当环境中出现认证或支付类密钥时 (BETTER_AUTH_*、AUTH_*、STRIPE_*、PAYMENT_* 等),该进程会拒绝启动, 因为它在沙箱中运行不受信任的代码,不能持有这些密钥。同一次构建还会产出 dist/publish-skills.mjs, 部署时的技能发布步骤运行这个文件。

web 应用

Web 应用可按现有方式部署,但必须连接存放 Agent 数据表的数据库,所以不能用 D1。 把 AGENT_SERVICE_URL 指向 agent 服务的内网地址,并且不要把该服务暴露到公网。浏览器不直接访问它。

在 Cloudflare 上,agent 服务以容器的形式运行在 Worker 旁边。Worker 经 Hyperdrive 连接 Postgres (DATABASE_DIALECT=postgres、DATABASE_ADAPTER=hyperdrive),容器用 AGENT_DATABASE_URL 直连, AGENT_SERVICE 绑定取代 AGENT_SERVICE_URL。wrangler.jsonc 里注释掉的配置块列出了步骤。参见 部署到 Cloudflare Workers、部署到 Node 主机, 以及 Fly.io、Railway 和 Docker 的部署指南,它们都把 agent 作为单独的服务运行。

每次部署之后

pnpm db:migrate
pnpm agent:publish-skills

两条命令都是幂等的。没有新迁移、技能也没有变化时,它们不会写入任何内容。

验证

  1. pnpm db:migrate 在你部署使用的方言下报告 0016_agent_starter 已应用。
  2. /admin/config/sandbox 显示沙箱已配置,密钥保存在后台配置表中,页面不回显。
  3. /admin/config/search 对你启用的每个服务商都返回测试连接成功。
  4. 未登录时 curl -i http://127.0.0.1:5173/api/agent/threads 返回 401。登录后只返回你自己的会话。
  5. agent 服务的 GET /healthz 返回 status: "ok"。场景与沙箱配置完成后,GET /readyz 返回 200, 且 database、schema、objectStorage 与 providers 均为 ready。
  6. /app/agent 能完整执行一轮对话,并且这次运行的积分预留在积分账本中结算为实际消耗。

在仓库中运行 pnpm validate:agent-starter 和 pnpm validate:optional-agent。

故障排查

Agent 入口不见了,或 /api/agent/* 返回 503

Web 应用报告 agent 不可用。响应带有错误码 agent_unavailable 和 x-agent-unavailable-reason 响应头:

原因处理
plugin_disabled在 设置 → 插件 中启用 agent-starter。
database_not_transactional数据库是 D1。改用 Postgres,或 Node 上的 SQLite。
service_not_configured设置 AGENT_SERVICE_URL;在 Cloudflare 上则加上 AGENT_SERVICE 容器绑定。
signing_secret_missing在两个进程里把 AGENT_INTERNAL_SIGNING_SECRET 设为同一个值。

管理员在 /app/agent 上能看到同样的原因。

agent 脚本以 agent_requires_transactions 失败

进程连接的数据库不支持交互式事务(D1)。把它指向 Postgres(DATABASE_DIALECT=postgres) 或 Node 上的 SQLite。脚本在写入任何数据之前就失败,不会留下需要清理的数据。

运行提示模型未配置

该运行需要的场景没有生效的通道路由。在 /admin/config/ai 中配置。在每个生效路由都能解析到带密钥的通道之前, /readyz 会一直报告 providers: not_ready。

脚本类工具提示沙箱未配置

/admin/config/sandbox 未启用或缺少密钥。这里没有环境变量兜底,只能在该页面保存密钥。

服务以 forbidden_agent_service_configuration 退出

它的环境里带了认证或支付类密钥。删掉它们。该服务只需要数据库、两个 agent 密钥与 web 内部地址。

pnpm agent:publish-skills 提示对象存储未配置

技能包保存在对象存储里,所以 /admin/config/storage 没有配置服务商之前发布不了任何内容。 该命令以非零码退出,部署中执行到它会停下。pnpm dev:agent 打印同样的提示并启动两个进程, 以便访问配置页。配置之后重新执行发布。

新技能对运行没有产生效果

技能只改了磁盘上的文件,没有发布。运行 pnpm agent:publish-skills。运行从注册表读取技能,不读取 agent-skills/。

参考

下一步