Image agent
Add an image agent to the workbench: requests run an image Skill on the agent runtime, in the frame the reader picks, with a per-run picture limit you set.
The image agent is a plugin on top of the agent starter. It adds an Images agent to the workbench composer at /app/agent, where its messages run the Image Studio Skill, an aspect-ratio picker next to the composer, a viewer for image artifacts, and an Image Agent settings page at /admin/config/image-agent. The Images sidebar entry at /app/image is a shortcut that opens the workbench with that agent picked. It adds no tool and no table. Pictures come from model.generate on the platform's image scenes.
Before you begin
- The agent starter installed and the agent service deployed: a model for
agent.generaland a sandbox, as described in its guide. Without the agent service the Images entry is hidden. - An image provider wired so that an
image-creationtask completes. See Get image and video generation working. - The
image-agentplugin, which is part of the repository and requiresagent-starter. It is listed in Settings → Plugins (/admin/plugins). - An admin account with
config.readto open the settings page andconfig.writeto save it.
Configure the two scenes
The image agent runs on two scenes, both configured in Settings → AI Config (/admin/config/ai) like any other scene. See AI scenes.
| Scene | Media | What it is for |
|---|---|---|
agent.image | Text | The agent loop of an image run. Needs an OpenAI-compatible chat route with a model. |
image-creation | Image | The pictures themselves. Prices are set on this route. |
A missing agent.image route does not affect the agent service. The rest of the workbench keeps working and only the image page reports what is missing.
The Skill also calls image-editing to revise an existing picture and image-understanding to inspect one. Route those scenes too if you want revisions and visual checks. A picture made on image-creation or image-editing counts toward the per-run limit. Inspecting a picture does not.
Publish the Skill
Runs load Skills from the registry, not from disk. The Skill ships in src/plugins/image-agent/skills/image-studio and is published with the platform Skills:
pnpm agent:publish-skillsDeploys run the same step. It publishes platform.image only when its content changed.
Check readiness and set the limit
Open the settings page
Go to Settings → Image Agent (/admin/config/image-agent). Readiness lists the agent.image route, the image-creation route and the published Skill, each Ready or Missing.
Set pictures per run
Enter Pictures per run, from 1 to 32 (default 8), and click Save. Generations past this number are rejected before they reach a provider, and the model receives an instruction to stop and publish what it has.
Use the image agent
Open Images in the workspace sidebar. The workbench opens at /app/agent with Images selected in the agent picker; you can also select it there yourself. Pick a frame (1:1, 3:4, 4:3, 9:16 or 16:9) and describe the picture. The frame is stored in the message, so retrying an old message keeps its frame, and the next run in the same thread keeps it too. A generation that states its own frame keeps it.
With the picker on Auto, a request that clearly asks for a picture ("draw…", "generate an image of…") is routed to the same Skill, and the workbench switches to the image agent for the rest of the thread. Each published picture is shown inside the message as well as in the panel.
Verify
- On
/admin/config/image-agent, all three Readiness items show Ready. - Open
/app/image. It lands on/app/agentwith Images picked. Choose 16:9 and send "A wide banner of a mountain lake at dawn". - The run generates pictures, publishes them, and the panel opens the last one in the image viewer with its pixel size.
- Set Pictures per run to 1 and send another request. The second generation is rejected and the reply says the budget is spent.
In the repository, pnpm validate:image-agent checks the routing, the pinned frame, the picture limit and the wiring without calling a provider.
Troubleshooting
The image page says image generation is not ready
Each line names what is missing. An agent.image route must be an OpenAI-compatible chat route with a model; an image-only route does not count for the agent loop.
The Images entry is missing
The entry needs the agent service. It is hidden when the service is not deployed, the database is D1, or agent-starter is switched off. See Run the agent starter.
Requests on Auto are not routed to images
Only requests that clearly ask for a picture are routed. Select Images in the picker, which always runs the image Skill.
Turn it off
Switch image-agent off in Settings → Plugins. The Images and Image Agent entries disappear, both pages return not found, its server functions reject calls, and a run on agent.image is rejected when it starts. Switching agent-starter off turns the image agent off with it.
Agent plugins
Build an agent capability as a plugin: it joins the one workbench composer, adds its own cards, panels and operations, and switches on and off at runtime without host changes.
What the base repository contains
The foundation, the modules that ship with it and the agent stack: what each part adds and what it needs.