Tips & Best Practices

Expert guidance for building effective, efficient, and secure agents.

Configuration Tips

Auto Mode for Quick Start

Don’t have a config file? docker-agent can automatically detect your available API keys and use an appropriate model:

# Automatically uses the best available provider
$ docker agent run

# Provider priority: OpenAI → Anthropic → Google → Mistral → DMR

The special auto model value also works in configs:

agents:
  root:
    model: auto # Uses best available provider
    description: Adaptive assistant
    instruction: You are a helpful assistant.

Environment Variable Interpolation

Commands support JavaScript template literal syntax for environment variables:

agents:
  root:
    model: openai/gpt-4o
    description: Deployment assistant
    instruction: You help with deployments.
    commands:
      # Simple variable
      greet: "Hello ${env.USER}!"

      # With default value
      deploy: "Deploy to ${env.ENV || 'staging'}"

      # Multiple variables
      release: "Release ${env.PROJECT} v${env.VERSION || '1.0.0'}"

Model Aliases Are Auto-Pinned

docker-agent automatically resolves model aliases to their latest pinned versions. This ensures reproducible behavior:

# You write:
model: anthropic/claude-sonnet-4-5

# docker-agent resolves to:
# anthropic/claude-sonnet-4-5-20250929 (or latest available)

To use a specific version, specify it explicitly in your config.

Performance Tips

Defer Tools for Faster Startup

Large MCP toolsets can slow down agent startup. Use defer to load tools on-demand:

agents:
  root:
    model: openai/gpt-4o
    description: Multi-tool assistant
    instruction: You have many tools available.
    toolsets:
      - type: mcp
        ref: docker:github-official
        defer: true
      - type: mcp
        ref: docker:slack
        defer: true
      - type: mcp
        ref: docker:linear
        defer: true

Or defer specific tools within a toolset:

toolsets:
  - type: mcp
    ref: docker:github-official
    defer:
      - "list_issues"
      - "search_repos"
  - type: mcp
    ref: docker:slack
    defer:
      - "list_channels"

Filter MCP Tools

Many MCP servers expose dozens of tools. Filter to only what you need:

toolsets:
  - type: mcp
    ref: docker:github-official
    # Only expose these specific tools
    tools:
      - list_issues
      - create_issue
      - get_pull_request
      - create_pull_request

Fewer tools means faster tool selection and less confusion for the model.

Set max_iterations

Always set max_iterations for agents with powerful tools to prevent infinite loops:

agents:
  developer:
    model: anthropic/claude-sonnet-4-0
    description: Development assistant
    instruction: You are a developer.
    max_iterations: 30 # Reasonable limit for development tasks
    toolsets:
      - type: filesystem
      - type: shell

Typical values: 20-30 for development agents, 10-15 for simple tasks.

Reliability Tips

Use Fallback Models

Configure fallback models for resilience against provider outages or rate limits:

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: Reliable assistant
    instruction: You are a helpful assistant.
    fallback:
      models:
        # Different provider for resilience
        - openai/gpt-4o
        # Cheaper model as last resort
        - openai/gpt-4o-mini
      retries: 2 # Retry 5xx errors twice
      cooldown: 1m # Stick with fallback for 1 min after rate limit

Best practices for fallback chains:

Use different providers for true redundancy
Order by preference (best first)
Include a cheaper/faster model as last resort

Use Think Tool for Non-Reasoning Models

The think tool provides a reasoning scratchpad for models that lack built-in thinking capabilities:

toolsets:
  - type: think # Useful for models without native reasoning

The agent uses it as a scratchpad for planning and decision-making. If your model already supports a thinking budget (e.g., Claude with extended thinking, OpenAI o-series, Gemini with thinking enabled), you don’t need this tool — the model can reason internally.

Security Tips

Use –yolo Mode Carefully

The --yolo flag auto-approves all tool calls without confirmation:

# Auto-approve everything (use with caution!)
$ docker agent run agent.yaml --yolo

When it’s appropriate:

CI/CD pipelines with controlled inputs
Automated testing
Agents with only safe, read-only tools

When to avoid:

Interactive sessions with untested prompts
Agents with shell or filesystem write access
Any situation where unreviewed actions could cause harm

Combine Permissions with Sandbox

For defense in depth, use both permissions and sandbox mode:

agents:
  secure_dev:
    model: anthropic/claude-sonnet-4-0
    description: Secure development assistant
    instruction: You are a secure coding assistant.
    toolsets:
      - type: filesystem
      - type: shell

permissions:
  allow:
    - "read_*"
    - "shell:cmd=go*"
    - "shell:cmd=npm*"
  deny:
    - "shell:cmd=sudo*"
    - "shell:cmd=rm*-rf*"

# Run with sandbox enabled
docker-agent run --sandbox agent.yaml

Set Global Permission Guardrails

Use global permissions in your user config to enforce safety rules across every agent:

# ~/.config/cagent/config.yaml
settings:
  permissions:
    deny:
      - "shell:cmd=sudo*"
      - "shell:cmd=rm*-rf*"
      - "shell:cmd=git push --force*"
    allow:
      - "read_*"
      - "shell:cmd=ls*"
      - "shell:cmd=cat*"

These rules merge with any agent-level permissions. Deny patterns from your global config cannot be overridden by agent configs, so you can trust that dangerous commands stay blocked regardless of which agent you run.

Use Hooks for Audit Logging

Log all tool calls for compliance or debugging:

agents:
  audited:
    model: openai/gpt-4o
    description: Audited assistant
    instruction: You are a helpful assistant.
    hooks:
      post_tool_use:
        - matcher: "*"
          hooks:
            - type: command
              command: "./scripts/audit-log.sh"

Multi-Agent Tips

Handoffs vs Sub-Agents

Understand the difference between sub_agents and handoffs:

sub_agents (transfer_task)

Delegates task to a child in a sub-session, waits for result, then continues. Hierarchical — the parent remains in control.

sub_agents: [researcher, writer]

handoffs (peer-to-peer)

Hands off the entire conversation to another agent in the same session. The active agent switches and sees the full history. Agents can form cycles.

handoffs:
  - specialist
  - summarizer

See Multi-Agent Systems for a detailed comparison.

Give Sub-Agents Clear Descriptions

The root agent uses descriptions to decide which sub-agent to delegate to:

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: Technical lead
    instruction: Delegate to specialists based on the task.
    sub_agents: [frontend, backend, devops]

  frontend:
    model: openai/gpt-4o
    # Good: specific and actionable
    description: |
      Frontend specialist. Handles React, TypeScript, CSS, 
      UI components, and browser-related issues.

  backend:
    model: openai/gpt-4o
    # Good: clear domain boundaries
    description: |
      Backend specialist. Handles APIs, databases, 
      server logic, and Go/Python code.

  devops:
    model: openai/gpt-4o
    description: |
      DevOps specialist. Handles CI/CD, Docker, Kubernetes,
      infrastructure, and deployment pipelines.

Debugging Tips

Enable Debug Logging

Use the --debug flag to see detailed execution logs:

# Default log location: ~/.cagent/cagent.debug.log
$ docker agent run agent.yaml --debug

# Custom log location
$ docker agent run agent.yaml --debug --log-file ./debug.log

Check Token Usage

Use the /cost command during a session to see token consumption:

/cost

Token Usage:
  Input:  12,456 tokens
  Output:  3,789 tokens
  Total:  16,245 tokens

Compact Long Sessions

If a session gets too long, use /compact to summarize and reduce context:

/compact

Session compacted. Summary generated and history trimmed.

More Tips

User-Defined Default Model

Set your preferred default model in ~/.config/cagent/config.yaml:

settings:
  default_model: anthropic/claude-sonnet-4-0

This model is used when you run docker agent run without a config file.

GitHub PR Reviewer Example

Use docker-agent as a GitHub Actions PR reviewer:

# .github/workflows/pr-review.yml
name: PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run docker-agent review
        env:
          ANTHROPIC_API_KEY: $
          GITHUB_TOKEN: $
        run: |
          # Install docker-agent
          curl -fsSL https://get.docker-agent.dev | sh

          # Run the review
          docker agent run --exec reviewer.yaml --yolo \
            "Review PR #$"

With a simple reviewer agent:

# reviewer.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: PR reviewer
    instruction: |
      Review pull requests for code quality, bugs, and security issues.
      Be constructive and specific in your feedback.
    toolsets:
      - type: mcp
        ref: docker:github-official
      - type: think

← Previous Custom Providers Next → Managing Secrets