Development

Extensible Components

• Extensions: Hook into agent lifecycle points to modify behavior
• Tools: Modular components providing specific functionality to agents
• API Endpoints: Expose Agent Zero functionality to external systems
• Helpers: Utility modules providing shared logic across the framework
• Prompts: Instructions and context provided to the LLM

Extension Points

• 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
• message_loop_prompts_after: Executed after prompts are processed
• 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

Extension Mechanism

The extension mechanism works through the call_extensions function:

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 Custom 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

# File: /agents/_example/extensions/agent_init/_10_example_extension.py
from python.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)

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.

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

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

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

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

Location:

• Default endpoints: /python/api/

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

Location:

• Default helpers: /python/helpers/

Prompt Locations

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

Prompt Features

Variable Placeholders:

Prompts can include variables using the {{'{{'}}var{{'}}'}} syntax:

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

Dynamic Variable Loaders:

Create Python files with the same name as your prompt files to generate variables at runtime:

from python.helpers.files import VariablesPlugin
from python.helpers import files

class MyVariablesPlugin(VariablesPlugin):
    async def generate(self):
        # Generate dynamic content
        tools_list = await self.load_tools()
        return {
            "tools": tools_list,
            "custom_var": "custom value"
        }