In the fast-evolving world of artificial intelligence (AI), the year 2025 marks a significant milestone with the introduction of Docker’s innovative tool—Docker cagent. This open-source multi-agent runtime offers a streamlined approach to managing AI agents using a declarative YAML configuration. By doing so, it eliminates the need for traditional tasks like managing Python environments, various SDK versions, and complex orchestration logic. Instead, developers can now simply define the behavior of AI agents in a single configuration file and bring them to life with the command “cagent run”.
In this comprehensive article, we will delve deep into how Docker cagent integrates seamlessly with GitHub Models to achieve true vendor independence. We will walk you through the process of building a practical AI-driven podcast generation agent that utilizes multiple specialized sub-agents. Moreover, we will guide you on how to package and distribute these AI agents using Docker Hub. By the end of this discussion, you will have a clear understanding of how to sidestep vendor lock-in, as well as how to develop AI agent systems that are flexible, cost-effective, and ready for production throughout their lifecycle.
Understanding Docker cagent
Docker cagent is an open-source tool that orchestrates AI agents through a straightforward YAML configuration. This innovation allows developers to bypass the cumbersome task of managing various Python environments and SDK versions. By defining agent behavior in a single configuration file, developers can execute the defined tasks with a simple “cagent run” command.
Key Features of Docker cagent
- Declarative YAML Configuration: This feature allows for single-file agent definitions, which include model configuration, clear instructions, access to tools, and delegation rules for interacting and coordinating with sub-agents.
- Multi-Provider Support: Docker cagent supports several providers including OpenAI, Anthropic, Google Gemini, and Docker Model Runner (DMR) for local inference.
- MCP Integration Support: This feature leverages Model Context Protocol (MCP) to connect external tools and services using protocols like Stdio, HTTP, and SSE.
- Secured Registry Distribution: Developers can package and share agents securely via Docker Hub, utilizing the standard container registry infrastructure.
- Built-In Reasoning Tools: With capabilities such as “think”, “todo”, and “memory”, Docker cagent offers tools designed for complex problem-solving workflows.
The central proposition of Docker cagent is straightforward—developers declare what an agent should accomplish, and the cagent handles the execution. Each agent operates within an isolated context, utilizing specialized tools via MCP and configurable models. Agents can also delegate tasks to sub-agents, forming hierarchical teams that mimic human organizational structures.
Exploring GitHub Models
GitHub Models is a comprehensive suite of developer tools that facilitate the journey from AI concept to deployment. It includes a model catalog, prompt management, and quantitative evaluations. GitHub Models offers users rate-limited free access to production-grade language models from renowned providers such as OpenAI (GPT-4o, GPT-5), Meta (Llama 3.1, Llama 3.2), Microsoft (Phi-3.5), and DeepSeek models.
One of the significant advantages of GitHub Models is its one-time authentication using GitHub Personal Access Tokens. Once authenticated, developers can easily plug and play any model supported by GitHub Models. The platform continues to expand its list of supported models, recently adding Anthropic Claude models.
For a complete list of models supported by GitHub, you can visit the GitHub Marketplace at https://github.com/marketplace.
GitHub has designed its platform, including GitHub Models and GitHub Copilot agents, to support production-level AI workflows. It provides the necessary infrastructure, governance, and integration points to facilitate this.
Configuring Docker cagent with GitHub Models
The OpenAI-compatible API of GitHub Models allows for a straightforward integration with Docker cagent by treating it as a custom OpenAI provider with a modified base URL and authentication.
In this section, we will guide you through creating and deploying a Podcast Generator agent using GitHub models. We will show you how simple it is to deploy and share AI agents by deploying them to the Docker Hub registry. To begin, you will need to create a fine-grained personal access token by visiting GitHub Personal Access Tokens.
Prerequisites
- Docker Desktop 4.49+: Ensure that the MCP Toolkit is enabled.
- GitHub Personal Access Token: This should have model scope permissions.
- cagent Binary: Download it from the Docker cagent GitHub repository and place it in the folder
C:\Dockercagent. Run.\cagent-exe –helpto explore more options.Defining Your Agent
Let’s explore a simple podcast generator agent, which I developed while testing Docker cagent. The purpose of this agent is to generate podcasts by utilizing blogs, articles, and YouTube videos as sources.
Below is the YAML configuration file for the Podcast Generator. It describes a sophisticated multi-agent workflow for automated podcast production, leveraging GitHub Models and MCP tools like DuckDuckGo for external data access. The DuckDuckGo MCP server operates in an isolated Docker container managed by the MCP gateway.
Podcast Generator YAML Configuration
“`yaml
!/usr/bin/env cagent run
agents:
root:
description: "Podcast Director – Orchestrates the entire podcast creation workflow and generates text file"
instruction: |
You are the Podcast Director responsible for coordinating the entire podcast creation process.Your workflow:
- Analyze input requirements (topic, length, style, target audience)
- Delegate research to the research agent which can open duck duck go browser for researching
- Pass the researched information to the scriptwriter for script creation
- Output is generated as a text file which can be saved to file or printed out
- Ensure quality control throughout the process
Always maintain a professional, engaging tone and ensure the final podcast meets broadcast standards.
model: github-model
toolsets:- type: mcp
command: docker
args: ["mcp", "gateway", "run", "–servers=duckduckgo"]
sub_agents: ["researcher", "scriptwriter"]researcher:
model: github-model
description: "Podcast Researcher – Gathers comprehensive information for podcast content"
instruction: |
You are an expert podcast researcher who gathers comprehensive, accurate, and engaging information.Your responsibilities:
- Research the given topic thoroughly using web search
- Find current news, trends, and expert opinions
- Gather supporting statistics, quotes, and examples
- Identify interesting angles and story hooks
- Create detailed research briefs with sources
- Fact-check information for accuracy
Always provide well-sourced, current, and engaging research that will make for compelling podcast content.
toolsets: - type: mcp
command: docker
args: ["mcp", "gateway", "run", "–servers=duckduckgo"]scriptwriter:
model: github-model
description: "Podcast Scriptwriter – Creates engaging, professional podcast scripts"
instruction: |
You are a professional podcast scriptwriter who creates compelling, conversational content.Your expertise:
- Transform research into engaging conversational scripts
- Create natural dialogue and smooth transitions
- Add hooks, sound bite moments, and calls-to-action
- Structure content with clear intro, body, and outro
- Include timing cues and production notes
- Adapt tone for target audience and podcast style
- Create multiple format options (interview, solo, panel discussion)
Write scripts that sound natural when spoken and keep listeners engaged throughout.
toolsets: - type: mcp
command: docker
args: ["mcp", "gateway", "run", "–servers=filesystem"]models:
github-model:
provider: openai
model: openai/gpt-5
base_url: https://models.github.ai/inference
env:
OPENAI_API_KEY: $GITHUB_TOKEN
“`Note: Since we are using the DuckDuckGo MCP server, ensure that you add and install this MCP server from the MCP catalog on your Docker Desktop.
Running Your Agent Locally
To execute your agent from the root folder where your cagent binaries are located, ensure you update your GitHub PAT token and use the following command:
bash<br /> cagent run ./sunnynagavo55_podcastgenerator.yaml<br />Pushing Your Agent as a Docker Image
To share your agent with your team, push it as a Docker image to your preferred registry using the command:
bash<br /> cagent push Sunnynagavo55/Podcastgenerator<br />You can view your published images within your repositories as shown in the following figure.
Pulling Your Agent on a Different Machine
To pull your Docker image agent created by a teammate, use the command:
bash<br /> cagent pull Sunnynagavo55/Podcastgenerator<br />Alternatively, you can run the same agent directly without pulling the image by using:
bash<br /> cagent run Sunnynagavo55/Podcastgenerator<br />Note: The Podcast Generator example agent has been added to the Docker/cagent GitHub repository under the examples folder. You can access it here: Podcast Generator Example.
Conclusion
Traditional AI development processes often tie you to specific providers, requiring separate API keys and multiple billing accounts, while navigating complex vendor-specific SDKs. However, Docker cagent, combined with GitHub Models, revolutionizes this landscape. By merging Docker’s declarative agent framework with GitHub’s unified model marketplace, you achieve true vendor independence. A single GitHub Personal Access Token provides access to models from industry leaders such as OpenAI, Meta, Microsoft, Anthropic, and DeepSeek, removing the hassle of managing various credentials and authentication schemes.
The future of AI development doesn’t involve committing to a single vendor’s ecosystem. Instead, it’s about creating systems that are flexible enough to adapt as new models emerge and business needs evolve. Docker cagent and GitHub Models empower developers with this architectural freedom today.
Why wait? Start building with the robust capabilities of Docker cagent and GitHub Models, and share your innovative stories with the world.
Resources
For more detailed information about Docker cagent, you can explore the product documentation at Docker cagent Documentation.
To dive deeper into cagent, visit the GitHub repository and give it a star to support the community. Let us know what you build using this powerful tool!
This comprehensive guide should empower you to harness the potential of Docker cagent and GitHub Models in your AI projects, ensuring they are vendor-independent, adaptable, and efficient.
- type: mcp
For more Information, Refer to this article.
