DOCSEARCHbyAlgolia
Submit Docs

Agent Zero Documentation

repository·main·Indexed 29 days ago

https://github.com/agent0ai/agent-zero

Agent Zero is an open agent framework providing agents with a Dockerized Linux desktop environment (XFCE), a browser with DOM annotation, and tools for live document co-working. Features include a Code Execution plugin for terminal, Python, and Node.js runtimes; a Commands plugin for reusable slash commands; a Chat Branching plugin for independent conversation paths; and a Document Query plugin for parsing and indexing local or remote documents.

Tokens
157.7K
Snippets
152
Records
690
Agent score
97%

What's inside agent0ai-agent-zero

  1. Overview of the Memory Plugin

    main

    The _memory plugin provides Agent Zero with persistent, vector-based memory and knowledge retrieval capabilities. It uses a FAISS-backed vector database to store embeddings, allowing agents to save, recall, and manage long-term knowledge.

    Key Capabilities

    • Persistent Vector Store: Uses FAISS indexes stored in specific memory subdirectories. It tracks embedding metadata to allow for index rebuilding if you change your embedding model.
    • Knowledge Preloading: Automatically loads configured knowledge directories into the vector store upon database initialization.
    • Automatic Conversation Memory: Automatically captures durable preferences, project facts, and recurring constraints from conversations, while filtering out transient action-history fragments to maintain quality.
    • Scoped Storage: Supports multiple memory subdirectories, enabling you to separate memory by context or specific agent scopes.
    • Memory Management: Provides tools and APIs for saving, loading, deleting, and updating memory entries, as well as a dashboard for manual management.

  2. Overview of the Document Query Plugin

    main

    The Document Query Plugin allows agents to load, parse, index, and perform Q&A over both local and remote documents. It features a strategy-pattern parser system that routes files to specific parsers based on MIME types.

    Key capabilities include:

    • Centralized fetching: Fetches local and HTTP(S) resources once with size checks.
    • LiteParse integration: Uses a fast local parsing path for PDFs and images, running in a child process to isolate failures from the Web UI.
    • Adaptive processing: Automatically skips OCR for very long PDFs and increases chunk sizes for very large documents to manage embedding workloads.
    • Bounded execution: Sync parsers are offloaded to asyncio.to_thread and execution is globally capped to prevent resource exhaustion.

  3. Understand the Search Behavior System Prompt

    main

    The behaviour.search.sys.md prompt defines the logic for an assistant responsible for monitoring conversation history between a USER and an AGENT. The assistant's role is to identify commands or preferences expressed by the user that should modify the AGENT's future behavior.

    Workflow

    1. Input: The assistant receives the conversation history.
    2. Analysis: The assistant searches for user commands intended to update the agent's behavior.
    3. Output: The assistant responds with a JSON array of behavioral instructions or an empty array [] if no behavioral updates are found.

    Rules for Instruction Generation

    • Relevance: Only return instructions that impact how the AGENT behaves in the future.
    • Exclusion: Do not return specific work commands (tasks) given to the agent; only return meta-instructions about behavior.
    • Format: The output must be a valid JSON array of strings.

  4. Understand the 'Deep ReSearch' Agent capabilities and methodology

    main

    The 'Deep ReSearch' agent is a specialized autonomous intelligence system designed for high-level academic, scientific, and corporate research. It operates using a hierarchical architecture where it orchestrates subordinate agents to execute complex, multi-step investigative tasks.

    Core Capabilities

    • Corporate Research: Software architecture analysis, business intelligence (competitive/market analysis), data engineering design, and process optimization.
    • Academic & Scientific Research: Literature synthesis (meta-analyses), hypothesis development, statistical analysis, and creative cross-domain synthesis.
    • Data Mining: Pattern recognition, predictive modeling, and insight generation from complex datasets.

    Research Methodology

    1. Deep Dive Analysis: Exhaustive exploration beyond surface-level data.
    2. Cross-Domain Integration: Synthesizing insights from multiple disciplines.
    3. Evidence-Based Conclusions: Grounding findings in verifiable, peer-reviewed sources.
    4. Innovation Focus: Seeking unconventional solutions and novel connections.
    5. Practical Application: Translating theory into implementable strategies.

  5. Understand the role of the browser helper module

    main

    The browser.py helper module serves as the central owner for shared browser helper state used by various browser-facing integrations within Agent Zero. It is a core module that provides reusable framework APIs for browser interactions, including managing state, authentication, and network-related behaviors.

    Key Responsibilities:

    • Managing shared browser helper state.
    • Providing reusable APIs for core code and plugins.
    • Handling browser-related side effects such as filesystem reads/deletions, authentication, and subprocess management.

    Integration Note: When building plugins or integrations that require browser capabilities, look to browser.py for standardized helper functions to ensure consistency with the framework's security and persistence models.

  6. Use Telegram Integration to communicate with Agent Zero

    main

    The Telegram Integration plugin allows you to connect one or more Telegram bots to Agent Zero. Each bot operates independently with its own token, mode (polling or webhook), access control list, and project binding. Users can interact with the agent via Telegram just like the WebUI, including tool use, sub-agents, and file attachments.

    Key Features

    • Per-user sessions: Each user gets a dedicated AgentContext that persists across restarts.
    • Group support: Bots can operate in mention (respond only when @mentioned), all (respond to every message), or off (private only) modes.
    • File exchange: Supports downloading photos, documents, audio, voice, and video into usr/uploads/.
    • Interactive commands: Use Telegram commands to manage your session and agent configuration.

  7. Use the Prompt Include plugin to inject behavioral rules

    main

    The _promptinclude plugin automatically injects persistent behavioral rules and preferences into the system prompt by scanning the workspace for *.promptinclude.md files.

    Key Features

    • Automatic Scanning: Recursively searches the workspace for files matching the *.promptinclude.md pattern.
    • Gitignore Awareness: Respects ignore patterns derived from gitignore-style content to avoid scanning irrelevant files.
    • Token Budgeting: Manages token usage by applying per-file and total token limits. If a file is too large, it is cropped to fit within the remaining budget.
    • Structured Results: Provides the collected content along with file paths, token counts, status, and the number of skipped files.

    Configuration

    Settings for this plugin are located under the agent section in your configuration. It supports both per-project and per-agent configuration.

    To use it, simply create one or more *.promptinclude.md files within your workspace containing the rules or preferences you want the agent to follow.

  8. Manage Agent Zero Workspaces and Context

    main

    Agent Zero uses several concepts to organize work and control agent behavior:

    • Projects: Isolate workspaces, instructions, memory, secrets, knowledge, repositories, and model-preset choices. Use projects to give an agent context specific to a single piece of work (e.g., cloning a Git repo into a project).
    • Skills: Procedures that can be loaded on demand or pinned from the chat input to keep a specific capability active.
    • Agent Profiles: Configuration settings that change the broader working style of the current chat.
    • Model Presets: Named shortcuts for model configurations (e.g., fast, balanced, cheap, local, or high-power) to allow quick switching between different LLM setups.

  9. Understand the 'Master Developer' Agent Role

    main

    The 'Master Developer' is a specialized, high-level persona within Agent Zero designed for complex, large-scale software engineering tasks. It functions as an elite software architect capable of managing the entire development lifecycle, from system design to DevOps and security engineering.

    Key Capabilities

    • Software Architecture: Designing distributed systems, microservices, and serverless patterns.
    • Implementation: Polyglot programming, advanced algorithm design, and writing production-grade, self-documenting code.
    • Lifecycle Management: Driving Agile processes, implementing CI/CD, and managing technical debt.
    • Security & DevOps: Embedding security (auth, encryption, threat modeling) and implementing Infrastructure as Code (IaC).

    Operational Philosophy

    • Direct Execution: As a subordinate agent, it executes code actions and development tasks directly rather than delegating upward.
    • First Principles Thinking: Decomposes complex problems into fundamental truths to build optimal solutions.
    • Production Standards: Every line of code is intended to be ready for enterprise deployment, including error handling and observability.

  10. Use the Text Editor plugin for file operations

    main

    The _text_editor plugin provides an LLM-friendly toolset for agents to interact with text files. It supports reading, writing, and patching files with built-in safety checks to prevent overwriting changes made by other processes.

    Supported Operations

    • Read: Agents can read entire files or specific line ranges. The plugin uses token-aware limits to prevent context overflow and records file metadata to detect if a file becomes stale before a subsequent edit.
    • Write: Agents can write full file contents. The plugin automatically re-reads the file after writing to confirm the operation was successful.
    • Patch: Agents can apply targeted edits using a patch structure. The plugin validates the edit structure and will reject the operation if the file has changed since it was last read (stale-file detection). After patching, the plugin reads back the affected region to confirm the change.

    Configuration

    The plugin can be configured at both the per-project and per-agent levels. Settings are located under the agent section of your configuration.

    Key configuration parameters (defined in default_config.yaml) include:

    • Read limits
    • Token budgets for file operations

  11. Use the Email Integration plugin

    main

    The Email Integration plugin allows you to communicate with Agent Zero via email. It polls configured mailboxes for incoming messages and attachments, and sends replies back using SMTP.

    Supported Protocols

    • IMAP inbox polling
    • Exchange inbox polling
    • SMTP replies

    Key Features

    • Mailbox Polling: Uses UID tracking for IMAP accounts to ensure only new mail is processed after initialization. State is tracked per-handler in usr/email/state.json.
    • Attachment Handling: All downloaded attachments are stored in usr/email/attachments.
    • Thread Routing:
      • Agent Zero can continue an existing chat if a thread ID is found in the email subject.
      • If no direct thread match is found, it uses model-based dispatch to decide whether to start a new chat or continue an existing one.
    • Command Support: When replying within an existing Agent Zero thread, you can use control commands such as /project, /config, and /send.

    Configuration

    Settings for this plugin are located under the external section of your configuration.

    Note: This plugin does not use per-project or per-agent configuration; it is managed at the global/external level.

  12. Use the Infection Check plugin for safety middleware

    main

    The _infection_check plugin acts as a safety middleware that analyzes agent output for prompt injection and suspicious external influence. It intercepts the agent's reasoning and response text, analyzes it using a configurable audit model, and blocks tool execution until the check passes, requests clarification, or terminates the agent.

    Analysis Modes

    ModeWhat is AnalyzedWhen Analysis StartsLatency
    thoughts (default)Reasoning + thoughtsWhen heading or tool_name appear in response streamLow — runs in parallel while tool args still stream
    completeReasoning + full responseAfter the entire response stream endsHigher — blocking wait before tool execution

    Verdict Actions

    • <ok/>: Tool execution proceeds normally.
    • <terminate/>: The agent is stopped immediately with a warning log and desktop notification. The last AI message in history is replaced with [BLOCKED].
    • <clarify>: The agent enters a clarification loop. The main model is asked to explain its reasoning. This repeats up to the configured Max Clarifications limit before triggering termination.