A0 Development

Agent Zero Development Guide

This skill provides comprehensive, accurate guidance for extending and building features for Agent Zero. Use it when you need to:

• Understand the architecture and project layout
• Create new Tools for agent capabilities
• Add Extensions to hook into the framework lifecycle
• Build API Endpoints for the Web UI
• Create Agent Profiles (subordinates) with custom prompts
• Understand and extend the Prompt System
• Create Skills (see the dedicated create-skill skill for the full wizard)
• Work with Projects and workspace configuration

> Path convention: Throughout this guide, /a0/ refers to the framework root — this is /a0/ inside Docker, or your local repository root in development. All paths are relative to this root.

> [!IMPORTANT] > Plugins are the primary way to extend Agent Zero. Most new tools, extensions, and prompts should be packaged as plugins. For all plugin tasks (create, review, manage, debug, contribute), load the a0-plugin-router skill which routes to the appropriate specialist. This guide covers the underlying framework patterns that plugins build upon.

Related skills: a0-plugin-router (plugin tasks) | create-skill (skill creation wizard) | a0-create-plugin | a0-review-plugin | a0-manage-plugin | a0-contribute-plugin | a0-debug-plugin

---

Architecture Overview

Project Layout

/a0/                              # Framework root
├── agent.py                      # Core Agent + AgentContext + AgentConfig classes
├── initialize.py                 # Agent initialization logic
├── models.py                     # Model definitions
├── run_ui.py                     # Web UI entry point
│
├── tools/                        # Core tools (search, response, browser, etc.)
├── extensions/
│   ├── python/                   # Python lifecycle extensions
│   │   ├── /         # e.g., agent_init/, system_prompt/, etc.
│   │   │   └── _NN_name.py       # Numbered extension files
│   │   └── _functions/           # Implicit @extensible decorator extensions
│   └── webui/                    # JavaScript WebUI extensions
│       └── /         # e.g., json_api_call_before/
│           └── name.js
├── api/                          # Flask API endpoint handlers
├── helpers/                      # Framework utilities and base classes
│   ├── tool.py                   # Tool + Response base classes
│   ├── extension.py              # Extension base class + @extensible decorator
│   ├── api.py                    # ApiHandler base class
│   ├── files.py                  # File operations + prompt reading
│   ├── plugins.py                # Plugin system manager
│   ├── print_style.py            # Console output formatting
│   └── ...                       # Many more utility modules
│
├── prompts/                      # Core prompt fragments (system, tools, framework)
├── agents/                       # Agent profiles (subordinate specializations)
│   ├── default/                  # Base profile (inherited by others)
│   ├── agent0/                   # Main user-facing agent
│   ├── developer/                # Developer subordinate
│   ├── hacker/                   # Security subordinate
│   ├── researcher/               # Research subordinate
│   └── _example/                 # Example profile with tool + extension samples
│
├── plugins/                      # Core plugins (tools, extensions, prompts)
│   ├── _code_execution/          # Terminal/Python/Node.js execution
│   ├── _memory/                  # Persistent memory system
│   ├── _text_editor/             # File read/write/patch
│   ├── _model_config/            # LLM model selection
│   ├── _infection_check/         # Prompt injection safety
│   └── ...                       # More core plugins
│
├── skills/                       # Core skills (SKILL.md bundles)
├── knowledge/                    # Knowledge base files
├── webui/                        # Web UI frontend
├── docs/                         # Documentation
│
└── usr/                          # User-space (survives updates)
    ├── agents/                   # User-created agent profiles
    ├── plugins/                  # User-installed plugins
    ├── skills/                   # User-created skills
    ├── knowledge/                # User knowledge base files
    ├── extensions/               # Standalone user extensions (created on demand; prefer plugins instead)
    ├── projects/                 # Project workspaces (created on demand when user adds projects via UI)
    └── workdir/                  # Default working directory

Key Architecture Patterns

1. Plugin-first design — Most capabilities (tools, extensions, prompts) are delivered via plugins in /a0/plugins/ (core) or /a0/usr/plugins/ (user).
2. Extensions execute in numeric order — Files named _10_*.py, _20_*.py, etc. run sequentially within each hook point.
3. Tools inherit from Tool — All tools implement the execute() method returning a Response.
4. Shared AgentContext — Enables state persistence across agents in a conversation.
5. Async/await throughout — All tool execution, extensions, and API handlers are async.
6. Prompt fragments compose — System prompts are assembled from named fragments with includes and variable substitution.
7. Profile inheritance — Agent profiles inherit from default/ and override specific prompt fragments.
8. User-space separation — Everything under /a0/usr/ survives framework updates.

Agent Loop

The core execution cycle works as follows:

1. User message arrives (via UI or API)
2. System prompt assembly — prompt fragments are composed with includes and variable substitution
3. LLM call — the assembled prompt + conversation history is sent to the model
4. Response parsing — the framework parses the LLM response looking for JSON tool calls
5. Tool execution — if tool calls are found, each tool's execute() method is called and the result is appended to history
6. Loop continues — steps 3-5 repeat until the agent produces a response tool call (which ends the loop) or a loop limit is reached

Extensions fire at each stage (e.g., monologue_start, before_main_llm_call, tool_execute_before, etc.), allowing plugins to observe and modify behavior at every point.

---

Creating Tools

Tools are how agents interact with the world. Each tool inherits from the Tool base class.

Import Path

from helpers.tool import Tool, Response

Tool Base Class

# /a0/helpers/tool.py

@dataclass
class Response:
    message: str              # Text response shown to agent
    break_loop: bool          # True = stop agent message loop
    additional: dict[str, Any] | None = None  # Extra metadata for history

class Tool:
    def __init__(self, agent: Agent, name: str, method: str | None,
                 args: dict[str,str], message: str,
                 loop_data: LoopData | None, **kwargs) -> None:
        self.agent = agent
        self.name = name
        self.method = method   # For tools with sub-methods (e.g., "skills_tool:load")
        self.args = args
        self.loop_data = loop_data
        self.message = message

    async def execute(self, **kwargs) -> Response:
        pass  # Override this

    # Lifecycle hooks (called automatically):
    async def before_execution(self, **kwargs): ...
    async def after_execution(self, response: Response, **kwargs): ...

Where Tools Live

| Location | Purpose | |---|---| | /a0/tools/ | Core framework tools (search, response, callsubordinate, etc.) | | /a0/plugins//tools/ | Plugin-provided tools (codeexecution, memory, text_editor) | | /a0/agents//tools/ | Profile-specific tool overrides | | /a0/usr/plugins//tools/ | User plugin tools |

Example: Creating a Tool

Based on the actual _example profile in /a0/agents/_example/tools/example_tool.py:

# my_tool.py
from helpers.tool import Tool, Response

class MyTool(Tool):
    async def execute(self, **kwargs):
        # Get arguments — kwargs contains the tool_args from the agent's JSON
        input_data = kwargs.get("input", "")

        # Do something
        result = f"Processed: {input_data}"

        # Return response
        return Response(
            message=result,        # Shown to the agent
            break_loop=False,      # Don't stop the agent loop
        )

> [!IMPORTANT] > Every tool needs a corresponding prompt fragment so the agent knows how to use it. Create a file named agent.system.tool..md in the appropriate prompts/ directory. See the [Prompt System](#prompt-system) section.

Tool Best Practices

• Always handle errors gracefully — return error messages in Response, don't crash
• Access agent context via self.agent.context
• Use self.method to support sub-methods (e.g., my_tool:action1, my_tool:action2)
• Use kwargs.get() to read arguments with defaults
• For long operations, use self.set_progress() or self.add_progress() to show status
• Access self.loop_data for loop state (iteration count, timing, etc.) — this is the LoopData instance passed during tool dispatch

---

Creating Extensions

Extensions hook into specific lifecycle points in the agent framework.

Import Path

from helpers.extension import Extension

Extension Base Class

class Extension:
    def __init__(self, agent: "Agent | None", **kwargs):
        self.agent: "Agent | None" = agent
        self.kwargs = kwargs

    def execute(self, **kwargs) -> None | Awaitable[None]:
        pass  # Override this — kwargs are hook-point-specific

> Extensions can be sync or async. If execute() returns an Awaitable, the framework will await it automatically. The agent parameter is nullable because some hook points (like startup_migration or banners) fire before an agent exists.

Extension File Location

Extensions live in directories named by their hook point. The path structure is:

extensions/python//_NN_name.py

Where _NN_ is a numeric prefix controlling execution order (e.g., _10_, _20_, _50_).

| Source | Path | |---|---| | Core extensions | /a0/extensions/python// | | Plugin extensions | /a0/plugins//extensions/python// | | User extensions | /a0/usr/extensions/python// | | Agent profile extensions | /a0/agents//extensions// | | User plugin extensions | /a0/usr/plugins//extensions/python// |

Python Extension Hook Points

Complete list of available hook points:

| Hook Point | When It Fires | Common Use | |---|---|---| | agent_init | Agent is initialized | Load configs, set defaults | | system_prompt | System prompt is being assembled | Inject prompt content | | monologue_start | Agent monologue begins | Pre-processing, state setup | | message_loop_start | Before message processing loop | Pre-loop setup | | message_loop_prompts_before | Before prompt assembly in loop | Modify prompt inputs | | message_loop_prompts_after | After prompt assembly in loop | Add context (memory recall lives here) | | before_main_llm_call | Before the LLM API call | Modify prompts, add context | | util_model_call_before | Before utility model calls | Modify utility prompts | | response_stream | When response streaming begins | Initialize stream handlers | | response_stream_chunk | Per response chunk received | Transform output, collect data | | response_stream_end | Response streaming complete | Finalize, analyze full response | | reasoning_stream | Reasoning/thinking stream begins | Monitor reasoning | | reasoning_stream_chunk | Per reasoning chunk | Collect reasoning data | | reasoning_stream_end | Reasoning stream complete | Analyze reasoning | | tool_execute_before | Before a tool runs | Validation, logging, safety checks | | tool_execute_after | After a tool runs | Post-process results | | hist_add_before | Before adding to history | Modify history entries | | hist_add_tool_result | After tool result added to history | Log tool results | | message_loop_end | After message processing loop | Post-loop cleanup | | monologue_end | Agent monologue complete | Memorization, cleanup | | process_chain_end | Entire processing chain done | Final cleanup | | job_loop | Background job loop tick | Periodic background tasks | | error_format | Error is being formatted | Custom error messages | | startup_migration | Framework startup | Data migrations | | banners | Startup banners displayed | Add custom banners | | embedding_model_changed | Embedding model changed | Reload vector stores (fired programmatically, not a directory-based hook) | | user_message_ui | User message from UI | Pre-process user input | | webui_ws_connect | WebSocket client connects | Session setup | | webui_ws_disconnect | WebSocket client disconnects | Session cleanup | | webui_ws_event | WebSocket event received | Handle custom WS events |

The @extensible Decorator (Implicit Extension Points)

Any framework function decorated with @extensible automatically gets two extension points:

_functions///start
_functions///end

The path mapping converts Python module paths and qualified names using / separators:

• Module agent.py → agent
• Class method Agent.handle_exception → Agent/handle_exception
• Full path: _functions/agent/Agent/handle_exception/start

For nested modules like helpers.history, a method History.add would map to _functions/helpers/history/History/add/start.

For example, a function Agent.handle_exception in module agent creates:

• _functions/agent/Agent/handle_exception/start
• _functions/agent/Agent/handle_exception/end

Extensions in these directories receive a data dict with:

• data["args"] — positional args (mutable)
• data["kwargs"] — keyword args (mutable)
• data["result"] — set this to short-circuit the function
• data["exception"] — set to a BaseException to force-raise

This is used by plugins like _error_retry to wrap core agent methods.

WebUI Extensions (JavaScript)

Client-side extensions live under extensions/webui//:

| Hook Point | When It Fires | |---|---| | json_api_call_before | Before a JSON API request | | json_api_call_after | After a JSON API response | | fetch_api_call_before | Before a fetch API request | | fetch_api_call_after | After a fetch API response | | get_message_handler | Register custom message renderers | | set_messages_before_loop | Before messages are rendered | | set_messages_after_loop | After messages are rendered | | webui_ws_push | WebSocket push to client |

Example: Creating an Extension

Based on the actual _example profile in /a0/agents/_example/extensions/agent_init/_10_example_extension.py:

# extensions/python/agent_init/_15_my_extension.py
from helpers.extension import Extension

class MyExtension(Extension):
    async def execute(self, **kwargs):
        # Access the agent
        agent = self.agent
        context = agent.context

        # Extension logic — kwargs content depends on the hook point
        agent.agent_name = "CustomAgent" + str(agent.number)

Extension Execution Order

Extensions execute in numeric order based on filename prefix:

_10_first.py      # Runs first
_20_second.py     # Runs second
_50_third.py      # Runs third

Use 10-number increments to leave room for future extensions.

---

Creating API Endpoints

API endpoints serve the Web UI and external clients using Flask.

Import Path

from helpers.api import ApiHandler
from flask import Request, Response

ApiHandler Base Class

class ApiHandler:
    def __init__(self, app: Flask, thread_lock: ThreadLockType):
        self.app = app
        self.thread_lock = thread_lock

    # Override these class methods to configure behavior:
    @classmethod
    def requires_

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Gen-Verse](https://github.com/Gen-Verse)
- **Source:** [Gen-Verse/PAST-Bench](https://github.com/Gen-Verse/PAST-Bench)
- **License:** Apache-2.0
- **Homepage:** https://arxiv.org/abs/2608.04003

Install and usage instructions live in the source repository linked above.