图片 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。每张发布的图片既显示在消息里,也可以在面板中打开。

验证

  1. 在 /admin/config/image-agent,三项 就绪状态 都显示 就绪。
  2. 打开 /app/image,页面会进入 /app/agent 并选中 图片。选择 16:9,发送「一张黎明时分山间湖泊的宽幅横幅」。
  3. 运行会生成并发布图片,面板用图片查看器打开最后一张,并显示像素尺寸。
  4. 把 每次运行的出图张数 设为 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 会一起停用。