docs/guides/usage.md
This guide explores usage and configuration scenarios for Agent Zero. You can consider this as a reference post-installation guide.
Agent Zero provides several basic operations through its interface:
The Restart button allows you to quickly restart the Agent Zero container without using the terminal:
[!TIP] Use the Restart function when you want to:
- Reset the framework if you encounter unexpected behavior
- See changes applied to the framework code
Located beneath the chat input box, Agent Zero provides a set of action buttons for enhanced control and visibility:
.txt, .pdf, .csv, .html, .json, and .md formats/a0/knowledge/custom/mainAccess the chat history in JSON format
/a0/usr/chats/ inside the container[!TIP] Use the Context and History buttons to understand how the agent interprets your instructions and debug any unexpected behavior.
Open the Plugins dialog from the sidebar quick actions by clicking the plugin icon.
From this view you can manage installed plugins, review plugin details, open plugin settings, and change activation state.
There are two ways to reach the Plugin Hub from the Plugins dialog:
The Plugin Hub lets you search community plugins, filter by tags, sort the listing, and open a plugin card for more context before installing.
Opening a plugin shows its author, tags, README content, and install action. Once you are in the detail view, the next steps are intentionally straightforward.
Agent Zero supports direct file attachments in the chat interface for seamless file operations:
[!TIP] When working with multiple files, you can attach them all at once and then give instructions about what to do with them. The agent will handle them as a batch while keeping you informed of the progress.
Agent Zero's power comes from its ability to use tools. Here's how to leverage them effectively:
The built-in browser is provided by the _browser plugin and direct browser tool. It uses Playwright operations controlled by the main agent, exposes typed page refs for links, buttons, images, and inputs, and includes a WebUI viewer for open browser sessions. Playwright Chromium is preinstalled in Docker; in local development it is installed on demand when needed via ensure_playwright_binary() (see Development Setup to pre-install).
If you need a different browser stack or want external browser tooling, MCP-based browser tools are still a strong option:
See MCP Setup for configuration guidance and recommended servers.
Agent Zero instances can communicate with each other using the A2A protocol. This enables:
To enable A2A connectivity, go to Settings ā MCP/A2A ā A0 A2A Server and toggle the server on. You'll receive a connection URL that other Agent Zero instances can use to communicate with your agent.
See A2A Setup for detailed configuration and use cases.
Let's say you want Agent Zero to perform some financial analysis tasks. Here's a possible prompt:
Please be a professional financial analyst. Find last month Bitcoin/ USD price trend and make a chart in your environment. The chart must have highlighted key points corresponding with dates of major news about cryptocurrency. Use the
search_engineanddocument_querytools to find the price and the news, and thecode_execution_toolto perform the rest of the job.
Agent Zero might then:
search_engine and document_query tools to query a reliable source for the Bitcoin price and for the news about cryptocurrency as prompted.code_execution_tool to execute a Python script that performs the graph creation and key points highlighting, using the extracted data and the news dates as inputs.response_tool.[!NOTE] The first run of
code_execution_toolmay take a while as it downloads and builds the Agent Zero Docker image. Subsequent runs will be faster.
This example demonstrates how to combine multiple tools to achieve an analysis task. By mastering prompt engineering and tool usage, you can unlock the full potential of Agent Zero to solve complex problems.
One of Agent Zero's unique features is multi-agent cooperation.
Projects are isolated workspaces that provide dedicated context, instructions, memory, and secrets for specific tasks or clients. They are one of Agent Zero's most powerful organizational features, preventing context bleed and enabling focused, specialized agent behavior.
Each project includes:
/a0/usr/projects/<project_name>/There are two ways to access project management:
Create a new empty project workspace:
Clone a repository directly into your project workspace:
The system clones the main branch by default. You can ask the agent to checkout other branches later. After cloning, you'll see repository status including current branch, clean/dirty state, and last commit info.
[!NOTE] If the cloned repository already contains a
.a0proj/configuration folder, Agent Zero merges the existing configuration with your specified preferences.
[!IMPORTANT] Well-written instructions are key to effective project-specific behavior. Be specific about:
- The agent's role and expertise for this project
- Directory paths and file locations
- Expected workflows and procedures
- Quality standards and validation rules
- Output formats and requirements
Example instructions:
## Your Role
You are an expert Financial Data Analyst working with Excel automation.
## Operational Context
- Work directory: `/usr/projects/excel-finance/`
- Input data: `/usr/projects/excel-finance/data/incoming/`
- Reports output: `/usr/projects/excel-finance/reports/`
## Core Responsibilities
1. Scan for new Excel/CSV files in incoming directory
2. Validate and clean data (check for missing values, duplicates)
3. Consolidate data from multiple sources
4. Generate executive reports with visualizations
5. Flag compliance issues and anomalies
Choose how project memory is managed:
Own memory (recommended): Project has isolated memory under vector_db/projects/<project_name>/
Global memory: Project shares the default memory pool
Projects support scoped configuration:
Variables (non-sensitive): Stored in .a0proj/variables.env
API_BASE_URL=https://api.example.com
OUTPUT_FORMAT=json
Secrets (sensitive): Stored in .a0proj/secrets.env
API_KEY=sk-abc123xyz...
DATABASE_PASSWORD=super_secret_pwd
Reference these in your prompts: "Use my API_KEY to authenticate with the service"
[!WARNING] Secrets may not be included in backup archives. Keep a separate manual copy of critical credentials.
Projects can automatically inject their directory structure into the agent's context. This is configurable per project:
The default ignores: .a0proj/, venv/, __pycache__/, node_modules/, .git/
This feature helps the agent understand your codebase structure without manual explanation.
To use a project, activate it for your current chat:
Each chat can have its own active project. Multiple chats can use different projects simultaneously.
Once activated, the agent:
/a0/usr/projects/<project_name>/
āāā .a0proj/ # Project metadata (managed by A0)
ā āāā project.json # Main configuration
ā āāā variables.env # Non-sensitive config
ā āāā secrets.env # Sensitive credentials
ā āāā agents.json # Subagent settings
ā āāā instructions/ # Additional instruction files
ā āāā knowledge/ # Project knowledge base
āāā src/ # Your actual project files
āāā data/ # Data files
āāā ... # Other project content
Multi-Client Work: Create separate projects for each client with isolated memory and credentials
Multi-Language Development: Organize by tech stack (Python ML, Node.js webapp, Go microservices)
Domain-Specific Tasks: Separate projects for finance, marketing, HR with domain-specific instructions
Automated Workflows: Combine with Tasks & Scheduling for recurring project-based work
[!TIP] For a comprehensive guide to creating and managing projects, including detailed examples and troubleshooting, see the Projects Tutorial.
See also:
Tasks enable Agent Zero to run automated or scheduled work in isolated contexts. They're perfect for recurring workflows, batch processing, or time-delayed operations that don't require immediate attention.
Tasks are autonomous work units that Agent Zero executes in dedicated or shared chat contexts. Each task includes:
Agent Zero supports three types of tasks:
Run on a recurring schedule using cron syntax:
0 9 * * * (every day at 9 AM)0 * * * * (every hour)0 9 * * 1 (Mondays at 9 AM)Execute at specific, predetermined times:
Manual execution for on-demand work:
Access the Task Scheduler from the sidebar:
The scheduler shows:
Ask the agent to create tasks programmatically:
Create a scheduled task that checks my email inbox every morning at 8 AM
and summarizes new messages from the last 24 hours.
The agent uses the scheduler tool to create tasks based on your natural language description.
When editing a task, you configure:
A unique identifier for the task:
Choose the execution model:
[!NOTE] Task type cannot be changed after creation. To switch types, create a new task.
Optionally link the task to a project:
Benefits of project-scoped tasks:
Example:
Control task execution:
Toggle state to temporarily disable tasks without deleting them.
For Scheduled Tasks, configure the cron schedule:
Common patterns:
# Every day at 9 AM
0 9 * * *
# Every hour
0 * * * *
# Every Monday at 10 AM
0 10 * * 1
# Every 15 minutes
*/15 * * * *
# First day of month at midnight
0 0 1 * *
Timezone aware: Tasks respect your configured timezone setting
For Planned Tasks, add specific execution times:
Dedicated Context (recommended):
Shared Context:
When a task runs:
Context Preparation
Prompt Injection
Agent Execution
Result Handling
Real-time monitoring:
Execution history:
Task: "Morning Inbox Summary"
Type: Scheduled (0 9 * * *)
Project: "Email Automation"
Prompt: "Check my Gmail inbox for new messages from the last 24 hours.
Summarize important emails by category and highlight any urgent items."
Task: "Server Health Check"
Type: Scheduled (*/30 * * * *)
Project: "DevOps Monitoring"
Prompt: "Check server status, CPU usage, and disk space.
Alert me if any metric exceeds threshold."
Task: "Weekly Data Export"
Type: Scheduled (0 2 * * 0)
Project: "Analytics"
Prompt: "Export last week's analytics data to CSV.
Upload to cloud storage and send summary report."
Task: "Product Launch Sequence"
Type: Planned
Executions:
- 2026-03-01 09:00 - Send launch announcement
- 2026-03-03 14:00 - Send feature highlights
- 2026-03-07 10:00 - Send customer testimonials
Project: "Marketing Campaigns"
Tasks and Projects are designed to work together:
Pattern: Project-Scoped Automation
Create a project with domain-specific instructions
Project: "Customer Support"
Instructions: "You are a customer support analyst.
Monitor ticket queue, categorize by urgency, draft responses."
Create a recurring task for that project
Task: "Ticket Queue Monitor"
Schedule: Every 2 hours
Project: "Customer Support"
Prompt: "Check new tickets and categorize them."
Task automatically uses:
Benefits:
Tasks can trigger notifications on completion or failure:
See Notifications for configuration details.
Tasks can pull from multiple sources:
"Aggregate data from:
1. Sales CRM API
2. Marketing analytics dashboard
3. Customer support tickets
Generate unified weekly report."
[!TIP] Combine Projects + Tasks + Notifications for powerful automation workflows. Example: Create a "Client Reports" project with instructions, then add scheduled tasks for each client that inherit those instructions automatically.
Explore related features:
Use the Settings ā Secrets and Variables fields to store credentials and non-sensitive configuration values.
You can reference these values in prompts by name. For example, store MY_GMAIL as a secret and instruct the agent to use it when prompted.
[!IMPORTANT] Secrets are stored in
/a0/usr/secrets.env.
[!NOTE] Project-scoped secrets and variables (when using Projects) live under
/a0/usr/projects/<project_name>/.a0proj/(secrets.env,variables.env).
Agent Zero includes a secure tunneling feature that allows you to expose your local instance to the internet. This makes it possible to access your Agent Zero instance from anywhere or share it with others without complex network configuration.
Agent Zero uses the Flaredantic library to create secure tunnels. These tunnels:
When sharing your Agent Zero instance via a tunnel:
[!IMPORTANT] When attempting to create a tunnel without authentication configured, Agent Zero will display a security warning.
To secure your tunneled Agent Zero instance, configure authentication in Settings:
Alternatively, you can set environment variables:
AUTH_LOGIN=your_username
AUTH_PASSWORD=your_password
This will require users to enter these credentials when accessing your tunneled Agent Zero instance.
If you encounter issues with the tunnel feature:
[!TIP] Combine tunneling with authentication for secure remote access to your Agent Zero instance from any device, including mobile phones and tablets.
Agent Zero provides both Text-to-Speech (TTS) and Speech-to-Text (STT) capabilities for natural voice interaction:
Enable voice responses from agents:
The TTS uses a standard voice interface provided by modern browsers, which may sound robotic but is effective and does not require complex AI models. This ensures low latency and quick responses across various platforms, including mobile devices.
[!TIP] The Text-to-Speech feature is great for:
- Multitasking while receiving agent responses
- Accessibility purposes
- Creating a more interactive experience
Send voice messages to agents using OpenAI's Whisper model (does not require OpenAI API key!):
Users can adjust settings such as silence threshold and message duration before sending to optimize their interaction experience.
Configure STT settings in the Settings page:
[!IMPORTANT] All STT and TTS functionalities operate locally within the Docker container, ensuring that no data is transmitted to external servers or OpenAI APIs. This enhances user privacy while maintaining functionality.
[!TIP] When asking the agent to solve mathematical problems, it will automatically respond using KaTeX formatting for clear and professional-looking mathematical expressions.
Agent Zero provides a powerful file browser interface for managing your workspace:
[!NOTE] The file browser lets you navigate the Agent Zero filesystem. For file-based work, keep your working files in
/a0/usr(or inside a Project workspace).
[!TIP] The File Browser integrates seamlessly with Agent Zero's capabilities. You can reference files directly in your conversations, and the agent can help you manage, modify, and organize your files.
Agent Zero includes a sophisticated memory management system that stores and retrieves information from conversations, knowledge sources, and learning experiences. The Memory Dashboard provides a powerful interface to view, search, filter, edit, and delete memory entries stored in the vector database.
Open the Memory Dashboard from the sidebar to manage your agent's memory:
The dashboard provides several ways to organize and filter memory entries:
Find specific memories using the powerful search feature:
[!TIP] Use the threshold slider to balance between broad discovery (lower values) and precise matching (higher values). Start with 0.60 and adjust based on your results.
Each memory entry displays key information:
Click any memory entry to open the detailed view with full editing capabilities:
The details panel provides comprehensive information about each memory:
Modify memory entries directly from the details view:
[!NOTE] Edited memories are immediately updated in the vector database and will affect how the agent recalls and uses this information in future interactions.
Remove unwanted or outdated memory entries:
Alternatively, delete directly from the main dashboard:
[!WARNING] Deleted memories cannot be recovered. Use caution when removing entries, especially those from knowledge sources or important conversations.
For bulk cleanup operations:
Memories derived from uploaded knowledge files:
Memories from chat interactions:
When using Projects (see Projects):
[!TIP] Combine memory management with the backup system to preserve important memory states. Before clearing or making bulk changes, create a backup so you can restore if needed.
[!IMPORTANT] Memory management directly affects agent behavior and recall. Regularly maintaining your memory database ensures optimal agent performance and relevant context retention.
Agent Zero provides a comprehensive backup and restore system to protect your data and configurations. This feature helps you safeguard your work and migrate Agent Zero setups between different systems.
Access the backup functionality through the Settings interface:
By default, Agent Zero backs up your most important data:
[!NOTE] Chat history is stored at
/a0/usr/chats/inside the container.
Before creating a backup, you can customize what to include:
[!TIP] The backup system uses pattern matching, so you can include or exclude specific file types. For example, you can backup all
.pyfiles but exclude temporary.tmpfiles.
[!NOTE] Backup creation may take a few minutes depending on the amount of data. You'll see progress updates during the process. Secrets stored in
/a0/usr/secrets.envare not always included in backup archives. Keep a manual copy if you rely on secrets.
The restore process allows you to recover your Agent Zero setup from a previous backup:
After uploading, you can review and customize the restore:
Configure how the restore should handle existing files:
Optionally clean up existing files before restoring:
/a0/usr/secrets.env. Copy it manually when migrating.Moving Agent Zero to a new server or computer:
Preserving completed projects:
Saving work-in-progress states:
Sharing Agent Zero configurations:
[!IMPORTANT] Always test your backup and restore process in a safe environment before relying on it for critical data. Keep multiple backup versions and store them in secure, accessible locations.
[!TIP] The backup system is designed to work across different operating systems and Agent Zero installations. Your backups from a Windows system will work on Linux, and vice versa.