Merge pull request #24284 from dvdksn/disambiguate-agents

dvdksn · web-flow · commit 6f9c8c272b10 · 2026-03-06T13:19:15.000+01:00
ai: Disambiguate Docker Agent, Gordon, and Docker Sandboxes
diff --git a/content/guides/agentic-ai.md b/content/guides/agentic-ai.md
@@ -12,8 +12,8 @@ params:
 > [!TIP]
 >
 > This guide uses the familiar Docker Compose workflow to orchestrate agentic AI
-> applications. For a smoother development experience, check out [Docker
-> Docker Agent](../manuals/ai/docker-agent/_index.md), a purpose-built agent runtime that
+> applications. For a smoother development experience, check out
+> [Docker Agent](../manuals/ai/docker-agent/_index.md), a purpose-built agent runtime that
 > simplifies running and managing AI agents.
 
 ## Introduction
@@ -65,11 +65,11 @@ all works together.
 
 To follow this guide, you need to:
 
- - [Install Docker Desktop 4.43 or later](../get-started/get-docker.md)
- - [Enable Docker Model Runner](/manuals/ai/model-runner.md#enable-dmr-in-docker-desktop)
- - At least the following hardware specifications:
-    - VRAM: 3.5 GB
-    - Storage: 2.31 GB
+- [Install Docker Desktop 4.43 or later](../get-started/get-docker.md)
+- [Enable Docker Model Runner](/manuals/ai/model-runner.md#enable-dmr-in-docker-desktop)
+- At least the following hardware specifications:
+  - VRAM: 3.5 GB
+  - Storage: 2.31 GB
 
 ## Step 1: Clone the sample application
 
@@ -90,8 +90,9 @@ run in the cloud. This particular example uses the [Gemma 3 4B
 model](https://hub.docker.com/r/ai/gemma3) with a context size of `10000`.
 
 Hardware requirements:
- - VRAM: 3.5 GB
- - Storage: 2.31 GB
+
+- VRAM: 3.5 GB
+- Storage: 2.31 GB
 
 If your machine exceeds those requirements, consider running the application with a larger
 context size or a larger model to improve the agents performance. You can easily
@@ -113,7 +114,7 @@ To run the application locally, follow these steps:
    incorrect fact in the prompt and hit enter. An agent searches DuckDuckGo to
    verify it and another agent revises the output.
 
-    ![Screenshot of the application](./images/agentic-ai-app.png)
+   ![Screenshot of the application](./images/agentic-ai-app.png)
 
 3. Press ctrl-c in the terminal to stop the application when you're done.
 
@@ -136,7 +137,7 @@ services:
     depends_on:
       - mcp-gateway
     models:
-      gemma3 :
+      gemma3:
         endpoint_var: MODEL_RUNNER_URL
         model_var: MODEL_RUNNER_MODEL
 
@@ -160,16 +161,16 @@ models:
 
 The app consists of three main components:
 
- - The `adk` service, which is the web application that runs the agentic AI
-   application. This service talks to the MCP gateway and model.
- - The `mcp-gateway` service, which is the MCP gateway that connects the app
-   to external tools and services.
- - The `models` block, which defines the model to use with the application.
+- The `adk` service, which is the web application that runs the agentic AI
+  application. This service talks to the MCP gateway and model.
+- The `mcp-gateway` service, which is the MCP gateway that connects the app
+  to external tools and services.
+- The `models` block, which defines the model to use with the application.
 
 When you examine the `compose.yaml` file, you'll notice two notable elements for the model:
 
- - A service‑level `models` block in the `adk` service
- - A top-level `models` block
+- A service‑level `models` block in the `adk` service
+- A top-level `models` block
 
 These two blocks together let Docker Compose automatically start and connect
 your ADK web app to the specified LLM.
@@ -189,7 +190,7 @@ example, it uses the [`duckduckgo` MCP
 server](https://hub.docker.com/mcp/server/duckduckgo/overview) to perform web
 searches.
 
->  [!TIP]
+> [!TIP]
 >
 > Looking for more MCP servers to use? Check out the [Docker MCP
 > Catalog](https://hub.docker.com/catalogs/mcp/).
diff --git a/content/manuals/ai-overview.md b/content/manuals/ai-overview.md
@@ -0,0 +1,46 @@
+---
+title: Docker AI overview
+linkTitle: Overview
+description: Docker's AI tools help you build, run, and manage AI-powered applications and workflows.
+weight: 1
+keywords: docker, ai, gordon, docker agent, sandboxes, model runner, mcp
+params:
+  sidebar:
+    group: AI
+---
+
+Docker provides tools for working with AI across your development workflow.
+Each tool serves a different purpose.
+
+## Which tool do I need?
+
+| I want to...                                                    | Use                                                      | CLI command      |
+| --------------------------------------------------------------- | -------------------------------------------------------- | ---------------- |
+| Get AI help with Docker tasks (containers, images, Dockerfiles) | [Gordon](./ai/gordon/)                                   | `docker ai`      |
+| Run AI models locally with an OpenAI-compatible API             | [Model Runner](./ai/model-runner/)                       | `docker model`   |
+| Connect AI tools to external services via MCP                   | [MCP Catalog and Toolkit](./ai/mcp-catalog-and-toolkit/) | `docker mcp`     |
+| Build and orchestrate custom multi-agent teams                  | [Docker Agent](./ai/docker-agent/)                       | `docker agent`   |
+| Run coding agents in isolated environments                      | [Docker Sandboxes](./ai/sandboxes/)                      | `docker sandbox` |
+
+## How these tools relate
+
+**Gordon** is Docker's built-in AI assistant. It helps with Docker-specific
+tasks like debugging containers, writing Dockerfiles, and managing images. You
+interact with it through Docker Desktop or the `docker ai` command.
+
+**Docker Agent** is an open-source framework for defining teams of AI agents
+in YAML. You configure agents with specific roles, models, and tools, then
+run them from your terminal. Docker Agent is a general-purpose agent runtime,
+not specific to Docker tasks.
+
+**Docker Sandboxes** provides isolated microVM environments for running coding
+agents. It supports multiple agents including Claude Code, Codex, Copilot,
+Gemini, and Docker Agent. Sandboxes is the isolation layer — the agents
+themselves are separate tools.
+
+**Model Runner** lets you run LLMs locally. Other tools like Docker Agent can
+use Model Runner as a model provider.
+
+**MCP Catalog and Toolkit** manages connections between AI tools and external
+services using the Model Context Protocol. Gordon, Docker Agent, and
+third-party tools can all use MCP servers configured through the Toolkit.
diff --git a/content/manuals/ai/docker-agent/_index.md b/content/manuals/ai/docker-agent/_index.md
@@ -16,10 +16,15 @@ keywords: [ai, agent, docker agent, cagent]
 
 {{< summary-bar feature_name="Docker Agent" >}}
 
-[Docker Agent](https://github.com/docker/cagent) is an open source tool for building
-teams of specialized AI agents. Instead of prompting one generalist model, you
-define agents with specific roles and instructions that collaborate to solve
-problems. Run these agent teams from your terminal using any LLM provider.
+[Docker Agent](https://github.com/docker/cagent) is an open-source framework
+for building teams of specialized AI agents. Instead of prompting one
+generalist model, you define agents with specific roles and instructions that
+collaborate to solve problems. Run these agent teams from your terminal using
+any LLM provider.
+
+> [!NOTE]
+> Docker Agent is a framework for building and running custom agent teams.
+> For Docker's built-in AI assistant, see [Gordon](/ai/gordon/) (`docker ai`).
 
 ## Why agent teams
 
diff --git a/content/manuals/ai/gordon/_index.md b/content/manuals/ai/gordon/_index.md
@@ -1,6 +1,7 @@
 ---
 title: Gordon
-description: AI agent for Docker workflows - execute tasks, debug issues, and
+description:
+  AI assistant for Docker workflows - execute tasks, debug issues, and
   manage containers with intelligent assistance
 weight: 40
 params:
@@ -15,7 +16,7 @@ aliases:
 
 {{< summary-bar feature_name="Gordon" >}}
 
-Gordon is an AI agent that takes action on your Docker workflows. It analyzes
+Gordon is an AI-powered assistant that takes action on your Docker workflows. It analyzes
 your environment, proposes solutions, and executes commands with your
 permission. Available in Docker Desktop and via the `docker ai` CLI command.
 
diff --git a/content/manuals/ai/gordon/concepts/capabilities.md b/content/manuals/ai/gordon/concepts/capabilities.md
@@ -14,13 +14,13 @@ explains what Gordon can do and the tools it uses.
 
 Gordon uses five capabilities to take action on your behalf:
 
-- Specialized agents for specific Docker tasks
+- Specialized sub-agents for specific Docker tasks
 - Shell access to run commands
 - Filesystem access to read and write files
 - Knowledge base of Docker documentation and best practices
 - Web access to fetch external resources
 
-## Agent architecture
+## Internal architecture
 
 Gordon uses a primary agent that handles most tasks, with a specialized
 sub-agent for specific workflows:
diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md
@@ -1,6 +1,6 @@
 ---
 title: Docker Sandboxes
-description: Run AI agents in isolated environments
+description: Run AI coding agents in isolated environments
 weight: 20
 params:
   sidebar:
@@ -91,7 +91,7 @@ Docker Sandboxes works with multiple AI coding agents:
 - **Copilot** - GitHub Copilot agent (in development)
 - **Gemini** - Google's Gemini agent (in development)
 - **OpenCode** - Multi-provider agent with TUI interface (in development)
-- **Docker Agent** - Docker's multi-provider coding agent (in development)
+- **[Docker Agent](/ai/docker-agent/)** - Docker's multi-provider coding agent (in development)
 - **Kiro** - Interactive agent with device flow auth (in development)
 - **Shell** - Minimal sandbox for manual agent installation
 
diff --git a/content/manuals/ai/sandboxes/agents/_index.md b/content/manuals/ai/sandboxes/agents/_index.md
@@ -12,16 +12,16 @@ inside microVMs with private Docker daemons.
 
 ## Supported agents
 
-| Agent       | Command    | Status       | Notes                                     |
-| ----------- | ---------- | ------------ | ----------------------------------------- |
-| Claude Code | `claude`   | Experimental | Most tested implementation                |
-| Codex       | `codex`    | Experimental | In development                            |
-| Copilot     | `copilot`  | Experimental | In development                            |
-| Gemini      | `gemini`   | Experimental | In development                            |
-| Docker Agent | `cagent`   | Experimental | In development                            |
-| Kiro        | `kiro`     | Experimental | In development                            |
-| OpenCode    | `opencode` | Experimental | In development                            |
-| Custom shell | `shell`   | Experimental | Minimal environment for manual setup      |
+| Agent                             | Command    | Status       | Notes                                |
+| --------------------------------- | ---------- | ------------ | ------------------------------------ |
+| Claude Code                       | `claude`   | Experimental | Most tested implementation           |
+| Codex                             | `codex`    | Experimental | In development                       |
+| Copilot                           | `copilot`  | Experimental | In development                       |
+| Gemini                            | `gemini`   | Experimental | In development                       |
+| [Docker Agent](/ai/docker-agent/) | `cagent`   | Experimental | Also available as a standalone tool  |
+| Kiro                              | `kiro`     | Experimental | In development                       |
+| OpenCode                          | `opencode` | Experimental | In development                       |
+| Custom shell                      | `shell`    | Experimental | Minimal environment for manual setup |
 
 ## Experimental status
 
@@ -67,7 +67,7 @@ agent (no fallback authentication methods are used).
 See the agent-specific documentation:
 
 - [Claude Code](./claude-code.md)
-- [cagent](./cagent.md)
+- [Docker Agent](./docker-agent.md)
 - [Codex](./codex.md)
 - [Copilot](./copilot.md)
 - [Gemini](./gemini.md)
diff --git a/content/manuals/ai/sandboxes/agents/docker-agent.md b/content/manuals/ai/sandboxes/agents/docker-agent.md
@@ -3,15 +3,19 @@ title: Docker Agent sandbox
 description: |
   Use Docker Agent in Docker Sandboxes with multi-provider authentication
   supporting OpenAI, Anthropic, and more.
-keywords: docker, sandboxes, docker agent, ai agent, multi-provider, authentication
+keywords: docker, sandboxes, docker agent, multi-provider, authentication
+aliases:
+  - /ai/sandboxes/agents/cagent/
+  - /manuals/ai/sandboxes/agents/cagent/
 weight: 60
 ---
 
 {{< summary-bar feature_name="Docker Sandboxes" >}}
 
-This guide covers authentication, configuration, and usage of Docker Agent in
-a sandboxed environment. [Docker Agent](/ai/docker-agent/) is Docker's open source coding
-agent that supports multiple providers.
+This page covers running [Docker Agent](/ai/docker-agent/) inside Docker
+Sandboxes. Docker Agent is also available as a standalone CLI tool. See the
+full documentation for standalone usage, configuration reference, and building
+agent teams.
 
 ## Quick start
 
