Docker Agent: build a repeatable review workflow from one YAML file

What the documentation establishes

Docker documents Docker Agent as an open-source framework for custom agent teams. It is included in Docker Desktop 4.63 and later; earlier Desktop releases used the name cagent. Source ↗

Agent roles and instructions are defined in configuration, and a root agent can delegate to named sub-agents with separate context. Source ↗

The quickstart supports both an interactive session and a one-shot run using --exec. Source ↗

Model setup supports cloud credentials or a local Docker Model Runner model. The doctor command checks setup; choosing a local model still requires a suitable installed model and hardware. Source ↗

The walkthrough below is an original worked exercise. We have not independently tested this product’s performance.

1. Define a job small enough to judge

Write the output contract before choosing a model. A triage note needs four parts: what happened, which evidence supports it, what remains unknown, and the next diagnostic action. A polished explanation that silently invents a cause fails the task. Avoid an open-ended instruction such as “investigate everything”; it makes both cost and completion hard to evaluate.

For our fictional release, the evidence says requests started failing after a deployment, but it does not prove the deployment caused them. We want the agent to preserve that distinction. Keep a human-written expected answer beside the input. When you change a prompt, compare against that answer rather than deciding whether the new prose sounds more confident.

Return exactly these headings:
Observed events
Evidence IDs
Unresolved questions
Next diagnostic action
Use only the supplied evidence. Label hypotheses explicitly.
Do not propose a production change before a diagnostic check.
If a requested fact is absent, say what evidence would establish it.

2. Check the installation and model first

Use Docker’s installation instructions linked below for your operating system. The commands here assume Docker Agent is already available. Start with the setup check; if it fails, solve that problem before editing the task instructions. Changing a prompt will not repair a missing model connection.

Choose one model for the initial experiment and record its identifier. If you select a cloud provider, understand where the supplied evidence will be sent and use only material you are allowed to provide. If you select a local model, check that it actually loads on your machine. Neither choice makes the output automatically correct. Keep credentials out of the YAML and the saved research report.

docker agent doctor
docker agent setup

The setup wizard is an interactive configuration step, not part of a recurring task. Complete it once, then keep the chosen model explicit in the experiment. The configuration below uses a model identifier from Docker’s setup example; replace it with a model you have configured if needed.

3. Save a focused configuration

Save this original example as incident-review.yaml in a small exercise folder. The model and instructions are explicit so a later revision can be compared with the same starting point. Do not add integrations yet. The agent should be able to complete this exercise from a short pasted note.

The root role is an evidence editor. It does not need to pretend to be a complete operations team. Its job is to structure what you know and make the next investigation concrete. Save each configuration revision alongside the output you evaluated; otherwise you will not know which change improved or degraded the result.

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Prepare a bounded incident triage note
    instruction: |
      Work only from the evidence supplied in the conversation.
      Return Observed events, Evidence IDs, Unresolved questions,
      and Next diagnostic action. Separate hypotheses from observations.
      Cite evidence IDs beside every factual statement.
      Do not invent timestamps, owners, root causes, or measurements.
      Recommend one diagnostic check before any production change.
      When evidence conflicts, describe the conflict rather than choosing
      the more convenient account. Do not claim to have run a check.

4. Run the same example twice

docker agent run incident-review.yaml

E1: At 09:10 UTC, the team deployed build 42.
E2: At 09:14 UTC, support reported that some customers saw a checkout error.
E3: A dashboard screenshot shows 3% failed requests for the last hour.
E4: No pre-deployment error-rate measurement is included.
E5: A teammate guesses the payment provider is slow; no latency data is included.
Question: Prepare a triage note for the release meeting.

A successful answer can state the temporal ordering of E1 and E2. It must not conclude that build 42 caused the errors, or that failures increased from zero to three percent. E4 explicitly removes the baseline needed for the second claim. The payment-provider explanation is an untested hypothesis from E5.

For the second run, change only E3 to a screenshot covering the preceding day. The answer should now flag a mismatch between the reporting window and the incident window. If it repeats the first answer unchanged, your evaluation has exposed a real weakness. Preserve both outputs, including the failure, instead of selecting the more impressive one for a demo.

docker agent run --exec incident-review.yaml "E1: Build 42 deployed at 09:10 UTC. E2: Checkout failures reported at 09:14 UTC. No baseline is provided. Produce the triage note."

5. Score the result before adding another agent

Record each check as pass or fail, then add elapsed time, model identifier, and any reported usage. A single successful output is a demonstration, not a reliability estimate. Use several deliberately varied notes: missing times, contradictory reports, duplicated evidence, and an irrelevant instruction embedded inside a quoted log. The latter should be treated as input data, not a new task.

Only consider a second agent if failures have a separable cause. For example, a reviewer could examine whether every claim has an evidence ID. Define its output contract and compare the combined system against the single-agent baseline. More roles can create additional handoff errors; the second agent must improve measured results enough to justify its cost.

6. Turn the experiment into a maintained workflow

When the exercise passes, save a small run record containing the configuration revision, the input identifier, the selected model, the output, and the scorecard. Keep the raw evidence with its original timestamps. That record lets someone reproduce the evaluation when the model, prompt, or framework changes.

Introduce one capability at a time. If the next job is reading a repository, define the allowed working directory and decide which files must stay out of the context before adding a filesystem tool. If the next job involves changing systems or sending messages, add an explicit review stage and verify the tool permissions. The exercise above does not establish those integrations or their safety.

Keep a clear stopping rule: if an instruction change cannot pass the existing examples after a bounded number of attempts, keep the previous working configuration and record the failure. A maintained workflow is a versioned procedure with evidence, not a stream of increasingly elaborate prompts. Revisit the Docker documentation when commands or configuration fields change, and rerun the same cases before replacing the baseline.

Guide history

Revisions preserve the original instructions. A source recheck alone does not create a new revision.

Revision 2 · Added a concrete installation/model preflight, consistent saved inputs for interactive and one-shot runs, a complete expected answer, isolated second test, and symptom-based recovery steps. Removed video discovery metadata from the instructional source list; prior revision retains it.

Revision 1 · New documented configuration, fictional incident, evaluation scorecard, and maintenance procedure.

Continue learning