Customization

Prompts & Customization

Customize Agent Zero's behavior by modifying prompts, creating custom agent profiles, and using dynamic variables for advanced prompt engineering.

Understanding the Prompt System

Agent Zero's behavior is controlled through a flexible prompt system using Markdown files. The system supports variable placeholders, dynamic loaders, and agent-specific overrides.

Core Prompt Files

  • agent.system.main.role.md - Defines the agent's overall role and capabilities
  • agent.system.main.communication.md - Specifies how the agent should communicate
  • agent.system.main.solving.md - Describes the agent's approach to tasks
  • agent.system.main.behaviour.md - Controls dynamic behavior adjustments and rules
  • agent.system.main.environment.md - Defines the runtime environment context
  • agent.system.tools.md - Organizes and calls individual tool prompt files
  • agent.system.tool.*.md - Individual tool prompt files

💡 Key Concept: The agent.system.main.md file acts as a central hub, referencing other prompt files to create the complete system prompt.

Prompt Organization

Default Prompts

Located in /prompts/, serve as the base configuration:

/prompts/
├── agent.system.main.md
├── agent.system.main.role.md
├── agent.system.main.communication.md
├── agent.system.main.solving.md
├── agent.system.main.behaviour.md
├── agent.system.tools.md
└── agent.system.tool.*.md

Custom Prompts (v0.9.7+)

Place overrides in agents/<agent_profile>/prompts/:

  1. Create or clone an existing agent profile under agents/<agent_profile>/
  2. Add only the prompt files you want to override in agents/<agent_profile>/prompts/
  3. Agent Zero merges these overrides with the default prompts automatically
  4. Select the Agent Profile in Settings to activate the overrides

💡 Benefit: You only need to override specific prompts while inheriting the rest of the default behavior.

Variable Placeholders

Prompts can include variables using the {{'{{'}}var{{'}}'}} syntax. These variables are replaced with actual values when the prompt is processed.

Example Usage

# Current system date and time of user
- current datetime: {{'{{'}}date_time{{'}}'}}
- rely on this info always up to date

# Agent Information
- agent name: {{'{{'}}agent_name{{'}}'}}
- agent number: {{'{{'}}number{{'}}'}}

Common Variables

  • {{'{{'}}date_time{{'}}'}} - Current system date and time
  • {{'{{'}}agent_name{{'}}'}} - Name of the current agent
  • {{'{{'}}number{{'}}'}} - Agent number in hierarchy
  • {{'{{'}}tools{{'}}'}} - Available tools list
  • {{'{{'}}memory{{'}}'}} - Retrieved memory context

Dynamic Behavior System

Real-Time Behavior Adjustment

Agents can modify their behavior in real-time based on user instructions:

  • Behavior changes are automatically integrated into the system prompt
  • Behavioral rules are merged intelligently, avoiding duplicates and conflicts
  • Changes are applied without disrupting other components

Example:

User: "Please respond in UK English from now on"
Agent: Uses behavior_adjustment tool to add this rule
Result: All future responses follow UK English conventions

How It Works

  1. User requests behavior changes
  2. System identifies behavioral instructions in conversation
  3. New rules are merged with existing ruleset
  4. Updated behavior is immediately applied
  5. Custom rules stored in agent's memory directory as behaviour.md

💡 Note: Behavior rules are injected at the start of the system prompt and maintain separation between core functionality and behavioral rules.

Creating Custom Agent Profiles

Profile Structure

/agents/
└── my_custom_agent/
    ├── prompts/
    │   ├── agent.system.main.role.md
    │   ├── agent.system.main.communication.md
    │   └── agent.system.tool.*.md
    ├── tools/
    │   └── custom_tool.py
    └── extensions/
        └── agent_init/
            └── custom_extension.py

Creating a Profile

  1. Create a new directory under /agents/
  2. Add only the components you want to customize
  3. Agent Zero automatically merges with defaults
  4. Select your profile in Settings → Agent Configuration

💡 Tip: Start by cloning the _example agent profile and modifying it to your needs.

Best Practices

Prompt Engineering

  • Be specific: Clear instructions lead to better agent behavior
  • Use examples: Show desired output formats
  • Define constraints: Specify what the agent should and shouldn't do
  • Test iteratively: Adjust prompts based on actual agent responses
  • Keep it organized: Use markdown headers for structure

Agent Profiles

  • Create profiles for different use cases (coding, research, automation)
  • Override only what's necessary - inherit the rest
  • Document profile purpose and differences from default
  • Version control your custom profiles

Maintenance

  • Keep prompts updated as Agent Zero evolves
  • Test after framework updates
  • Balance customization with maintainability
  • Use Projects for task-specific instructions instead of global prompt changes

Need Help?

Questions about prompt customization? Reach out to the community!