Docker Agent: Container Workflows Come to AI Agents

By Prahlad Menon 3 min read

Docker changed how we think about application deployment. Define your app in a Dockerfile, build an image, push to a registry, pull and run anywhere. Now they’re bringing that same workflow to AI agents.

What is Docker Agent?

Docker Agent is an open-source framework for building and running AI agents using declarative YAML configuration. If you have Docker Desktop 4.63 or later, it’s already available as a CLI plugin.

The mental model is familiar: instead of writing agent code, you define agent behavior in YAML. Instead of complex deployment scripts, you push to an OCI registry and pull on any machine. The agent runtime handles the rest.

A Simple Example

Here’s what an agent definition looks like:

agents:
  root:
    model: openai/gpt-5-mini
    description: A helpful AI assistant
    instruction: |
      You are a knowledgeable assistant that helps users with various tasks.
      Be helpful, accurate, and concise in your responses.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo

Run it with:

docker agent run agent.yaml

That’s it. No Python environment to manage. No dependency conflicts. No “works on my machine” issues.

Multi-Agent Teams

The real power emerges with multi-agent orchestration. Instead of one generalist model trying to do everything, you define specialized agents that collaborate:

agents:
  root:
    model: anthropic/claude-sonnet-4
    description: Bug investigator
    instruction: |
      Analyze reported bugs and identify root causes.
      When you understand the issue, delegate to fixer.
    sub_agents:
      - fixer

  fixer:
    model: openai/gpt-5
    description: Code fixer
    instruction: |
      Implement fixes for bugs identified by the investigator.
      Write clean, tested code.

The root agent investigates, then hands off to the fixer. Each agent maintains its own context and stays focused on its specialty. Docker Agent manages the coordination.

MCP Integration

Docker Agent natively supports the Model Context Protocol — the emerging standard for connecting AI models to external tools. You can use any MCP server:

toolsets:
  - type: mcp
    ref: docker:github        # GitHub operations
  - type: mcp
    ref: docker:filesystem    # File system access
  - type: mcp
    ref: docker:postgres      # Database queries

Docker maintains a catalog of MCP servers that you can reference directly. No manual setup required.

Provider Agnostic

Docker Agent works with most major AI providers:

  • OpenAI (GPT-4o, GPT-5, o3)
  • Anthropic (Claude Sonnet, Claude Opus)
  • Google (Gemini)
  • AWS Bedrock
  • Mistral
  • xAI
  • Docker Model Runner (local models)

Switch providers by changing one line in your YAML. Your agent definition stays the same.

Package and Share

Here’s where Docker’s container philosophy really shines. Agent configurations are packaged as OCI artifacts — the same format as container images:

# Push your agent to a registry
docker agent share push ./debugger.yaml myusername/debugger

# Pull and run someone else's agent
docker agent share pull myusername/debugger
docker agent run myusername/debugger

Use Docker Hub, or any OCI-compatible registry. Version your agents like you version your containers. Roll back when something breaks.

Built-in Capabilities

Beyond basic chat, Docker Agent includes:

  • Memory tools — Agents can remember context across conversations
  • Reasoning tools — Think and todo list primitives for complex problem-solving
  • RAG — Built-in retrieval with BM25, embeddings, hybrid search, and reranking
  • Shell and filesystem access — When agents need to actually do things

Why This Matters

The AI agent ecosystem has a packaging problem. Everyone builds agents differently. Sharing them requires sharing code, dependencies, API keys, and tribal knowledge. Deploying them means replicating someone else’s development environment.

Docker Agent addresses this the same way Docker addressed application deployment: standardize the format, abstract the runtime, and let registries handle distribution.

For teams already using Docker workflows, adopting Docker Agent requires no new mental models. Define, build, push, pull, run. The skills transfer.

Getting Started

If you have Docker Desktop 4.63+, you already have it:

# Set an API key
export OPENAI_API_KEY=sk-...

# Run the default agent
docker agent run

# Or try one from the catalog
docker agent run agentcatalog/pirate

# Generate a new agent interactively
docker agent new

Check out the documentation and example configurations for more.

Docker’s bet is that AI agents will follow the same trajectory as applications: from artisanal, hand-crafted deployments to standardized, portable packages. If they’re right, defining agents in YAML and distributing them through registries will feel as natural as docker pull does today.