An open-source plugin simplifies the creation of portable AI agents

An open-source plugin transforms the creation of AI agents into a declarative, executable, and shareable exercise like a container. Docker Agent combines multi-provider support, orchestration of agent teams, and configuration validation against an official schema.

Schema-controlled configurations and isolated tool execution

Agent configurations can be validated against the project's official schema using a validator built directly on the agent-schema.json file from the docker/docker-agent repository. This Python validator relies on yaml, json, and jsonschema. It correctly fails when faced with a deliberately invalid configuration that includes a non-existent tool type, confirming the robustness of the control. An example configuration integrating an MCP DuckDuckGo server via "ref: docker:duckduckgo" has been properly validated against this schema. The recommended execution of MCP servers in their own container enhances default isolation, with the option to run them locally, remotely, or in a container as needed.

Delegation between agents and choosing the best model by role

Docker Agent manages teams of specialized agents capable of delegating tasks. The "sub_agents" directive transforms isolated agents into a coordinated team and activates the built-in "transfer_task" tool without additional configuration. When called, "transfer_task" launches a dedicated sub-session for the targeted agent, waits for its result, and then returns it to the coordinator. This approach differs from the "transfers" option, which transfers the entire conversation and control, more suited for pipelines. In a content scenario, a coordinator delegates research to a research agent, passes the result to a writer, and then validates the final output. Each role can rely on a different model, for example, Claude for the coordinator and writer, and GPT-5 for the researcher. The ability to select the most relevant model for each function is part of the design goals. The writer may also have file access, and the researcher can formalize sourced summaries.

Portability, declarative formats, and provider compatibility

Agents express themselves in YAML or HCL, with a normalized model field in the format provider/model-name. The runtime is compatible with services such as OpenAI, Anthropic, Gemini, AWS Bedrock, Mistral, xAI, as well as local models via Docker Model Runner. Tools can be integrated or provided by MCP servers, executable locally, remotely, or in containers. Published agents are distributed via OCI registries, like Docker images, facilitating sharing and reuse in heterogeneous environments.

The plugin installs via Docker Desktop or Homebrew depending on the environment

To get started, Docker must be operational and access to at least one model is required. On Docker Desktop 4.63 or later, the plugin is already available and can be invoked via "docker agent." Under Homebrew, "brew install docker-agent" installs the executable, usable as "docker-agent" or via a symbolic link to "~/.docker/cli-plugins/docker-agent" to use it as a sub-command. An alternative is to download a binary from GitHub Releases and create an identical symbolic link. The command "docker agent --help" should return the list of sub-commands as a quick check.

Define a minimal agent and run it interactively or as a script

A minimal agent fits in an agent.yaml file and must declare an entry point named exactly "root." The runtime relies on the description to identify the agent, while the instruction defines the expected behavior in natural language. The toolsets section exposes capabilities, such as access to the file system or command execution, and a think field can structure reasoning before action. An example can target "anthropic/claude-sonnet-4-5" via the provider/model format. On the execution side, "docker agent run agent.yaml" opens an interactive session, while "--exec" sends a single instruction and then exits, a form suitable for calling from scripts or CI.

Access to models and memory and web tooling

Access to a model can be done via an API key provided as an environment variable, such as ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY, or by locally executing a model via Docker Model Runner to avoid any cloud dependency. Agents can have persistent memory, for example, a file "./research.db," to retain facts over exchanges. For web exploration, an MCP server such as DuckDuckGo can be referenced via "docker:duckduckgo" to be launched in an isolated container. The whole setup fits within an ecosystem of integrated tools or via MCP servers, while remaining compatible with a wide range of providers and local models.

Genesis of the project and early community indicators

Docker laid the groundwork in 2025 by extending Compose to agents and AI models, and launching Model Runner for local model execution. Docker Agent brings these foundations together into a dedicated tool rather than a simple extension of Compose. In terms of maturity, the Go module has tagged versions since March 2026, while the GitHub repository boasts over 3,300 stars and approaches 10,000 commits.