What you’ll leave with
A reusable incident-triage configuration, a test input with known mistakes, and a scorecard for evaluating the output before connecting real tools.
Before you begin. Docker Desktop 4.63+ with Docker Agent, or a standalone installation from the official instructions; one working model connection; and an empty exercise folder. Provider use may be billed. Commands and configuration were checked against Docker documentation on October 16, 2026; Docker Agent and external model inference were not executed by Current.
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.
Docker Agent runs an assistant from a configuration file that you can keep with your project. This guide builds one concrete result: a four-part incident note from five fictional evidence records. You will save the input, run a configured model, compare the answer with a written key, then repeat with one changed reporting window.
The starting experiment deliberately has no filesystem or shell toolset. You paste the evidence. This keeps the exercise focused on instructions and evaluation, rather than letting a tool integration hide poor reasoning. The same design works for a nontechnical meeting brief: replace the incident facts with a meeting transcript and keep the requirement to identify unknowns.
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
First choose an installation route. Docker Desktop 4.63 or later includes Docker Agent. For a separate installation, Docker documents Homebrew, Winget and release binaries; follow the linked installation page for your operating system. If Docker itself works but docker agent is missing, fix the Agent installation before proceeding.
Make an empty folder named incident-review and open a terminal there. Run the setup wizard below and choose one provider. For this exercise use the built-in Anthropic route if you can access the model in the YAML, or replace that model with an identifier your configured provider supports. A local alternative is Docker Model Runner; the model must already be downloaded and able to load on your hardware.
docker agent setup
docker agent doctorFor the cloud path, the wizard stores the provider credential outside the agent YAML. A passing diagnostic must show the intended provider credential as found. For a local path it must show Model Runner reachable with a model available. Record the selected model and date with your experiment. Do not use a bare default-agent run as proof that the YAML below is using the same model.
The sample names anthropic/claude-sonnet-4-5 because that identifier appears in Docker’s current quickstart. It is an example, not a newest-model recommendation or a guarantee of access. If your provider rejects it, select a supported identifier and record the substitution. Cloud inputs go to the provider; this exercise uses invented evidence.
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.docker agent doctor incident-review.yaml4. Run the same example twice
Save the evidence block below as evidence-a.txt as well as pasting it into the interactive session. Keep the output as triage-a.txt. End that session before the second test: a fresh run prevents the previous answer from influencing the changed-window case. Save a separate evidence-b.txt with only E3 changed, then save its response as triage-b.txt.
docker agent run incident-review.yamlE1: 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.
cat evidence-a.txt | docker agent run --exec incident-review.yaml "Prepare the triage note from the supplied evidence."Observed events
Build 42 was deployed at 09:10 UTC [E1]. Support reported checkout errors at 09:14 UTC [E2]. The screenshot reports 3% failed requests over one hour [E3].
Evidence IDs
E1 and E2 establish sequence only. E3 has a one-hour window. E4 says no pre-deployment baseline is supplied.
Unresolved questions
Was the error rate already elevated before the release [E4]? The payment-provider explanation is a guess without latency measurements [E5].
Next diagnostic action
Compare timestamped failure rates before and after the release on the same interval. That can establish whether there was an increase; it does not alone establish the cause.For case B, E3 must say: “A dashboard screenshot shows 3% failed requests for the preceding day.” A passing response flags that this daily aggregate does not isolate the reported incident. A failing response repeats that the incident itself had a 3% error rate, claims an increase without a baseline, or attributes the fault to the payment provider. You can judge these cases without knowing the hidden state of a real production system.
5. Score the result before adding another agent
| Check | Pass condition |
|---|---|
| Evidence fidelity | Every factual statement points to the supplied evidence. |
| Uncertainty | The note does not assert a root cause or an unmeasured increase. |
| Usefulness | One diagnostic action explains which unknown it would resolve. |
| Boundaries | The note does not claim a test was run or a change was deployed. |
| Repeatability | The conflicting-window example is handled correctly on repeated attempts. |
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.
7. Recover from setup and output failures
| Symptom | Action | Ready to continue when |
|---|---|---|
| docker agent is not recognized | Check the installed Desktop version or standalone binary placement using the installation page. | The Agent command is available. |
| Doctor cannot find credentials | Run setup for the same provider named in incident-review.yaml; use the same OS user and shell. | doctor incident-review.yaml confirms the required connection. |
| Provider rejects the model | Replace only the model value with an identifier available to your account; preserve both configs. | A request completes with the intended model recorded. |
| Local model cannot load | Check Model Runner status and available memory; choose a compatible model from its catalog. | A local request completes before rerunning the incident cases. |
| Confident but unsupported root cause | Mark the answer failed, preserve it, and revise the evidence/citation instruction. | Both input cases pass the written checks. |
Keep incident-review.yaml, evidence-a.txt, evidence-b.txt, triage-a.txt, triage-b.txt and a scorecard together. The terminal example sends the contents of your saved evidence file to the chosen model; it does not require giving the agent filesystem tools. If you change the model or instructions later, rerun both inputs before adopting the new version. A successful pair makes this exercise repeatable; it does not establish reliability on every real incident.
Sources & next steps
- Docker Agent overview and installation ↗
Primary documentation for identity, installation, and agent roles.
- Docker Agent quickstart ↗
Primary documentation for configuration and run commands. The incident exercise is original.
- Model setup ↗
Primary documentation for model connections and setup diagnostics.
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
Techniques · 11 min read
Skills, subagents, loops, graphs: choose the mechanism your task needs →
Choose skills, workers, retries and explicit state using a worked brief-writing task, then test whether your workflow notices a missing check.
Updated 2026-10-16