运行 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:migrateagent 部分已经在仓库里:packages/agent-* 下的工作区包,以及 apps/agent-service 里的独立应用。pnpm install 安装它们的依赖,迁移为所选数据库方言创建 Agent 数据表。如果在快速开始里已经运行过,这两条命令不会再做任何事。
让两个进程找到彼此
# 只放基础设施项。服务商、限额与价格都在 /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在你部署使用的方言下报告0016_agent_starter已应用。/admin/config/sandbox显示沙箱已配置,密钥保存在后台配置表中,页面不回显。/admin/config/search对你启用的每个服务商都返回测试连接成功。- 未登录时
curl -i http://127.0.0.1:5173/api/agent/threads返回401。登录后只返回你自己的会话。 - agent 服务的
GET /healthz返回status: "ok"。场景与沙箱配置完成后,GET /readyz返回200, 且database、schema、objectStorage与providers均为ready。 /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/。