Don Agent Mode

The Don can be run in "agent mode" to establish a direct connection between Large Language Models (LLMs) and the tools you define in your configuration. This allows for autonomous execution of tasks without requiring a separate MCP client like Cursor or Visual Studio Code.

Overview

In agent mode, Don:

1. Connects directly to an LLM API
2. Makes your tools available to the LLM
3. Manages the conversation flow.
4. Handles tool execution requests
5. Provides the tool results back to the LLM

This creates a complete AI agent that can perform tasks on your system using your defined tools.

Command-Line Options

Run the agent with:

don agent [flags]

Required Flags

• --tools: Path to the tools configuration file (required)
• --model, -m: LLM model to use (e.g., "gpt-4o", "llama3", etc.) - can be omitted if:
  • A default model is configured in your agent configuration, or
  • The DON_AGENT_MODEL environment variable is set

Optional Flags

• --logfile, -l: Path to the log file
• --log-level: Logging level (none, error, info, debug)
• --system-prompt, -s: System prompt for the LLM (merges with system prompts from agent configuration)
• --user-prompt, -u: Initial user prompt for the LLM
• --openai-api-key, -k: OpenAI API key (or set OPENAI_API_KEY environment variable, or configure in agent config)
• --openai-api-url, -b: Base URL for the OpenAI API (for non-OpenAI services, or configure in agent config)
• --once, -o: Exit after receiving a final response (one-shot mode)

💡 Tip: Many settings can be configured via environment variables. See the Environment Variables Reference for a complete list.

Configuration File for Agent Mode

Don has agent-specific configuration that includes model definitions with prompts. The agent configuration by default is a separate from the tools configuration and is managed through the don agent config commands (although it can be embedded in the tools configuration file, it just needs a agent: root element).

The agent configuration file is located at ~/.don/agent.yaml by default, but you can specify a custom location using the DON_AGENT_CONFIG environment variable:

# Use a custom agent configuration file
export DON_AGENT_CONFIG="/path/to/custom/agent.yaml"
don agent --tools=tools.yaml

📖 For complete details on agent configuration, including:

• Configuration file structure and syntax
• Model configuration fields
• Environment variable substitution (including DON_AGENT_CONFIG)
• Configuration management commands
• Example configurations

See the Agent Configuration Guide

Agent Subcommands

agent config - Manage Agent Configuration

See the Agent Configuration Guide for details on the agent config subcommands.

agent info - Display Agent Configuration

The agent info subcommand displays detailed information about the current agent configuration:

don agent info [--tools <tools-file>]

Note: The --tools flag is optional for this command. It's only needed if you want to verify the full agent configuration including tools setup. Without it, the command will display your agent's model configuration, API settings, and prompts.

Flags:

• --json: Output in JSON format (ideal for parsing by other tools)
• --include-prompts: Include the full system prompts in the output
• --check: Test LLM connectivity (exits with error if LLM is not responding)
• --tools: (Optional) Path to tools configuration file

Examples:

Display basic agent configuration (no tools needed):

don agent info

Check LLM connectivity:

don agent --model llama3 info --check

Output in JSON format for parsing:

don agent info --json

Show configuration with full prompts:

don agent --system-prompt "Custom prompt" info --include-prompts

Include tools configuration verification:

don agent info --tools disk-diagnostics-ro.yaml

Override model and show configuration:

don agent --model llama3 info --json

The info command shows:

• Agent configuration file path (typically ~/.don/agent.yaml)
• Orchestrator model (the main planning agent)
• Tool-runner model (the agent that executes tools)
• API configuration (with masked keys)
• System prompts (with --include-prompts)
• LLM connectivity status (with --check)
• Configured tools file (if --tools is provided)

Running the Agent

With the tools defined in disk-diagnostics-ro.yaml, you can run:

don agent \
  --tools disk-diagnostics-ro.yaml \
  "My root partition is running low on space. Can you help me find what's taking up space and how I might free some up?"

The agent will:

• Load model and API settings from ~/.don/agent.yaml (see Agent Configuration Guide). It will look like this:

$ cat ~/.don/agent.yaml
agent:
  models:
    - model: "gpt-4o"
      class: "openai"
      name: "gpt-4o"
      default: true
      api-key: "your-openai-api-key"
      api-url: "https://api.openai.com/v1"

    - name: "claude-sonnet-4"
      class: "amazon-bedrock"
      model: "us.anthropic.claude-sonnet-4-5-20250929-v1:0"
      api-url: "https://bedrock-runtime.us-east-2.amazonaws.com"

    - model: "gemma3n"
      class: "ollama"
      name: "gemma3n"

    - model: "llama3.1:8b"
      class: "ollama"
      name: "llama3"

• Load system prompts from the agent configuration (if any, or use the default ones).
• Load tools from disk-diagnostics-ro.yaml.
• Connect to the configured LLM API.
• Process the LLM's responses and execute tool calls as requested.

You can also use STDIN as part of the prompt by using a - for replacing it, like this:

cat failure.log | don agent \
  --tools kubectl-ro.yaml \
  "I'm seeing this error in the Kubernetes logs" - "Please help me to debug this problem."

When STDIN is used (via -), the agent automatically runs in --once mode since STDIN is no longer available for interactive input.

Interacting with the Agent

In interactive mode (without the --once flag), the agent will:

• Display the LLM's responses
• Execute tool calls as requested by the LLM
• Wait for you to provide additional input after the LLM completes its response
• Continue the conversation with the full conversation context preserved
• Loop until you exit (Ctrl+C)

In one-shot mode (with the --once flag), the agent will:

• Process the initial prompt
• Execute any requested tools
• Display the final response
• Exit automatically after the LLM completes

Testing and Debugging

When developing agents, you can:

1. Enable debug logging with --log-level debug

2. Examine the log file for detailed information

3. Test with the exe command to verify individual tools:

   don exe --tools disk-diagnostics-ro.yaml disk_usage directory="/" max_depth=2