Configuration Overview

cagent uses YAML configuration files to define agents, models, tools, and their relationships.

File Structure

A cagent YAML config has these main sections:

# 1. Version — configuration schema version (optional but recommended)
version: 5

# 2. Metadata — optional agent metadata for distribution
metadata:
  author: my-org
  description: My helpful agent
  version: "1.0.0"

# 3. Models — define AI models with their parameters
models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-0
    max_tokens: 64000

# 4. Agents — define AI agents with their behavior
agents:
  root:
    model: claude
    description: A helpful assistant
    instruction: You are helpful.
    toolsets:
      - type: think

# 5. RAG — define retrieval-augmented generation sources (optional)
rag:
  docs:
    docs: ["./docs"]
    strategies:
      - type: chunked-embeddings
        model: openai/text-embedding-3-small

# 6. Providers — optional custom provider definitions
providers:
  my_provider:
    api_type: openai_chatcompletions
    base_url: https://api.example.com/v1
    token_key: MY_API_KEY

# 7. Permissions — global tool permission rules (optional)
permissions:
  allow: ["read_*"]
  deny: ["shell:cmd=sudo*"]

Minimal Config

The simplest possible configuration — a single agent with an inline model:

agents:
  root:
    model: openai/gpt-4o
    description: A helpful assistant
    instruction: You are a helpful assistant.

Inline vs Named Models

Models can be referenced inline or defined in the models section:

model: openai/gpt-4o

model: my_claude

Config Sections

Advanced Configuration

Environment Variables

API keys and secrets are read from environment variables — never stored in config files:

Validation

cagent validates your configuration at startup:

• All sub_agents must reference agents defined in the config
• Named model references must exist in the models section
• Provider names must be valid (openai, anthropic, google, dmr, etc.)
• Required environment variables (API keys) must be set
• Tool-specific fields are validated (e.g., path is only valid for memory)

JSON Schema

For editor autocompletion and validation, use the cagent JSON Schema. Add this to the top of your YAML file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/docker/cagent/main/agent-schema.json

Config Versioning

cagent configs are versioned. The current version is 5. Add the version at the top of your config:

version: 5

agents:
  root:
    model: openai/gpt-4o
    # ...

When you load an older config, cagent automatically migrates it to the latest schema. It’s recommended to include the version to ensure consistent behavior.

Metadata Section

Optional metadata for agent distribution via OCI registries:

metadata:
  author: my-org
  license: Apache-2.0
  description: A helpful coding assistant
  readme: | # Displayed in registries
    This agent helps with coding tasks.
  version: "1.0.0"

See Agent Distribution for publishing agents to registries.

Custom Providers Section

Define reusable provider configurations for custom or self-hosted endpoints:

providers:
  azure:
    api_type: openai_chatcompletions
    base_url: https://my-resource.openai.azure.com/openai/deployments/gpt-4o
    token_key: AZURE_OPENAI_API_KEY

  internal_llm:
    api_type: openai_chatcompletions
    base_url: https://llm.internal.company.com/v1
    token_key: INTERNAL_API_KEY

models:
  azure_gpt:
    provider: azure # References the custom provider
    model: gpt-4o

agents:
  root:
    model: azure_gpt

See Custom Providers for more details.