图片 Agent
为用户后台加入图片页面:请求在 agent 运行时上执行图片 Skill,使用用户选择的画幅,并受你设置的每次运行出图上限约束。
图片 Agent 是 Agent 启动模板之上的插件。它在 /app/agent 工作台的输入框里加入 图片 agent(交给它的消息运行 Image Studio Skill)、composer 旁边的画幅选择、图片 artifact 查看器,以及管理后台 /admin/config/image-agent 的 图片 Agent 设置页。侧边栏的 图片 入口(/app/image)是一个快捷方式,打开工作台并预先选好这个 agent。它不新增 Tool 和数据表。图片由 model.generate 在平台的图片场景上生成。
准备工作
- 已安装 Agent 启动模板并部署了 agent 服务:按其指南为
agent.general配好模型并配置沙箱。没有 agent 服务时,图片 入口会被隐藏。 - 已接好图片服务商,
image-creation任务能够完成。参见跑通图片和视频生成。 image-agent插件,它已经在仓库里,依赖agent-starter。可以在 设置 → 插件(/admin/plugins)里看到它。- 管理员账号:
config.read用于打开设置页,保存还需要config.write。
配置两个场景
图片 Agent 使用两个场景,都在 设置 → AI 配置(/admin/config/ai)中按普通场景配置,参见 AI 场景。
| 场景 | 媒体类型 | 用途 |
|---|---|---|
agent.image | 文本 | 图片运行的 agent 循环,需要一个带模型的 OpenAI 兼容对话路由。 |
image-creation | 图片 | 生成图片本身,价格在这条路由上设置。 |
agent.image 不影响 agent 服务的就绪状态。缺少它时,工作台的其他功能照常可用,只有图片页面会提示缺少什么。
Skill 还会调用 image-editing 修改已有图片,调用 image-understanding 查看图片。需要改图和视觉检查时,也要为这两个场景配置路由。在 image-creation 或 image-editing 上生成的图片计入每次运行的张数上限,查看图片不计入。
发布 Skill
运行从 Skill 注册表加载 Skill,不从磁盘读取。Skill 位于 src/plugins/image-agent/skills/image-studio,与平台 Skill 一起发布:
pnpm agent:publish-skills部署时会执行同一步骤,只有内容变化时才发布新的 platform.image 版本。
检查就绪状态并设置上限
打开设置页
进入 设置 → 图片 Agent(/admin/config/image-agent)。就绪状态 列出 agent.image 路由、image-creation 路由和 Skill 发布情况,每项显示 就绪 或 缺少。
设置每次运行的出图张数
在 每次运行的出图张数 中填写 1 到 32(默认 8),点击 保存。超过这个数量的生成会在到达供应商之前被拒绝,模型会收到停止生成并发布已有结果的指示。
使用图片 agent
在用户后台侧边栏打开 图片。工作台会在 /app/agent 打开,agent 选择器里已选中 图片;也可以在那里自己选。选择画幅(1:1、3:4、4:3、9:16 或 16:9),然后描述想要的图片。画幅随消息一起保存,重试旧消息时画幅不变,同一线程的下一次运行也会沿用。某次生成自己指定了画幅时,以它为准。
选择器停在 自动 时,明确要求出图的请求(如「画一张……」「generate an image of…」)会路由到同一个 Skill,工作台在这个线程的后续消息里切换到图片 agent。每张发布的图片既显示在消息里,也可以在面板中打开。
验证
- 在
/admin/config/image-agent,三项 就绪状态 都显示 就绪。 - 打开
/app/image,页面会进入/app/agent并选中 图片。选择 16:9,发送「一张黎明时分山间湖泊的宽幅横幅」。 - 运行会生成并发布图片,面板用图片查看器打开最后一张,并显示像素尺寸。
- 把 每次运行的出图张数 设为 1 再发一次请求。第二次生成会被拒绝,回复中会说明额度已用完。
在仓库中,pnpm validate:image-agent 会在不调用供应商的情况下检查路由、画幅固定、出图上限和接线。
常见问题
图片页面提示图片生成还未就绪
每一行都写明缺少什么。agent.image 的路由必须是带模型的 OpenAI 兼容对话路由,只有图片路由不能用于 agent 循环。
看不到图片入口
这个入口需要 agent 服务。服务没有部署、数据库是 D1,或 agent-starter 被停用时,它会被隐藏。参见运行 Agent 启动模板。
自动模式下请求没有路由到图片
只有明确要求出图的请求才会被路由。在选择器里选中 图片,选中后始终运行图片 Skill。
停用
在 设置 → 插件 中关闭 image-agent。图片 和 图片 Agent 入口会消失,两个页面返回 not found,它的 server function 会拒绝请求,agent.image 上的运行会在启动时被拒绝。关闭 agent-starter 时,图片 Agent 会一起停用。