agents, models, and providers

agents is the only required block, a model reference is provider/model or a name from models, and providers sets a reusable endpoint such as Docker Model Runner.

You open capture/fixtures/agents/files.yaml and find model: local on the agent, a local entry under models, and provider: dmr inside that entry. A second file, dmr.yaml, adds a providers block with a URL, and its run never reaches the recorder.

When you finish this section, you can follow an agent's model value to the endpoint it calls, and predict what auto picks.

The file and its schema

Agent file: a YAML or HCL document that matches agent-schema.json, the schema of Docker Agent v16. Its root allows 16 keys and requires one: agents, a map of agent configurations with at least one agent {{schema agents}}. A misspelled top-level key fails the load, because the parser rejects unknown top-level keys {{docs-agent Configuration Overview}}.

version is a string from "0" to "16" in the schema enum. The same docs page still gives 15 as the current version {{docs-agent Configuration Overview}}. The capture files declare "16" and load, so this manual follows the schema. When you load an older config, Docker Agent migrates it to the latest schema {{docs-agent Configuration Overview}}. The agent that share pull fetched from agentcatalog/pirate declares version: "2" and names openai/gpt-4.1 inline (16-share-pull-agent.yaml).

version: "16"

agents:
  root:
    model: local
    description: Lists the files of a small repository and counts lines.
    instruction: |
      You answer questions about the files in the working directory.
      Use the tools to look; never guess. Answer in one sentence that
      names the files and gives the line count.
    max_iterations: 8
    toolsets:
      - type: filesystem
      - type: shell

models:
  local:
    provider: dmr
    model: ai/qwen3:4b
    temperature: 0

title: the agent file of the single-agent runs
source: capture/fixtures/agents/files.yaml
lang: yaml
note: Nothing is cut. The same file drives the runs in the session, eval, and share sections.
---
version: "16"

agents:
  root:
    model: local
    description: Lists the files of a small repository and counts lines.
    instruction: |
      You answer questions about the files in the working directory.
      Use the tools to look; never guess. Answer in one sentence that
      names the files and gives the line count.
    max_iterations: 8
    toolsets:
      - type: filesystem
      - type: shell

models:
  local:
    provider: dmr
    model: ai/qwen3:4b
    temperature: 0

Agent keys

Agent: one entry under agents, named by its key. The first agent of the team runs unless --agent names another {{help-agent docker-agent run}}. The schema AgentConfig lists the keys, and these are the ones the capture files use or rely on.

Model references

Model reference: the value of model on an agent. It takes five forms:

• provider/model inline, such as dmr/ai/qwen3 in greeter.yaml {{docs-agent Models}}.
• a name under models, such as local, with provider, model, and parameters such as temperature: 0.
• a first_available list: at load time, Docker Agent picks the first candidate that has its credentials configured {{docs-agent Models}}.
• an alloy: two references with a comma between them, which the runtime alternates in one conversation.
• auto: the first cloud provider that has a configured credential, then a pulled Model Runner model {{docs-agent Set Up a Model}}.

run --model [agent=]provider/model replaces the reference for one run {{help-agent docker-agent run}}. On the recording Mac, doctor resolved auto to dmr/docker.io/ai/qwen3:4b with only the 4B tag pulled (25-doctor.txt). With no Model Runner, it named dmr/ai/qwen3:latest and reported no usable model (16-doctor.txt).

providers and the Model Runner endpoint

Provider definition: an entry under providers with an underlying provider (default openai), a base_url, a token_key, and defaults that its models inherit {{docs-agent Provider Definitions}}.

version: "16"

providers:
  runner:
    provider: dmr
    base_url: http://localhost:12434/engines/llama.cpp/v1

models:
  qwen:
    provider: runner
    model: ai/qwen3:4b
    temperature: 0
…

title: a named provider for Docker Model Runner
source: capture/fixtures/agents/dmr.yaml
lang: yaml
note: The agents block is cut.
---
version: "16"

providers:
  runner:
    provider: dmr
    base_url: http://localhost:12434/engines/llama.cpp/v1

models:
  qwen:
    provider: runner
    model: ai/qwen3:4b
    temperature: 0
…

files.yaml names provider: dmr with no base_url, and then Docker Agent finds the DMR endpoint by itself {{docs-agent Docker Model Runner}}. It runs docker model status --json, which 16-dry-run.txt prints inside its error when no Docker daemon answers. An eval container has no docker CLI, so the same discovery fails there, as eval shows.

With an explicit base_url, dmr.yaml answered Hello (the capture). That run is live in every capture, because an explicit base_url bypasses the --record proxy and leaves the cassette empty (kit notes). Set base_url when discovery cannot work, and leave it out when you want a cassette.

Provider ids changed too. doctor prints fireworks-ai, togetherai, and moonshotai, and the docs Models table lists fireworks, together, and moonshot. This manual prints the ids that doctor prints (conflict C58), and the providers table has the rest. A named patch under flavors changes any of these blocks at run time with --flavor {{help-agent docker-agent run}}, and the capture ran none.

Fig. 5.2two ways a model reference reaches Model Runnerstructure

Original SVG

Original source

id: fig-5-2
kind: structure
title: two ways a model reference reaches Model Runner
claim: `files.yaml` resolves `local` to the `dmr` provider and finds the endpoint itself, while `dmr.yaml` resolves `qwen` through `providers.runner` to a fixed URL.
caption: Read each column top down, from the agent to the endpoint. Violet blocks are agent entries and plum blocks are model and provider entries. The bottom row is the `auto` decision as `doctor` printed it. From capture/fixtures/agents/files.yaml, capture/fixtures/agents/dmr.yaml, capture/out/16-doctor.txt, 16-dry-run.txt, and 25-doctor.txt.

- Give every agent file a `version` string and only top-level keys from the schema.
- Name models under `models` so that parameters such as `temperature` live in one place.
- Set `base_url` only when discovery cannot work, because it bypasses `--record`.
- Read the `auto` line of `docker-agent doctor` before you rely on `auto`.

Sources: schema agents, AgentConfig (research/sources/agent-schema.json); docs-agent Configuration Overview, Models, Set Up a Model, Provider Definitions, Docker Model Runner (research/sources/docs-docker-agent.md, pages configuration/overview, concepts/models, getting-started/set-up-a-model, providers/custom, providers/dmr); help-agent docker-agent run (research/sources/help-docker-agent.md); conflict C58 (research/conflicts-register.md); capture/README.md; capture/fixtures/agents/files.yaml, dmr.yaml, greeter.yaml; capture/out/16-doctor.txt, 16-dry-run.txt, 16-share-pull-agent.yaml, 25-doctor.txt, 25-run-dmr.txt