Extensions Framework

[!NOTE] Agent Zero is built with extensibility in mind. It provides a framework for creating custom extensions, agents, skills, and tools that can be used to enhance the functionality of the framework.

Extensible components

• The Python framework controlling Agent Zero is built as simple as possible, relying on independent smaller and modular scripts for individual tools, API endpoints, system extensions and helper scripts.
• This way individual components can be easily replaced, upgraded or extended.

Here's a summary of the extensible components:

Extensions

Extensions are components that hook into specific points in the agent's lifecycle. They allow you to modify or enhance the behavior of Agent Zero at predefined extension points. The framework uses a plugin-like architecture where extensions are automatically discovered and loaded.

Extension Points

Agent Zero provides several extension points where custom code can be injected:

• agent_init: Executed when an agent is initialized
• before_main_llm_call: Executed before the main LLM call is made
• message_loop_start: Executed at the start of the message processing loop
• message_loop_prompts_before: Executed before prompts are processed in the message loop
• message_loop_prompts_after: Executed after prompts are processed in the message loop
• message_loop_end: Executed at the end of the message processing loop
• monologue_start: Executed at the start of agent monologue
• monologue_end: Executed at the end of agent monologue
• reasoning_stream: Executed when reasoning stream data is received
• response_stream: Executed when response stream data is received
• system_prompt: Executed when system prompts are processed — split into focused extensions (see below)

Extension Mechanism

The extension mechanism in Agent Zero works through the call_extensions function in agent.py, which:

1. Loads default extensions from /python/extensions/{extension_point}/
2. Loads agent-specific extensions from /agents/{agent_profile}/extensions/{extension_point}/
3. Merges them, with agent-specific extensions overriding default ones based on filename
4. Executes each extension in order

Creating Extensions

To create a custom extension:

1. Create a Python class that inherits from the Extension base class
2. Implement the execute method
3. Place the file in the appropriate extension point directory:
   • Default extensions: /python/extensions/{extension_point}/
   • Agent-specific extensions: /agents/{agent_profile}/extensions/{extension_point}/

Example extension:

# File: /agents/_example/extensions/agent_init/_10_example_extension.py
from helpers.extension import Extension

class ExampleExtension(Extension):
    async def execute(self, **kwargs):
        # rename the agent to SuperAgent0
        self.agent.agent_name = "SuperAgent" + str(self.agent.number)

Extension Override Logic

When an extension with the same filename exists in both the default location and an agent-specific location, the agent-specific version takes precedence. This allows for selective overriding of extensions while inheriting the rest of the default behavior.

For example, if both these files exist:

• /python/extensions/agent_init/example.py
• /agents/my_agent/extensions/agent_init/example.py

The version in /agents/my_agent/extensions/agent_init/example.py will be used, completely replacing the default version.

System Prompt Extensions

The system prompt is built by multiple focused extensions in extensions/python/system_prompt/, each handling one concern:

Each extension exposes a top-level build_prompt(agent) function decorated with @extensible, which auto-creates implicit start and end extension folders. Plugins can hook into these to modify the prompt before or after it's built.

The implicit path is composed from the function's full module path and full nested __qualname__ path:

• _functions/<module path>/<qualname path>/start
• _functions/<module path>/<qualname path>/end

For example, a top-level function build_prompt in module extensions.python.system_prompt._10_main_prompt maps to:

• extensions/python/_functions/extensions/python/system_prompt/_10_main_prompt/build_prompt/start/
• extensions/python/_functions/extensions/python/system_prompt/_10_main_prompt/build_prompt/end/

For nested callables, every namespace-like segment is kept. For example, helpers.something -> Outer.Inner.__init__ maps to:

• _functions/helpers/something/Outer/Inner/__init__/start
• _functions/helpers/something/Outer/Inner/__init__/end

This deep directory structure avoids collisions between functions that previously would have been flattened into the same extension point name.

Numbers _10–_14 run before plugin extensions (which start at _15+), ensuring core prompt sections are built first.

Tool prompt collection: _11_tools_prompt.py collects all agent.system.tool.*.md files from the full directory hierarchy via subagents.get_paths. Plugins that need to pass config values to their tool prompts can register per-file kwargs on agent.data["_tool_prompt_kwargs"] from an earlier-numbered extension:

# plugins/my_plugin/extensions/python/system_prompt/_09_my_config.py
class MyConfig(Extension):
    async def execute(self, **kwargs):
        tool_kwargs = self.agent.data.setdefault("_tool_prompt_kwargs", {})
        tool_kwargs["agent.system.tool.my_tool.md"] = {"my_var": "value"}

Tools

Tools are modular components that provide specific functionality to agents. They are invoked by the agent through tool calls in the LLM response. Tools are discovered dynamically and can be extended or overridden.

Tool Structure

Each tool is implemented as a Python class that inherits from the base Tool class. Tools are located in:

• Default tools: /python/tools/
• Agent-specific tools: /agents/{agent_profile}/tools/

Tool Override Logic

When a tool with the same name is requested, Agent Zero first checks for its existence in the agent-specific tools directory. If found, that version is used. If not found, it falls back to the default tools directory.

Example tool override:

# File: /agents/_example/tools/response.py
from helpers.tool import Tool, Response

# example of a tool redefinition
# the original response tool is in python/tools/response.py
# for the example agent this version will be used instead

class ResponseTool(Tool):
    async def execute(self, **kwargs):
        print("Redefined response tool executed")
        return Response(message=self.args["text"] if "text" in self.args else self.args["message"], break_loop=True)

Tool Execution Flow

When a tool is called, it goes through the following lifecycle:

1. Tool initialization
2. before_execution method
3. execute method (main functionality)
4. after_execution method

API Endpoints

API endpoints expose Agent Zero functionality to external systems or the user interface. They are modular and can be extended or replaced.

API endpoints are located in:

• Default endpoints: /python/api/

Each endpoint is a separate Python file that handles a specific API request.

Helpers

Helper modules provide utility functions and shared logic used across the framework. They support the extensibility of other components by providing common functionality.

Helpers are located in:

• Default helpers: /python/helpers/

Prompts

Prompts define the instructions and context provided to the LLM. They are highly extensible and can be customized for different agents.

Prompts are located in:

• Default prompts: /prompts/
• Agent-specific prompts: /agents/{agent_profile}/prompts/

[!NOTE] Since v0.9.7, custom prompts should be placed under agents/<agent_profile>/prompts/ instead of a shared prompts subdirectory.

Prompt Features

Agent Zero's prompt system supports several powerful features:

Variable Placeholders

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

Example:

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

Dynamic Variable Loaders

For more advanced prompt customization, you can create Python files with the same name as your prompt files. These Python files act as dynamic variable loaders that generate variables at runtime.

When a prompt file is processed, Agent Zero automatically looks for a corresponding .py file in the same directory. If found, it uses this Python file to generate dynamic variables for the prompt.

Example: If you have a prompt file agent.system.tools.md, you can create agent.system.tools.py alongside it:

from helpers.files import VariablesPlugin
from helpers import files

class Tools(VariablesPlugin):
    def get_variables(self, file: str, backup_dirs: list[str] | None = None) -> dict[str, Any]:
        # Dynamically collect all tool instruction files
        folder = files.get_abs_path(os.path.dirname(file))
        folders = [folder]
        if backup_dirs:
            folders.extend([files.get_abs_path(d) for d in backup_dirs])
        
        prompt_files = files.get_unique_filenames_in_dirs(folders, "agent.system.tool.*.md")
        
        tools = []
        for prompt_file in prompt_files:
            tool = files.read_file(prompt_file)
            tools.append(tool)
        
        return {"tools": "\n\n".join(tools)}

Then in your agent.system.tools.md prompt file, you can use:

# Available Tools
{{tools}}

This approach allows for highly dynamic prompts that can adapt based on available extensions, configurations, or runtime conditions. See existing examples in the /prompts/ directory for reference implementations.

File Includes

Prompts can include content from other prompt files using the {{ include "path/to/file.md" }} syntax. This allows for modular prompt design and reuse.

Example:

# Agent Zero System Manual

{{ include "agent.system.main.role.md" }}

{{ include "agent.system.main.environment.md" }}

{{ include "agent.system.main.communication.md" }}

Include Original

When overriding a prompt file, you can extend the original instead of replacing it entirely using {{include original}}. This finds the same filename in the next lower-priority directory and includes its content.

Example: Override agents/developer/prompts/agent.system.main.communication.md:

{{include original}}

- always explain your reasoning
- include code snippets in responses

This resolves to: find agent.system.main.communication.md in the next directory up the hierarchy → finds the default in prompts/ → includes it. Result:

## Communication
- be concise
- use markdown formatting
- ask clarifying questions when unsure

- always explain your reasoning
- include code snippets in responses

The override stays small and automatically inherits any future changes to the default file. Works at any level of the hierarchy — if multiple overrides each use {{include original}}, they chain together from highest to lowest priority.

Agent Specifics File

The default agent.system.main.md includes agent.system.main.specifics.md — an empty file by default. Subagent profiles can override just this file to add profile-specific instructions without touching role, communication, or other sections.

Example: agents/developer/prompts/agent.system.main.specifics.md:

## Developer specifics
- always use git branches for new features
- prefer Python 3.12+ syntax
- run tests before committing

Prompt Override Logic

Similar to extensions and tools, prompts follow an override pattern. When the agent reads a prompt, it first checks for its existence in the agent-specific prompts directory. If found, that version is used. If not found, it falls back to the default prompts directory.

Example of a prompt override:

> !!!
> This is an example prompt file redefinition.
> The original file is located at /prompts.
> Only copy and modify files you need to change, others will stay default.
> !!!

## Your role
You are Agent Zero, a sci-fi character from the movie "Agent Zero".

This example overrides the default role definition in /prompts/agent.system.main.role.md with a custom one for a specific agent profile.

Subagent Customization

Agent Zero supports creating specialized subagents with customized behavior. The _example agent in the /agents/_example/ directory demonstrates this pattern.

Creating a Subagent

1. Create a directory in /usr/agents/{agent_profile}/ for user-created profiles, or /agents/{agent_profile}/ only for built-in framework profiles.
2. Override or extend default components by mirroring the structure in the root directories:
   • /usr/agents/{agent_profile}/agent.yaml - required profile metadata
   • /usr/agents/{agent_profile}/extensions/ - custom extensions
   • /usr/agents/{agent_profile}/tools/ - custom tools
   • /usr/agents/{agent_profile}/prompts/ - custom prompts

Model settings are not stored in agent.yaml or profile settings.json. Main, Utility, and Embedding model configuration is handled by the _model_config plugin. For a user-created profile, profile-scoped model settings live at:

/a0/usr/agents/{agent_profile}/plugins/_model_config/config.json

Scoped _model_config/config.json files are selected as a whole, not deep-merged with global settings. If you create one, include a complete effective config with chat_model, utility_model, and embedding_model. See the Agent Profiles guide for details.

Example Subagent Structure

/usr/agents/my-profile/
├── agent.yaml
├── extensions/
│   └── agent_init/
│       └── _10_example_extension.py
├── prompts/
│   └── ...
├── tools/
│   ├── example_tool.py
│   └── response.py
└── plugins/
    └── _model_config/
        └── config.json

In this example:

• _10_example_extension.py is an extension that renames the agent when initialized
• response.py overrides the default response tool with custom behavior
• example_tool.py is a new tool specific to this agent
• plugins/_model_config/config.json optionally gives this profile its own Main, Utility, and Embedding model settings

Projects

Projects provide isolated workspaces for individual chats, keeping prompts, memory, knowledge, files, and secrets scoped to a specific use case.

Projects are ideal for multi-client or multi-domain work because each project can have its own agent/subagents and context windows, preventing context mixing. They are especially powerful when combined with the Tasks scheduler.

Project Location and Structure

• Projects are located under /a0/usr/projects/
• Each project has its own subdirectory, created by users via the UI
• A project can be backed up or restored by copying or downloading its entire directory

Each project directory contains a hidden .a0proj folder with project metadata and configuration:

/a0/usr/projects/{project_name}/
└── .a0proj/
    ├── project.json          # project metadata and settings
    ├── instructions/         # additional prompt/instruction files
    ├── knowledge/            # files to be imported into memory
    ├── memory/               # project-specific memory storage
    ├── plugins/              # project-scoped plugin configuration
    ├── secrets.env           # sensitive variables (secrets)
    └── variables.env         # non-sensitive variables

Behavior When a Project Is Active in a Chat

When a project is activated for a chat:

• The agent is instructed to work inside the project directory
• Project prompts (instructions) from .a0proj/instructions/ are automatically injected into the context window (all text files are imported)
• Memory can be configured as project-specific, meaning:
  • It does not mix with global memory
  • The memory file is stored under .a0proj/memory/
• Files created or modified by the agent are located within the project directory

The .a0proj/knowledge/ folder contains files that are imported into the project’s memory, enabling project-focused knowledge bases.

Secrets and Variables

Each project manages its own configuration values via environment files in .a0proj/:

• secrets.env – sensitive variables, such as API keys or passwords
• variables.env – non-sensitive variables, such as configuration flags or identifiers

These files allow you to keep credentials and configuration tightly scoped to a single project.

Plugin-owned project configuration is stored under .a0proj/plugins/<plugin_name>/. For example, _model_config stores project model settings and project-only presets here:

/a0/usr/projects/{project_name}/.a0proj/plugins/_model_config/config.json
/a0/usr/projects/{project_name}/.a0proj/plugins/_model_config/presets.yaml

The _model_config/presets.yaml file is a plain YAML list:

- name: Research
  chat:
    provider: openrouter
    name: anthropic/claude-sonnet-4.6
  utility:
    provider: openrouter
    name: openai/gpt-5.4-mini

When to Use Projects

Projects are the recommended way to create specialized workflows in Agent Zero when you need to:

• Add specific instructions without affecting global behavior
• Isolate file context, knowledge, and memory for a particular task or client
• Keep passwords and other secrets scoped to a single workspace
• Run multiple independent flows side by side under the same Agent Zero installation

See Usage → Tasks & Scheduling for how to pair projects with scheduled tasks.

Best Practices

• Keep extensions focused on a single responsibility
• Use the appropriate extension point for your functionality
• Leverage existing helpers rather than duplicating functionality
• Test extensions thoroughly to ensure they don't interfere with core functionality
• Document your extensions to make them easier to maintain and share