Model companions

Model companions let your agent use a specialist model for images, audio, or video while its main model handles the conversation and tool use. For example, it can read a screenshot, transcribe a recording, or generate an image without switching agents.

Ask for media work

Attach a file with @path and describe the result you need:

Read @./dashboard.png and explain which service is failing.

For generation, give a brief:

Generate a square illustration for a garden journal: herbs on a windowsill,
soft morning light, watercolor style, no text.

In a local terminal, Jazz can ask you to select a capable model for an unconfigured role. For recurring or unattended work, configure the companion in advance.

Configure companions

Add bindings to the agent’s config in ~/.jazz/agents/<id>.json:

{
  "config": {
    "llm": {
      "provider": "openai",
      "model": "gpt-5.4-mini"
    },
    "companions": {
      "analyze:image": "openrouter/inclusionai/ling-3.0-flash-vl",
      "analyze:audio": "alibaba/qwen3.6-27b",
      "analyze:video": "openrouter/inclusionai/ling-3.0-flash-vl",
      "generate:image": "openrouter/google/gemini-3.1-flash-image"
    }
  }
}

The main agent keeps its persona, conversation, memory, and tools. Each companion receives only the media and task needed for its role, then returns its result to the main agent. Configure credentials for each selected provider; see Model providers.

The six independent roles are analyze:image, analyze:audio, analyze:video, generate:image, generate:audio, and generate:video. Analysis and generation are separate because a model that understands a medium is not necessarily the model you want to create it.

What a companion receives

When the main agent delegates media work, Jazz starts a bounded, ephemeral companion run:

1. Jazz resolves up to eight named files and verifies their media type.
2. The companion receives the files plus a self-contained analysis task, and none of the parent conversation, tools, or memory.
3. It runs with no tools, at most four iterations, and a 30-minute timeout.
4. An analysis result returns as text. Generated media is saved under $JAZZ_HOME/generated/ and returned as an artifact on the current surface.
5. The companion cost is added to the parent run, which then continues the job.

This is different from a subagent. A subagent inherits the parent’s model and a bounded version of its tools for general delegated work. A companion changes the model specifically to cross a media capability boundary.

Interactive and unattended selection

In the terminal, an unbound agent first asks you to choose a provider that offers models for the requested role. If that provider is not configured, Jazz asks for its credential in a masked prompt (and saves it to Jazz config); it then offers only that provider’s capable models in the approval picker, with known prices shown. The chosen model is not run until you approve the media delegation. ChatGPT uses subscription sign-in rather than an API key; sign in with jazz config before selecting it. Jazz never silently chooses a paid provider.

CI, schedules, webhooks, and chat bridges cannot stop at an interactive provider/model picker. Bind every role the job may use in the agent JSON before running unattended. That binding is standing consent to send the selected media and task to that provider.

For one headless run, override analysis companions without changing the saved agent:

jazz run --agent analyst --with-vision openrouter/inclusionai/ling-3.0-flash-vl \
  "Read @/tmp/dashboard.png and identify the failing service and time window"

Equivalent flags exist for --with-audio and --with-video.

Attachments and generated files

Use @path in a terminal message or prompt to attach a local file. Chat bridges translate their platform attachments into the same structured message format. If the primary model already accepts that media type, Jazz can send it directly; analyze_media remains available when specialist perception would be more accurate or economical.

For generation, the parent gives the companion a self-contained brief. The resulting image, audio, or video belongs to the parent run: terminal output links it, JSON output reports it as an artifact, and chat bridges upload it when the platform supports that medium. A capable primary model can still emit media directly; a generate:* binding lets you choose a specialist without replacing the agent’s reasoning model.

jazz agent list --can image|audio|video finds configured agents that can produce a medium, either by their own model or by a bound generate:* companion marked via companion, and suggests capable models when none can. Companion bindings are configured independently in the agent file, so one agent can use six different specialists if the work calls for it.

Security and cost

A companion receives its input through its provider and therefore creates egress even when the parent uses a local model. A generation brief can be sensitive too. Bind only providers permitted to receive that material. The child cost contributes to the parent run’s aggregate cost; if any child price is unknown, costKnown is false.

Build a working version in Turn incident evidence into a visual briefing.