Kernlift

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.general and a sandbox, as described in its guide. Without the agent service the Images entry is hidden.
  • An image provider wired so that an image-creation task completes. See Get image and video generation working.
  • The image-agent plugin, which is part of the repository and requires agent-starter. It is listed in Settings → Plugins (/admin/plugins).
  • An admin account with config.read to open the settings page and config.write to 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.

SceneMediaWhat it is for
agent.imageTextThe agent loop of an image run. Needs an OpenAI-compatible chat route with a model.
image-creationImageThe 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-skills

Deploys 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

  1. On /admin/config/image-agent, all three Readiness items show Ready.
  2. Open /app/image. It lands on /app/agent with Images picked. Choose 16:9 and send "A wide banner of a mountain lake at dawn".
  3. The run generates pictures, publishes them, and the panel opens the last one in the image viewer with its pixel size.
  4. 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.