Docker Agent

Docker Agent is a CLI tool that runs AI agents defined in YAML or HCL. It provides several interfaces for interacting with agents:

• TUI: Interactive Terminal User Interface.
• CLI: Headless command-line interface.
• HTTP API: A server for programmatic access.
• MCP server: Model Context Protocol server support.
• A2A: Agent-to-Agent protocol.
• OCI distribution: Ability to package, push, and pull agents from OCI registries like Docker Hub, similar to container images.

Docker Agent supports a variety of AI model providers, ranging from cloud-based APIs to local execution. You can choose a provider based on your needs for reasoning capability, cost, or privacy.

Primary Providers

• OpenAI (openai): Broad model selection and multimodal capabilities.
• Anthropic (anthropic): Strong for coding, analysis, and large context windows.
• Google Gemini (google): Fast inference and competitive pricing.
• AWS Bedrock (amazon-bedrock): Enterprise-grade access to Claude, Nova, Llama, etc.
• Docker Model Runner (dmr): Run models locally via Docker with no API costs or keys required.
• Local Models (ollama or custom): Run Ollama, vLLM, or LocalAI locally.
• Provider Definitions: Allows defining reusable configurations for any provider type.

MCP tool results can include embedded resources like images, PDFs, and text files. Docker Agent automatically captures these as attachments and forwards them to the model as native content blocks:

• Anthropic: Images become image blocks; PDFs/documents become document blocks.
• OpenAI: Images are forwarded as input_image data URIs; PDFs as input_file data URIs.
• Bedrock/Gemini: Receive provider-native representations.

No configuration is required for this behavior.

For advanced orchestration and task management, refer to the following related documentation:

• Multi-Agent Systems: Learn about orchestration patterns for managing multiple agents.
• Background Agents: Learn about parallel task dispatching.
• Hooks: Learn about auditing and policy enforcement.
• Agent Configuration: Access the full agent schema reference.

The Todo Tool allows agents to manage task lists for complex multi-step workflows. It supports creating, updating, and listing tasks with status tracking.

Available Tools:

• create_todo: Create a new task.
• create_todos: Create multiple tasks at once.
• update_todos: Update the status of one or more tasks.
• list_todos: List all current tasks and their statuses.

Task Statuses:

• pending: Task has not been started.
• in-progress: Task is currently being done.
• completed: Task is finished.

Elicitation allows MCP tools to interactively prompt users for information during tool execution. The example server demonstrates several patterns:

• Simple Confirmation (confirm_action): A basic yes/no confirmation dialog.
• Form Input (create_user): Multi-field forms supporting required strings, optional fields, email validation, enums, and booleans.
• Numeric Input (configure_settings): Number fields with minimum and maximum validation and presets.
• Boolean Toggles (setup_preferences): Multiple boolean fields with default values.
• Enum Selection (select_option): Multiple dropdown/choice fields using predefined options.

Tools allow the Docker Agent to interact with external systems (files, shell, web, etc.). The workflow follows these steps:

1. The agent receives a user message.
2. The agent decides it needs a specific tool (e.g., Filesystem to read a file).
3. The Docker Agent runtime executes the tool and returns the result.
4. The agent incorporates the result into its response.

Tool Confirmation Behavior: By default, Docker Agent requires user confirmation before executing tools that have side effects, such as shell commands or file writes. To bypass this and auto-approve all tool calls, use the --yolo flag during execution.

Docker Agent resolves API keys and credentials at runtime through a prioritized chain of providers. The first provider that returns a value is used. The resolution order is:

1. Environment variables: Set in your shell (e.g., export OPENAI_API_KEY=sk-...).
2. Docker Compose secrets: Files mounted under /run/secrets/.
3. Docker Agent env file: The file located at ~/.config/cagent/.env (automatically read).
4. Credential helper: A custom command defined in ~/.config/cagent/config.yaml under credential_helper:.
5. Docker Desktop: Secrets stored by the Docker Desktop backend (automatic for signed-in users).

Note: Older versions used macOS Keychain or pass, but these are no longer supported. Migrate keys to one of the above methods.

To use GitHub Copilot's hosted models (like GPT-4o, Claude, or Gemini) with Docker Agent, you must have an active GitHub Copilot subscription (Individual, Business, or Enterprise) and a Personal Access Token (PAT) with the copilot scope. Export this token as the GITHUB_TOKEN environment variable.

Note: When running evaluations with docker agent eval, the GITHUB_TOKEN is not automatically forwarded to the isolated containers for security reasons. You must pass it explicitly using the -e flag.

export GITHUB_TOKEN="ghp_..."

# When running evaluations, pass the token explicitly:
docker agent eval agent.yaml ./evals -e GITHUB_TOKEN