Architecture

Key Concepts

• Creating Sub-Agents: Agents can create subordinate agents to delegate sub-tasks, helping manage complexity and distribute workload
• Communication: Agents can communicate with each other, sharing information and coordinating actions through the message system
• Hierarchy: Agent Zero uses a hierarchical structure with superior agents delegating tasks to subordinates for structured problem-solving

The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordinate agents, which can further delegate to other agents. Each agent can utilize tools and access shared assets (prompts, memory, knowledge, extensions, and skills) to perform its tasks.

Communication Flow

Communication flows between agents through messages structured according to prompt templates. Messages typically include:

• Thoughts: The agent's Chain of Thought and planning process
• Tool name: The specific tool used by the agent
• Responses or queries: Results, feedback, or queries from tools or other agents

Typical Interaction Flow

1. The user provides an instruction to Agent 0
2. Agent 0 initializes VectorDB and accesses memory
3. Agent 0 analyzes the instruction and formulates a plan using thoughts, possibly involving tools or sub-agents
4. If necessary, Agent 0 delegates sub-tasks to subordinate agents
5. Subordinate agents use tools to perform actions, providing arguments and responses
6. Agents communicate results and feedback back up the hierarchy
7. Agent 0 provides the final response to the user

Agents use the call_subordinate tool to delegate tasks to subordinate agents. This is Agent Zero's primary mechanism for task decomposition.

How It Works

1. Agent 0 identifies a sub-task that can be delegated
2. Uses call_subordinate tool with specific instructions
3. A new subordinate agent is spawned with its own context
4. Subordinate agent executes the task using available tools
5. Results are communicated back to the parent agent
6. Parent agent integrates results into its overall solution

Agent 0: "I need to analyze a large dataset and generate visualizations"
↓ delegates to →
Subordinate 1: "Analyze the dataset and extract key metrics"
Subordinate 2: "Generate charts and visualizations from the metrics"
↓ results flow back to →
Agent 0: Combines results into final report

What Are Agent Profiles?

Agent profiles are custom configurations located in /agents/<agent_profile>/ that modify how agents behave. They can override:

• Prompts: Customize system prompts and communication style
• Tools: Add custom tools or override existing ones
• Extensions: Modify agent lifecycle hooks and behavior
• Sub-agent settings: Control which sub-agents are available (via agents.json)

Profile Structure

/agents/
└── my_custom_agent/
    ├── prompts/                    # Override system prompts
    │   ├── agent.system.main.role.md
    │   ├── agent.system.main.communication.md
    │   └── agent.system.tool.*.md
    ├── tools/                      # Custom or overridden tools
    │   └── custom_tool.py
    ├── extensions/                 # Custom extensions
    │   └── agent_init/
    │       └── custom_extension.py
    └── agents.json                 # Sub-agent configuration

agents.json Configuration

The agents.json file controls which sub-agents are enabled or disabled for a specific agent profile. This allows you to customize the available tools and capabilities for subordinate agents.

Example agents.json:

{
  "browser_agent": {
    "enabled": true
  },
  "code_agent": {
    "enabled": true
  },
  "research_agent": {
    "enabled": false
  }
}

When a subordinate agent is created, it inherits the sub-agent configuration from the parent agent's profile, ensuring consistent behavior across the agent hierarchy.

Creating a Custom Agent Profile

1. Create a new directory under /agents/ with your profile name
2. Add only the components you want to customize (prompts, tools, extensions)
3. Create agents.json to configure available sub-agents
4. Select your profile in Settings → Agent Configuration → Agent Profile

Built-in Profiles

Agent Zero includes several pre-configured profiles:

• agent0: Default profile with balanced capabilities
• hacker: Security-focused profile with specialized prompts and tools
• researcher: Optimized for research and information gathering
• _example: Template profile for creating custom configurations

Project-Specific Agent Configuration

When using Projects, each project can have its own agents.json file located in .a0proj/agents.json. This allows project-specific sub-agent configurations:

• Enable/disable specific sub-agents per project
• Different capabilities for different project types
• Isolated sub-agent behavior within project context

Project-level agents.json takes precedence over the agent profile's configuration when a project is active.

Complex Task Decomposition

Break large tasks into specialized sub-tasks:

• Research agent gathers information
• Analysis agent processes data
• Writing agent generates reports
• Review agent validates output

Parallel Processing

Execute independent tasks simultaneously:

• Multiple data sources processed in parallel
• Independent API calls delegated to separate agents
• Concurrent file processing operations
• Results aggregated by parent agent

Specialized Agent Roles

Delegate to agents with specific expertise:

• Coding agent for implementation tasks
• Testing agent for quality assurance
• Documentation agent for writing guides
• DevOps agent for deployment operations