docs: make Agent Zero guides more human
Refresh README, quickstart, and the docs index around Browser, Desktop, A0 CLI, projects, memory, skills, profiles, and model presets. Add optimized scoped screenshots for Web UI, Browser, Desktop, and CLI workflows. Trim architecture-heavy developer pages toward DeepWiki handoffs so local docs stay focused on practical user guidance.
Alessandro committed
May 9, 2026 at 00:02 UTC
58b161e5d3aaf4e9b1a6bd21260a21e5dc4346f6
70 files changed
+2039
-4628
README.md
+52
-22
@@ -3,7 +3,7 @@
3
<img src="docs/res/a0-vector-graphics/horizontal_banner.svg" alt="Agent Zero Banner" width="100%"/>
4
5
# Agent Zero
6
-### AI agents with a full Linux system at their fingertips, and yours.
6
+### AI agents with a full Linux system at their fingertips.
7
8
Agent Zero is a dynamic, organic agentic framework for running AI agents that can create tools, write code, browse the web, cooperate with other agents, and keep learning from your goals and projects.
9
@@ -12,11 +12,13 @@ Agent Zero is a dynamic, organic agentic framework for running AI agents that ca
12
[](https://discord.gg/B8KZKNsPpj)
13
[](https://github.com/sponsors/agent0ai)
14
15
-[Introduction](#what-agent-zero-is) |
15
+[Introduction](#what-is-agent-zero) |
16
[Space Agent](#agent-zero-and-space-agent) |
17
[Quick Start](#how-to-install) |
18
[LLM Plans](#use-your-openai-codex-plan) |
19
[CLI Connector](#a0-cli-connector-use-agent-zero-on-your-host-machine) |
20
+[Browser](#native-browser-with-annotations-and-extensions) |
21
+[Desktop](#linux-desktop-and-libreoffice-cowork) |
22
[Features](#what-makes-agent-zero-different) |
23
[Examples](#try-these-first) |
24
[Docs](#documentation)
@@ -72,37 +74,46 @@ Agent Zero can use a Kali Linux system to accomplish your task. It can inspect f
74
75
The important idea is not a fixed list of buttons. The important idea is that the agent can build and use the right tool when the work demands it.
76
75
-## Universal Canvas
77
+## Canvas
78
77
-Agent Zero is becoming more visual and shared. The right-side Universal Canvas gives agents and humans working surfaces for browser sessions, documents, workspace history, and other plugin panels.
79
+Agent Zero is becoming more visual and shared. The right-side Canvas gives agents and humans working surfaces for browser sessions, documents, workspace history, and other plugin panels.
80
79
-The canvas makes agent work visible. You can watch it browse, inspect what changed, open files, cowork on deliverables, and intervene before a small mistake becomes a large one.
81
+The Canvas makes agent work visible. You can watch it browse, inspect what changed, open files, cowork on deliverables, and intervene before a small mistake becomes a large one.
82
81
-## LibreOffice Integration
83
+## Linux Desktop and LibreOffice Cowork
84
+
85
+<img alt="Agent Zero Desktop Canvas" src="docs/res/usage/webui/desktop-canvas.png" />
86
+<br>
87
+
88
+The Desktop surface opens Agent Zero's own Linux desktop in the Canvas. It is useful when the work needs a real GUI: Linux desktop apps, a terminal window, visual file management, or LibreOffice running where you and the agent can both see it.
89
90
<img alt="Cowork on Documents" width="1406" height="720" src="https://github.com/user-attachments/assets/4ad71888-4f0d-484a-b68b-631ad99187d7" />
91
<br>
92
93
Create, open, and cowork with the AI on documents, spreadsheets, and presentation decks with the LibreOffice stack.
94
88
-The document canvas supports Markdown by default, with LibreOffice-native ODT, ODS, and ODP workflows when binary office artifacts are needed. Agents can create substantial deliverables, read their contents, apply precise saved edits, preserve version history, and generate native ODS charts directly inside spreadsheets. Microsoft Office compatibility imports and exports remain available when explicitly requested.
95
+The Desktop toolbar can create Markdown, Writer, Spreadsheet, and Presentation files. LibreOffice Writer, Calc, and Impress run inside the Desktop, so you can type by hand while Agent Zero creates, updates, saves, and verifies the same files.
96
+
97
+The document Canvas supports Markdown by default, with LibreOffice-native ODT, ODS, and ODP workflows when binary office artifacts are needed. Microsoft Office compatibility imports and exports remain available when explicitly requested.
98
90
-Markdown, Writer, Spreadsheet, and Presentation files share a compact active-file header with save, rename, close, and creation controls in both canvas and modal views.
99
+Markdown, Writer, Spreadsheet, and Presentation files share a compact active-file header with save, rename, close, and creation controls in both Canvas and modal views.
100
+
101
+See the [Desktop guide](./docs/guides/desktop.md) for the screenshot walkthrough, prompt examples, and how Desktop differs from Browser.
102
103
## Native Browser With Annotations and Extensions
104
94
-<img alt="Native Browser" width="1406" height="720" src="https://github.com/user-attachments/assets/8d425af6-fb27-4d46-ade9-8ffa34c7382c" />
105
+<img alt="Agent Zero Browser Canvas and tool history" src="docs/res/usage/browser/browser-canvas-wide.png" />
106
<br>
107
97
-Agent Zero includes a direct Playwright-powered `browser` tool with a visible WebUI viewer, replacing the older browser-agent command flow. The main agent can call actions such as `open`, `navigate`, `content`, `detail`, `screenshot`, `click`, and `type`, then act through typed page references like `[link 3]`, `[button 6]`, and `[input text 8]`.
108
+Agent Zero includes a built-in Browser with an optional live surface in the Canvas. The agent can open pages, read them, click, type, upload files, and take screenshots.
109
99
-The Browser can run in the Docker/container browser or, when configured through the A0 CLI, attach to a host Chrome-family browser. Browser tool calls do not force-open the canvas by themselves: open the Browser surface when you want to watch the live page, or ask the agent to open/show the Browser in canvas.
110
+The Docker browser is the default live Browser surface. With A0 CLI, Agent Zero can also use **Bring Your Own Browser** to work with Chrome, Edge, or Chromium on your own computer. Open the Browser surface when you want to watch the Docker browser, or ask Agent Zero to show it in the Canvas.
111
101
-Browser history keeps per-step screenshots, so older chats show the page state the agent actually saw at that moment instead of linking every step to the latest live frame.
112
+Browser history keeps screenshots of important steps, so older chats can still show what the agent saw.
113
114
For web and mobile development, Annotate mode lets you click page elements or regions and leave actionable comments for the agent targeted at the page itself. You can review a UI visually, mark what needs to change, and send those notes straight back into the conversation.
115
105
-The Browser also supports Chrome extensions installed from the Chrome Web Store directly inside the Agent Zero browser environment, so workflows can use the same kind of browser capabilities real users depend on.
116
+The Browser also supports Chrome extensions inside the Docker browser. See the [Browser guide](./docs/guides/browser.md) for screenshots, settings, host-browser setup, and troubleshooting.
117
118
## Use Your OpenAI Codex Plan
119
@@ -117,9 +128,16 @@ This is the first step toward account-backed LLM plans in Agent Zero. More integ
128
129
# A0 CLI Connector: Use Agent Zero on Your Host Machine
130
120
-Agent Zero is safe when it lives in Docker. The **A0 CLI Connector** is how you intentionally let it work beyond the container: on your host machine, in a terminal-first workflow, or against a server where you do not want a GUI at all.
131
+The **A0 CLI Connector** is not a separate CLI agent. It connects to a running
132
+Agent Zero instance and gives that instance a terminal-native bridge to your
133
+host machine.
134
+
135
+Agent Zero stays responsible for the reasoning loop, memory, projects, profiles,
136
+model choices, and tools. The CLI is how you intentionally let that Agent
137
+Zero instance work beyond the Docker container: on your host machine, in a
138
+terminal-first workflow, or against a server where you do not want a GUI at all.
139
122
-<img width="1084" height="656" alt="A0 CLI Connector" src="https://github.com/user-attachments/assets/72d405df-d9a0-4d4b-8f96-edfa482bdb13" />
140
+<img alt="A0 CLI Connector connected shell" src="docs/res/usage/a0-cli/a0-cli-start.png" />
141
<br>
142
143
Install the connector on the machine you want Agent Zero to work on, not inside the Agent Zero container.
@@ -142,7 +160,9 @@ Then run:
160
a0
161
```
162
145
-`a0` connects your terminal to an Agent Zero instance. It can usually discover a local instance automatically, or you can point it at a remote Agent Zero URL hosted somewhere else, such as a VPS or tunnel.
163
+`a0` connects your terminal to an existing Agent Zero instance. It can usually discover a local instance automatically, or you can point it at a remote Agent Zero URL hosted somewhere else, such as a VPS or tunnel.
164
+
165
+Inside the shell, use `Ctrl+P` for the command palette, `/chats` to switch work, `/models` or `/presets` to adjust models, and `/browser status` to check Browser mode.
166
167
When you activate **Read+Write** access and the **Remote Code Execution Tool** in the CLI, Agent Zero can operate on the filesystem and shell of the machine where `a0` is running. That means it can work on your real local project files, not only files inside the Docker sandbox.
168
@@ -157,11 +177,15 @@ This is especially useful if you:
177
For full setup details, manual fallback installation, and remote-host tips, see the [A0 CLI Connector guide](./docs/guides/a0-cli-connector.md).
178
179
160
-### Projects, Skills, and Agent Profiles
180
+### Projects, Skills, Agent Profiles, and Model Presets
181
182
Projects isolate workspaces, instructions, memory, secrets, knowledge, repositories, and model presets. Clone a public or private Git repo into an isolated project and give the agent context that belongs to that work alone.
183
164
-Skills use the open `SKILL.md` standard: portable, structured capabilities that can be activated globally, per project, or for the current chat. Agent Profiles let you switch the behavior, prompt overrides, tools, extensions, and model configuration of the active agent without rewriting the whole system.
184
+Skills can be loaded on demand by Agent Zero, or pinned from the chat input when
185
+you want a specific procedure to stay active. Agent Profiles change the broader
186
+working style of the current chat. Model Presets are named shortcuts for model
187
+setups, so users can quickly switch between fast, balanced, cheap, local, or
188
+high-power model choices.
189
190
### Multi-Agent Cooperation
191
@@ -187,7 +211,7 @@ Agent Zero supports plugins, MCP, A2A, custom tools, custom prompts, project-sco
211
- **Research with the Browser tool:** "Use the Browser tool to compare three project management tools for a small AI team, and summarize the tradeoffs with source links."
212
- **Cowork on a spreadsheet:** "Create an editable ODS budget model with assumptions and monthly projections."
213
- **Review a web UI:** "Open my local app in the Browser. I will annotate the page with comments; then implement the requested UI fixes."
190
-- **Work inside a Git project:** "Clone this repository into a new project, inspect the architecture, and propose the safest first improvement."
214
+- **Work inside a Git project:** "Clone this repository into a new project, understand the layout, and propose the safest first improvement."
215
- **Create a specialist:** "Create an Agent Profile for financial analysis with cautious reasoning, clear assumptions, and spreadsheet-first deliverables."
216
- **Recover a workspace:** "Show me recent Time Travel snapshots and explain what changed before I revert anything."
217
@@ -241,13 +265,19 @@ Agent Zero is powerful because it can use a real environment. Treat it with the
265
| --- | --- |
266
| Install or update Agent Zero | [Installation](./docs/setup/installation.md) |
267
| Learn the UI and basic workflow | [Quickstart](./docs/quickstart.md) |
268
+| Browse, annotate, and use Browser screenshots | [Browser guide](./docs/guides/browser.md) |
269
+| Use the Linux desktop and LibreOffice | [Desktop guide](./docs/guides/desktop.md) |
270
| Connect Agent Zero to host-machine files and shell | [A0 CLI Connector](./docs/guides/a0-cli-connector.md) |
271
| Use projects and Git workspaces | [Projects guide](./docs/guides/projects.md) |
272
+| Create a small plugin | [Create a Small Plugin](./docs/guides/create-plugin.md) |
273
+| Add or remove active skills | [Skills guide](./docs/guides/skills.md) |
274
| Create or switch Agent Profiles | [Agent Profiles](./docs/guides/agent-profiles.md) |
247
-| Use skills and agent capabilities | [Usage guide](./docs/guides/usage.md) |
275
+| Create or switch Model Presets | [Model Presets](./docs/guides/model-presets.md) |
276
+| Manage and curate memories | [Memory guide](./docs/guides/memory.md) |
277
+| Learn the everyday chat controls | [Usage guide](./docs/guides/usage.md) |
278
| Configure MCP or external tools | [MCP setup](./docs/guides/mcp-setup.md) |
249
-| Understand the architecture | [Architecture](./docs/developer/architecture.md) |
250
-| Build extensions or plugins | [Extensions](./docs/developer/extensions.md) |
279
+| Understand the architecture and internals | [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero) |
280
+| Build an advanced extension | [Extensions](./docs/developer/extensions.md) |
281
| Contribute to the project | [Contributing](./docs/guides/contribution.md) |
282
| Troubleshoot problems | [Troubleshooting](./docs/guides/troubleshooting.md) |
283
docs/README.md
+62
-42
@@ -1,36 +1,49 @@
1
2
# Agent Zero Documentation
3
4
-Welcome to the Agent Zero documentation hub. Whether you're getting started or diving deep into the framework, you'll find comprehensive guides below.
4
+Welcome to the Agent Zero documentation hub. Start with the practical guides
5
+below: install it, open the Web UI, connect your host machine when needed, and
6
+learn the main workflows by sight.
7
+
8
+For architecture and source-linked internals, use
9
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). The local
10
+docs focus on practical setup, screenshots, and user workflows.
11
12
## Quick Start
13
14
- **[Quickstart Guide](quickstart.md):** Get up and running in 5 minutes with Agent Zero.
15
- **[Installation Guide](setup/installation.md):** Install scripts, updates, and advanced Docker setup (includes [How to Update](setup/installation.md#how-to-update-agent-zero)).
10
-- **[A0 CLI Connector](guides/a0-cli-connector.md):** Install the terminal-native connector, connect it to Agent Zero, and copy a setup brief for another agent.
16
+- **[A0 CLI Connector](guides/a0-cli-connector.md):** Install the host connector for a running Agent Zero instance, use the command palette, and switch Browser modes.
17
- **[Self Update](guides/self-update.md):** How the in-app updater works (technical reference).
18
- **[VPS Deployment](setup/vps-deployment.md):** Deploy Agent Zero on a remote server.
19
- **[Development Setup](setup/dev-setup.md):** Set up a local development environment.
20
21
## User Guides
22
17
-- **[Usage Guide](guides/usage.md):** Comprehensive guide to Agent Zero's features and capabilities.
18
-- **[A0 CLI Connector](guides/a0-cli-connector.md):** Terminal-first companion workflow for Agent Zero.
19
-- **[Agent Profiles](guides/agent-profiles.md):** Create and select specialized profiles, prompt overrides, and profile-specific model config.
23
+- **[Usage Guide](guides/usage.md):** Practical tour of Agent Zero's main workflows.
24
+- **[Browser Guide](guides/browser.md):** Use the built-in Browser, live Canvas surface, annotations, screenshots, host browser mode, and extensions.
25
+- **[Desktop Guide](guides/desktop.md):** Use the built-in Linux desktop, GUI apps, and LibreOffice Writer/Calc/Impress Cowork.
26
+- **[A0 CLI Connector](guides/a0-cli-connector.md):** Terminal-first host connector for Agent Zero, with screenshots of the host picker, connected shell, command palette, and Browser modes.
27
+- **[Create a Small Plugin](guides/create-plugin.md):** Build and review a tiny Web UI plugin that adds an unread dot to the chat list.
28
+- **[Skills Guide](guides/skills.md):** Open the Skills selector, add active skills, and remove prompt extras you no longer need.
29
+- **[Agent Profiles](guides/agent-profiles.md):** Switch the current chat profile or create a new guided profile from the chat input.
30
+- **[Model Presets](guides/model-presets.md):** Create simple named shortcuts for model setups.
31
+- **[Memory Guide](guides/memory.md):** Search, edit, delete, and curate memories so useful context does not become stale noise.
32
- **[Projects Tutorial](guides/projects.md):** Learn to create isolated workspaces with dedicated context and memory.
33
- **[API Integration](guides/api-integration.md):** Add external APIs without writing code.
34
- **[MCP Setup](guides/mcp-setup.md):** Configure Model Context Protocol servers.
35
- **[A2A Setup](guides/a2a-setup.md):** Enable agent-to-agent communication.
36
- **[Troubleshooting](guides/troubleshooting.md):** Solutions to common issues and FAQs.
37
26
-## Developer Documentation
38
+## Technical Reference
39
28
-- **[Architecture Overview](developer/architecture.md):** Understand Agent Zero's internal structure and components.
29
-- **[Plugins](developer/plugins.md):** Build plugins with `plugin.yaml`, scoped settings, and activation toggles.
30
-- **[Extensions](developer/extensions.md):** Create custom extensions to extend functionality.
31
-- **[Connectivity](developer/connectivity.md):** Connect to Agent Zero from external applications.
32
-- **[WebSockets](developer/websockets.md):** Real-time communication infrastructure.
33
-- **[MCP Configuration](developer/mcp-configuration.md):** Advanced MCP server configuration.
40
+- **[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero):** Architecture, Web UI internals, plugin lifecycle, backend APIs, deployment details, and source-linked explanations.
41
+- **[Architecture](developer/architecture.md):** Short local handoff to DeepWiki plus practical starting points.
42
+- **[Plugins](developer/plugins.md):** Compact plugin starting points and sharing checklist.
43
+- **[Extensions](developer/extensions.md):** Short guide for when an extension is the right tool.
44
+- **[Connectivity](developer/connectivity.md):** Choose between A0 CLI, MCP, A2A, and external APIs.
45
+- **[WebSockets](developer/websockets.md):** Short local handoff to DeepWiki and source files.
46
+- **[MCP Configuration](developer/mcp-configuration.md):** Compact reference for MCP JSON.
47
- **[Notifications](developer/notifications.md):** Notification system architecture and setup.
48
- **[Contributing Skills](developer/contributing-skills.md):** Create and share agent skills.
49
- **[Contributing Guide](guides/contribution.md):** Contribute to the Agent Zero project.
@@ -52,9 +65,9 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
65
- [How to Update Agent Zero](setup/installation.md#how-to-update-agent-zero)
66
- [Manual Installation (Advanced)](setup/installation.md#manual-installation-advanced)
67
- [Step 1: Install Docker Desktop](setup/installation.md#step-1-install-docker-desktop)
55
- - [Windows Installation](setup/installation.md#-windows-installation)
56
- - [macOS Installation](setup/installation.md#-macos-installation)
57
- - [Linux Installation](setup/installation.md#-linux-installation)
68
+ - [Windows Installation](setup/installation.md#windows-installation)
69
+ - [macOS Installation](setup/installation.md#macos-installation)
70
+ - [Linux Installation](setup/installation.md#linux-installation)
71
- [Step 2: Run Agent Zero](setup/installation.md#step-2-run-agent-zero)
72
- [Pull Docker Image](setup/installation.md#21-pull-the-agent-zero-docker-image)
73
- [Map Folders for Persistence](setup/installation.md#22-optional-map-folders-for-persistence)
@@ -77,45 +90,43 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
90
- [User Guides](#user-guides)
91
- [Usage Guide](guides/usage.md)
92
- [Basic Operations](guides/usage.md#basic-operations)
80
- - [Plugins and Plugin Hub](guides/usage.md#plugins-and-plugin-hub)
93
+ - [Plugins And Plugin Hub](guides/usage.md#plugins-and-plugin-hub)
94
+ - [Skills, Agent Profiles, And Model Presets](guides/usage.md#skills-agent-profiles-and-model-presets)
95
+ - [Skills](guides/usage.md#skills)
96
+ - [Agent Profiles](guides/usage.md#agent-profiles)
97
+ - [Model Presets](guides/usage.md#model-presets)
98
+ - [File Attachments](guides/usage.md#file-attachments)
99
- [Tool Usage](guides/usage.md#tool-usage)
100
+ - [Browser Tool And Surface](guides/usage.md#browser-tool-and-surface)
101
+ - [Desktop Surface](guides/usage.md#desktop-surface)
102
+ - [Agent-To-Agent Communication](guides/usage.md#agent-to-agent-communication)
103
+ - [Multi-Agent Cooperation](guides/usage.md#multi-agent-cooperation)
104
- [Projects](guides/usage.md#projects)
83
- - [What Projects Provide](guides/usage.md#what-projects-provide)
84
- - [Creating Projects](guides/usage.md#creating-projects)
85
- - [Project Configuration](guides/usage.md#project-configuration)
86
- - [Activating Projects](guides/usage.md#activating-projects)
87
- - [Common Use Cases](guides/usage.md#common-use-cases)
88
- - [Tasks & Scheduling](guides/usage.md#tasks--scheduling)
89
- - [Task Types](guides/usage.md#task-types)
90
- - [Creating Tasks](guides/usage.md#creating-tasks)
91
- - [Task Configuration](guides/usage.md#task-configuration)
92
- - [Integration with Projects](guides/usage.md#integration-with-projects)
93
- - [Secrets & Variables](guides/usage.md#secrets--variables)
94
- - [Remote Access via Tunneling](guides/usage.md#remote-access-via-tunneling)
105
+ - [Tasks And Scheduling](guides/usage.md#tasks-and-scheduling)
106
+ - [Secrets And Variables](guides/usage.md#secrets-and-variables)
107
+ - [Remote Access Via Tunneling](guides/usage.md#remote-access-via-tunneling)
108
- [Voice Interface](guides/usage.md#voice-interface)
109
+ - [Mathematical Expressions](guides/usage.md#mathematical-expressions)
110
+ - [File Browser](guides/usage.md#file-browser)
111
- [Memory Management](guides/usage.md#memory-management)
97
- - [Backup & Restore](guides/usage.md#backup--restore)
112
+ - [Backup And Restore](guides/usage.md#backup-and-restore)
113
+ - [Browser Guide](guides/browser.md)
114
+ - [Desktop Guide](guides/desktop.md)
115
- [A0 CLI Connector](guides/a0-cli-connector.md)
116
+ - [Create a Small Plugin](guides/create-plugin.md)
117
+ - [Skills Guide](guides/skills.md)
118
- [Agent Profiles](guides/agent-profiles.md)
119
+ - [Model Presets](guides/model-presets.md)
120
+ - [Memory Guide](guides/memory.md)
121
- [Projects Tutorial](guides/projects.md)
122
- [API Integration](guides/api-integration.md)
123
- [MCP Setup](guides/mcp-setup.md)
124
- [A2A Setup](guides/a2a-setup.md)
125
- [Troubleshooting](guides/troubleshooting.md)
126
106
-- [Developer Documentation](#developer-documentation)
107
- - [Architecture Overview](developer/architecture.md)
108
- - [System Architecture](developer/architecture.md#system-architecture)
109
- - [Runtime Architecture](developer/architecture.md#runtime-architecture)
110
- - [Implementation Details](developer/architecture.md#implementation-details)
111
- - [Core Components](developer/architecture.md#core-components)
112
- - [Agents](developer/architecture.md#1-agents)
113
- - [Tools](developer/architecture.md#2-tools)
114
- - [Memory System](developer/architecture.md#3-memory-system)
115
- - [Prompts](developer/architecture.md#4-prompts)
116
- - [Knowledge](developer/architecture.md#5-knowledge)
117
- - [Skills](developer/architecture.md#6-skills)
118
- - [Extensions](developer/architecture.md#7-extensions)
127
+- [Technical Reference](#technical-reference)
128
+ - [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
129
+ - [Architecture](developer/architecture.md)
130
- [Plugins](developer/plugins.md)
131
- [Extensions](developer/extensions.md)
132
- [Connectivity](developer/connectivity.md)
@@ -127,6 +138,15 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
138
139
---
140
141
+## Documentation Ownership
142
+
143
+| Content type | Home |
144
+| --- | --- |
145
+| Setup, screenshots, and everyday workflows | These docs |
146
+| Architecture and source-linked internals | [DeepWiki](https://deepwiki.com/agent0ai/agent-zero) |
147
+| Exact behavior | The current source code |
148
+| Community help and examples | Discord, Skool, GitHub discussions |
149
+
150
### Your journey with Agent Zero starts now!
151
152
Ready to dive in? Start with the [Quickstart Guide](quickstart.md) for the fastest path to your first chat, or follow the [Installation Guide](setup/installation.md) for a detailed setup walkthrough.
docs/agents/AGENTS.modals.md
+1
-1
@@ -218,7 +218,7 @@ Outcome:
218
219
### Floating no-backdrop modals
220
221
-Use `.modal-floating` on the outer `.modal` when a modal should behave like a floating utility panel instead of a blocking dialog. This is for special live surfaces such as the browser panel where the user should keep seeing and interacting with the chat or dashboard behind the panel.
221
+Use `.modal-floating` on the outer `.modal` when a modal should behave like a floating utility panel instead of a blocking dialog. This is for special live surfaces where the user should keep seeing and interacting with the chat or dashboard behind the panel. The Browser now primarily lives in the Canvas, Agent Zero's right-side workspace for live surfaces, but its floating/windowed surface follows the same non-blocking modal contract.
222
223
Working contract:
224
docs/agents/AGENTS.plugins.md
+3
-3
@@ -1,6 +1,6 @@
1
# Agent Zero - Plugins Guide
2
3
-This guide covers the Python Backend and Frontend WebUI plugin architecture. Use this as the definitive reference for building and extending Agent Zero.
3
+This guide covers the Python Backend and Frontend Web UI plugin architecture. Use this as the definitive reference for building and extending Agent Zero.
4
5
---
6
@@ -13,7 +13,7 @@ Agent Zero uses a convention-over-configuration plugin model where runtime capab
13
1. Backend discovery (python/helpers/plugins.py): Resolves roots (usr/plugins/ first, then plugins/) and builds the effective set of plugins.
14
2. Path resolution (python/helpers/subagents.py): Injects plugin paths into the agent's search space for prompts, tools, and configurations.
15
3. Python extensions (python/helpers/extension.py): Executes named lifecycle hooks from `extensions/python/<point>/` and implicit `@extensible` hooks from `extensions/python/_functions/<module>/<qualname>/<start|end>/`.
16
-4. WebUI extensions (webui/js/extensions.js): Injects HTML/JS contributions into core UI breakpoints (x-extension).
16
+4. Web UI extensions (webui/js/extensions.js): Injects HTML/JS contributions into core UI breakpoints (x-extension).
17
18
---
19
@@ -330,7 +330,7 @@ Both routes surface Plugin Index entries inside Agent Zero. The Plugin Hub suppo
330
331
## 9. See Also
332
333
-- `docs/developer/plugins.md` for the developer-facing plugin lifecycle and publishing guide
333
+- `docs/developer/plugins.md` for the compact plugin starting point and sharing checklist
334
- `plugins/README.md` for the bundled-vs-user plugin directory overview and quick links
335
- `skills/a0-plugin-router/SKILL.md` for the agent-facing entry point that routes plugin tasks to the right specialist skill
336
- `AGENTS.md` for the main framework guide
docs/developer/architecture.md
+25
-363
@@ -1,370 +1,32 @@
1
-# Architecture Overview
2
-Agent Zero is built on a flexible and modular architecture designed for extensibility and customization. This section outlines the key components and the interactions between them.
1
+# Architecture
2
4
-## System Architecture
3
+Agent Zero architecture is now documented in
4
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
5
6
-The user or Agent 0 is at the top of the hierarchy, delegating tasks to subordinate agents, which can further delegate to other agents. Each agent can utilize tools and access the shared assets (prompts, memory, knowledge, extensions and skills) to perform its tasks.
6
+Use DeepWiki when you want source-linked explanations of:
7
8
-## Runtime Architecture
9
-Agent Zero's runtime architecture is built around Docker containers:
8
+- the agent loop and message flow;
9
+- Web UI internals;
10
+- plugin discovery and lifecycle;
11
+- projects, memory, tools, and scheduler internals;
12
+- backend APIs and WebSocket behavior;
13
+- deployment and runtime structure.
14
11
-1. **Host System (your machine)**:
12
- - Requires only Docker and a web browser
13
- - Runs Docker Desktop or Docker Engine
14
- - Handles container orchestration
15
+This local page intentionally stays short so the repository does not maintain a
16
+second, stale architecture manual.
17
16
-2. **Runtime Container**:
17
- - Houses the complete Agent Zero framework
18
- - Manages the Web UI and API endpoints
19
- - Handles all core functionalities including code execution
20
- - Provides a standardized environment across all platforms
18
+## Practical Starting Points
19
22
-This architecture ensures:
23
-- Consistent environment across platforms
24
-- Simplified deployment and updates
25
-- Enhanced security through containerization
26
-- Reduced dependency requirements on host systems
27
-- Flexible deployment options for advanced users
28
-
29
-> [!NOTE]
30
-> The legacy approach of running Agent Zero directly on the host system (using Python, Conda, etc.)
31
-> is still possible but requires Remote Function Calling (RFC) configuration through the Settings
32
-> page. See the [development guide](development.md) for detailed instructions.
33
-
34
-## Implementation Details
35
-
36
-### Directory Structure
37
-| Directory | Description |
38
-| --- | --- |
39
-| `/docker` | Docker-related files for runtime container |
40
-| `/docs` | Documentation files and guides |
41
-| `/usr/skills` | Skills using the open SKILL.md standard (contextual expertise) |
42
-| `/agents` | Agent profiles (prompts, tools, extensions per profile) |
43
-| `/knowledge` | Knowledge base storage |
44
-| `/logs` | HTML CLI-style chat logs |
45
-| `/memory` | Persistent agent memory storage |
46
-| `/prompts` | Default system and tool prompt templates |
47
-| `/python` | Core Python codebase |
48
-| `/python/api` | API endpoints and interfaces |
49
-| `/python/extensions` | Modular extensions |
50
-| `/python/helpers` | Utility functions |
51
-| `/python/tools` | Tool implementations |
52
-| `/tmp` | Temporary runtime data |
53
-| `/usr/chats` | Saved chat history (JSON) |
54
-| `/usr/secrets.env` | Secrets store (not always included in backups) |
55
-| `/usr/projects` | Project workspaces and `.a0proj` metadata |
56
-| `/webui` | Web interface components |
57
-| `/webui/css` | Stylesheets |
58
-| `/webui/js` | JavaScript modules |
59
-| `/webui/public` | Static assets |
60
-
61
-### Key Files
62
-| File | Description |
63
-| --- | --- |
64
-| `usr/settings.json` | Main runtime settings (written by the Settings UI) |
65
-| `usr/secrets.env` | Secrets store (managed via Settings -> Secrets) |
66
-| `conf/model_providers.yaml` | Model provider defaults and settings |
67
-| `agent.py` | Core agent implementation |
68
-| `execute.py` | Framework initialization |
69
-| `models.py` | Model providers and configs |
70
-| `preload.py` | Pre-initialization routines |
71
-| `prepare.py` | Environment preparation |
72
-| `requirements.txt` | Python dependencies |
73
-| `run_ui.py` | Web UI launcher |
74
-
75
-> [!NOTE]
76
-> In the Docker runtime, the framework lives under `/a0` inside the container. Data persists as long as the container exists. For upgrades, prefer **Backup & Restore** instead of mapping the full `/a0` directory.
77
-
78
-## Core Components
79
-Agent Zero's architecture revolves around the following key components:
80
-
81
-### 1. Agents
82
-The core actors within the framework. Agents receive instructions, reason, make decisions, and utilize tools to achieve their objectives. Agents operate within a hierarchical structure, with superior agents delegating tasks to subordinate agents.
83
-
84
-#### Agent Hierarchy and Communication
85
-Agent Zero employs a hierarchical agent structure, where a top-level agent (often the user) can delegate tasks to subordinate agents. This hierarchy allows for the efficient breakdown of complex tasks into smaller, more manageable sub-tasks.
86
-
87
-Communication flows between agents through messages, which are structured according to the prompt templates. These messages typically include:
88
-
89
-| Argument | Description |
90
-| --- | --- |
91
-| `Thoughts:` | The agent's Chain of Thought and planning process |
92
-| `Tool name:` | The specific tool used by the agent |
93
-| `Responses or queries:` | Results, feedback or queries from tools or other agents |
94
-
95
-#### Interaction Flow
96
-A typical interaction flow within Agent Zero might look like this:
97
-
98
-1. The user provides an instruction to Agent 0
99
-2. Agent 0 initializes VectorDB and access memory
100
-3. Agent 0 analyzes the instruction and formulates a plan using `thoughts` argument, possibly involving the use of tools or the creation of sub-agents
101
-4. If necessary, Agent 0 delegates sub-tasks to subordinate agents
102
-5. Agents use tools to perform actions, both providing arguments and responses or queries
103
-6. Agents communicate results and feedback back up the hierarchy
104
-7. Agent 0 provides the final response to the user
105
-
106
-### 2. Tools
107
-Tools are functionalities that agents can leverage. These can include anything from web search and code execution to interacting with APIs or controlling external software. Agent Zero provides a mechanism for defining and integrating both built-in and custom tools.
108
-
109
-#### Built-in Tools
110
-Agent Zero comes with a set of built-in tools designed to help agents perform tasks efficiently:
111
-
112
-| Tool | Function |
20
+| Goal | Start here |
21
| --- | --- |
114
-| behavior_adjustment | Agent Zero use this tool to change its behavior according to a prior request from the user.
115
-| call_subordinate | Allows agents to delegate tasks to subordinate agents |
116
-| code_execution_tool | Allows agents to execute Python, Node.js, and Shell code in the terminal |
117
-| input | Allows agents to use the keyboard to interact with an active shell |
118
-| response_tool | Allows agents to output a response |
119
-| memory_tool | Enables agents to save, load, delete and forget information from memory |
120
-
121
-#### SearXNG Integration
122
-Agent Zero has integrated SearXNG as its primary search tool, replacing the previous knowledge tools (Perplexity and DuckDuckGo). This integration enhances the agent's ability to retrieve information while ensuring user privacy and customization.
123
-
124
-- Privacy-Focused Search
125
-SearXNG is an open-source metasearch engine that allows users to search multiple sources without tracking their queries. This integration ensures that user data remains private and secure while accessing a wide range of information.
126
-
127
-- Enhanced Search Capabilities
128
-The integration provides access to various types of content, including images, videos, and news articles, allowing users to gather comprehensive information on any topic.
129
-
130
-- Fallback Mechanism
131
-In cases where SearXNG might not return satisfactory results, Agent Zero can be configured to fall back on other sources or methods, ensuring that users always have access to information.
132
-
133
-> [!NOTE]
134
-> The Knowledge Tool is designed to work seamlessly with both online searches through
135
-> SearXNG and local knowledge base queries, providing a comprehensive information
136
-> retrieval system.
137
-
138
-#### Custom Tools
139
-Users can create custom tools to extend Agent Zero's capabilities. Custom tools can be integrated into the framework by defining a tool specification, which includes the tool's prompt. Place these prompt overrides in your agent profile:
140
-
141
-1. Create `agent.system.tool.$TOOL_NAME.md` in `agents/<agent_profile>/prompts/`
142
-2. Add the reference in `agent.system.tools.md` within the same prompt scope
143
-3. If needed, implement tool class in `python/tools` using `Tool` base class
144
-4. Follow existing patterns for consistency
145
-
146
-> [!NOTE]
147
-> Tools are always present in system prompt, so you should keep them to minimum.
148
-> To save yourself some tokens, use the [Skills module](#6-skills)
149
-> to add contextual expertise that is only loaded when relevant.
150
-
151
-### 3. Memory System
152
-The memory system is a critical component of Agent Zero, enabling the agent to learn and adapt from past interactions. It operates on a hybrid model where part of the memory is managed automatically by the framework while users can also manually input and extract information.
153
-
154
-#### Memory Structure
155
-The memory is categorized into four distinct areas:
156
-- **Storage and retrieval** of user-provided information (e.g., names, API keys)
157
-- **Fragments**: Contains pieces of information from previous conversations, updated automatically
158
-- **Solutions**: Stores successful solutions from past interactions for future reference
159
-- **Metadata**: Each memory entry includes metadata (IDs, timestamps), enabling efficient filtering and searching based on specific criteria
160
-
161
-#### Embeddings and Utility Model
162
-- Embeddings are generated locally using a small default model (tiny disk footprint).
163
-- The **utility model** handles summarization and memory extraction; it must be capable enough to distinguish durable knowledge from noise.
164
-
165
-#### Memory Management Best Practices
166
-- After important sessions, ask the agent to **“memorize learning opportunities from the current session.”**
167
-- For long-running workflows, **distill durable knowledge into prompts** rather than relying exclusively on memory.
168
-
169
-#### Messages History and Summarization
170
-
171
-Agent Zero employs a sophisticated message history and summarization system to maintain context effectively while optimizing memory usage. This system dynamically manages the information flow, ensuring relevant details are readily available while efficiently handling the constraints of context windows.
172
-
173
-- **Context Extraction:** The system identifies key information from previous messages that are vital for ongoing discussions. This process mirrors how humans recall important memories, allowing less critical details to fade.
174
-- **Summarization Process:** Using natural language processing through the utility model, Agent Zero condenses the extracted information into concise summaries. By summarizing past interactions, Agent Zero can quickly recall important facts about the whole chat, leading to more appropriate responses.
175
-- **Contextual Relevance:** The summarized context is prioritized based on its relevance to the current topic, ensuring users receive the most pertinent information.
176
-
177
-**Implementation Details:**
178
-
179
-- **Message Summaries**: Individual messages are summarized using a structured format that captures key information while reducing token usage.
180
-- **Dynamic Compression**: The system employs an intelligent compression strategy:
181
- - Recent messages remain in their original form for immediate context.
182
- - Older messages are gradually compressed into more concise summaries.
183
- - Multiple compression levels allow for efficient context window usage.
184
- - Original messages are preserved separately from summaries.
185
-- **Context Window Optimization**:
186
- - Acts as a near-infinite short-term memory for single conversations.
187
- - Dynamically adjusts compression ratios based on available space and settings.
188
-- **Bulk and Topic Summarization**:
189
- - Groups related messages into thematic chunks for better organization.
190
- - Generates concise summaries of multiple messages while preserving key context.
191
- - Enables efficient navigation of long conversation histories.
192
- - Maintains semantic connections between related topics.
193
-
194
-By dynamically adjusting context windows and summarizing past interactions, Agent Zero enhances both efficiency and user experience. This innovation not only reflects the framework's commitment to being dynamic and user-centric, but also draws inspiration from human cognitive processes, making AI interactions more relatable and effective. Just as humans forget trivial details, Agent Zero intelligently condenses information to enhance communication.
195
-
196
-> [!NOTE]
197
-> To maximize the effectiveness of context summarization, users should provide clear and specific instructions during interactions. This helps Agent Zero understand which details are most important to retain.
198
-
199
-### 4. Prompts
200
-The `prompts` directory contains various Markdown files that control agent behavior and communication. The most important file is `agent.system.main.md`, which acts as a central hub, referencing other prompt files.
201
-
202
-#### Core Prompt Files
203
-| Prompt File | Description |
204
-|---|---|
205
-| agent.system.main.role.md | Defines the agent's overall role and capabilities |
206
-| agent.system.main.communication.md | Specifies how the agent should communicate |
207
-| agent.system.main.solving.md | Describes the agent's approach to tasks |
208
-| agent.system.main.tips.md | Provides additional tips or guidance |
209
-| agent.system.main.specifics.md | Empty by default — override per profile for agent-specific instructions |
210
-| agent.system.main.behaviour.md | Controls dynamic behavior adjustments and rules |
211
-| agent.system.main.environment.md | Defines the runtime environment context |
212
-| agent.system.tools.md | Organizes and calls the individual tool prompt files |
213
-| agent.system.tool.*.md | Individual tool prompt files |
214
-
215
-#### Prompt Organization
216
-- **Default Prompts**: Located in `prompts/`, serve as the base configuration
217
-- **Custom Prompts (v0.9.7+)**: Place overrides in `agents/<agent_profile>/prompts/`
218
-- **Behavior Files**: Stored in memory as `behaviour.md`, containing dynamic rules
219
-- **Tool Prompts**: Organized in tool-specific files for modularity
220
-
221
-#### Custom Prompts (Post v0.9.7)
222
-1. Create or clone an existing agent profile under `agents/<agent_profile>/`
223
-2. Add only the prompt files you want to override in `agents/<agent_profile>/prompts/`
224
-3. Agent Zero merges these overrides with the default prompts automatically
225
-4. Select the **Agent Profile** in Settings to activate the overrides
226
-
227
-For user-created profiles, prefer `/a0/usr/agents/<agent_profile>/` so updates do not overwrite custom files. See the [Agent Profiles guide](../guides/agent-profiles.md) for the current `agent.yaml` structure, prompt override paths, and profile-specific `_model_config` model settings.
228
-
229
-#### Prompt Inheritance with `{{include original}}`
230
-When overriding a prompt, you can extend the original instead of replacing it entirely. Use `{{include original}}` to pull in the default version and add your changes on top:
231
-
232
-**Example:** `agents/developer/prompts/agent.system.main.communication.md`:
233
-```markdown
234
-{{include original}}
235
-
236
-- always explain your reasoning
237
-- include code snippets in responses
238
-```
239
-
240
-This finds `agent.system.main.communication.md` in the next directory up the hierarchy → includes the default from `prompts/` → appends the additions. Result:
241
-
242
-```markdown
243
-## Communication
244
-- be concise
245
-- use markdown formatting
246
-- ask clarifying questions when unsure
247
-
248
-- always explain your reasoning
249
-- include code snippets in responses
250
-```
251
-
252
-Overrides stay small and automatically inherit any future changes to the default.
253
-
254
-#### Dynamic Behavior System
255
-- **Behavior Adjustment**:
256
- - Agents can modify their behavior in real-time based on user instructions
257
- - Behavior changes are automatically integrated into the system prompt
258
- - Behavioral rules are merged intelligently, avoiding duplicates and conflicts
259
-
260
-- **Behavior Management Components**:
261
- - `behaviour_adjustment.py`: Core tool for updating agent behavior
262
- - `_20_behaviour_prompt.py`: Extension that injects behavior rules into system prompt
263
- - Custom rules stored in the agent's memory directory as `behaviour.md`
264
-
265
-- **Behavior Update Process**:
266
- 1. User requests behavior changes (e.g., "respond in UK English")
267
- 2. System identifies behavioral instructions in conversation
268
- 3. New rules are merged with existing ruleset
269
- 4. Updated behavior is immediately applied
270
-
271
-- **Integration with System Prompt**:
272
- - Behavior rules are injected at the start of the system prompt
273
- - Rules are formatted in a structured markdown format
274
- - Changes are applied without disrupting other components
275
- - Maintains separation between core functionality and behavioral rules
276
-
277
-> [!NOTE]
278
-> You can customize any of these files. Agent Zero will use files in `agents/<agent_profile>/prompts/` when present, and fall back to `prompts/` for everything else.
279
-
280
-> [!TIP]
281
-> The behavior system allows for dynamic adjustments without modifying the base prompt files.
282
-> Changes made through behavior rules persist across sessions while maintaining the core functionality.
283
-
284
-### 5. Knowledge
285
-Knowledge refers to the user-provided information and data that agents can leverage:
286
-
287
-- **Custom Knowledge**: Add files to `/knowledge/custom/main` directory manually or through the "Import Knowledge" button in the UI
288
- - Supported formats: `.txt`, `.pdf`, `.csv`, `.html`, `.json`, `.md`
289
- - Automatically imported and indexed
290
- - Expandable format support
291
-
292
-- **Knowledge Base**:
293
- - Can include PDFs, databases, books, documentation
294
- - `/docs` folder automatically added
295
- - Used for answering questions and decision-making
296
- - Supports RAG-augmented tasks
297
-
298
-### 6. Skills
299
-Skills provide contextual expertise using the **open SKILL.md standard** (originally developed by Anthropic). Skills are cross-platform and compatible with Claude Code, Cursor, Goose, OpenAI Codex CLI, GitHub Copilot, and more.
300
-
301
-#### Key Features
302
-- **YAML Frontmatter**: Structured metadata (name, description, tags, author)
303
-- **Cross-Platform**: Works with any AI agent that supports the SKILL.md standard
304
-- **Semantic Recall**: Skills are indexed in vector memory and loaded when contextually relevant
305
-- **Token Efficient**: Not in system prompt; loaded dynamically when needed
306
-- **Scripts Support**: Can reference `.sh`, `.py`, `.js`, `.ts` scripts
307
-
308
-#### SKILL.md Format
309
-```yaml
310
----
311
-name: "my-skill"
312
-description: "What this skill does and when to use it"
313
-version: "1.0.0"
314
-author: "Your Name"
315
-tags: ["category", "purpose"]
316
----
317
-
318
-# Skill Instructions
319
-
320
-Your detailed instructions here...
321
-
322
-## Examples
323
-- Example usage 1
324
-- Example usage 2
325
-```
326
-
327
-#### Directory Structure
328
-| Directory | Description |
329
-|-----------|-------------|
330
-| `/skills` | Default skills included with Agent Zero |
331
-| `/usr/skills` | Your custom skills (create folders here) |
332
-
333
-#### Adding Skills
334
-1. Create folder in `usr/skills` (e.g., `usr/skills/my-skill`)
335
-2. Add `SKILL.md` file with YAML frontmatter (required)
336
-3. Optionally add supporting scripts (`.sh`, `.py`, etc.)
337
-4. Optionally add `docs/` subfolder for additional documentation
338
-5. The agent will automatically discover the skill for list/search
339
-
340
-#### Using Skills
341
-Skills are surfaced via description/tag matching. You can also use the `skills_tool` to:
342
-- List all available skills
343
-- Load a specific skill by name
344
-- Read files from within a skill directory
345
-
346
-### 7. Extensions
347
-Extensions are a powerful feature of Agent Zero, designed to keep the main codebase clean and organized while allowing for greater flexibility and modularity.
348
-
349
-#### Structure
350
-Extensions can be found in `python/extensions` directory:
351
-- **Folder Organization**: Extensions are stored in designated subfolders corresponding to different aspects of the agent's message loop
352
-- **Execution Order**: Files are executed in alphabetical order for predictable behavior
353
-- **Naming Convention**: Files start with numbers to control execution order
354
-- **Modularity**: Each extension focuses on a specific functionality
355
-
356
-#### Types
357
-- **Message Loop Prompts**: Handle system messages and history construction
358
-- **Memory Management**: Handle recall and solution memorization
359
-- **System Integration**: Manage interaction with external systems
360
-
361
-#### Adding Extensions
362
-1. Create Python file in appropriate `python/extensions` subfolder
363
-2. Follow naming convention for execution order (start with number)
364
-3. Implement functionality following existing patterns
365
-4. Ensure compatibility with main system
366
-5. Test thoroughly before deployment
367
-
368
-> [!NOTE]
369
-> Consider contributing valuable custom components to the main repository.
370
-> See [Contributing](../guides/contribution.md) for more information.
22
+| Install or update Agent Zero | [Installation Guide](../setup/installation.md) |
23
+| Learn the Web UI | [Usage Guide](../guides/usage.md) |
24
+| Create a focused workspace | [Projects Guide](../guides/projects.md) |
25
+| Use the Browser | [Browser Guide](../guides/browser.md) |
26
+| Connect host files and shell | [A0 CLI Connector](../guides/a0-cli-connector.md) |
27
+| Build plugins | [Plugins](plugins.md) |
28
+| Build extensions | [Extensions](extensions.md) |
29
+| Configure MCP | [MCP Configuration](mcp-configuration.md) |
30
+
31
+If you are changing core behavior, read the relevant DeepWiki page first, then
32
+inspect the source in this repository before editing.
docs/developer/connectivity.md
+39
-673
@@ -1,689 +1,55 @@
1
-# Agent Zero Connectivity Guide
1
+# Connectivity
2
3
-This guide covers the different ways to connect to Agent Zero from external applications, including using the External API, connecting as an MCP client, and enabling agent-to-agent communication.
3
+This page helps you choose the right connection path.
4
5
-**Note:** You can find your specific URLs and API tokens in your Agent Zero instance under `Settings > External Services`.
5
+For source-linked architecture and endpoint internals, use
6
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). The local
7
+docs should not duplicate the full connectivity architecture.
8
7
-### API Token Information
9
+## Choose The Right Path
10
9
-The API token is automatically generated from your username and password. This same token is used for External API endpoints, MCP server connections, and A2A communication. The token will change if you update your credentials.
11
+| Need | Start here |
12
+| --- | --- |
13
+| Let Agent Zero work on your host files, shell, or browser | [A0 CLI Connector](../guides/a0-cli-connector.md) |
14
+| Add a third-party tool through MCP | [MCP Setup](../guides/mcp-setup.md) |
15
+| Let another agent talk to Agent Zero | [A2A Setup](../guides/a2a-setup.md) |
16
+| Add an external API for one workflow | [API Integration](../guides/api-integration.md) |
17
+| Study API, MCP, or A2A internals | [DeepWiki](https://deepwiki.com/agent0ai/agent-zero) |
18
11
----
19
+## External API Basics
20
13
-## External API Endpoints
21
+You can find your API token in Agent Zero under **Settings > External Services**.
22
15
-Agent Zero provides external API endpoints for integration with other applications. These endpoints use API key authentication and support text messages and file attachments.
23
+Common external endpoints include:
24
17
-### `POST /api_message`
25
+| Endpoint | Use it for |
26
+| --- | --- |
27
+| `POST /api_message` | Send a message to Agent Zero. |
28
+| `GET/POST /api_log_get` | Read chat logs. |
29
+| `POST /api_terminate_chat` | Stop a running chat. |
30
+| `POST /api_reset_chat` | Reset a chat. |
31
+| `POST /api_files_get` | Retrieve files. |
32
19
-Send messages to Agent Zero and receive responses. Supports text messages, file attachments, and conversation continuity.
33
+External API calls use the `X-API-KEY` header.
34
21
-### API Reference
22
-
23
-**Parameters:**
24
-* `context_id` (string, optional): Existing chat context ID
25
-* `message` (string, required): The message to send
26
-* `attachments` (array, optional): Array of `{filename, base64}` objects
27
-* `lifetime_hours` (number, optional): Chat lifetime in hours (default: 24)
28
-* `project_name` (string, optional): Project name to activate (only on first message)
29
-
30
-**Headers:**
31
-* `X-API-KEY` (required)
32
-* `Content-Type: application/json`
33
-
34
-### JavaScript Examples
35
-
36
-#### Basic Usage Example
37
-
38
-```javascript
39
-// Basic message example
40
-async function sendMessage() {
41
- try {
42
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_message', {
43
- method: 'POST',
44
- headers: {
45
- 'Content-Type': 'application/json',
46
- 'X-API-KEY': 'YOUR_API_KEY'
47
- },
48
- body: JSON.stringify({
49
- message: "Hello, how can you help me?",
50
- lifetime_hours: 24
51
- })
52
- });
53
-
54
- const data = await response.json();
55
-
56
- if (response.ok) {
57
- console.log('✅ Success!');
58
- console.log('Response:', data.response);
59
- console.log('Context ID:', data.context_id);
60
- return data;
61
- } else {
62
- console.error('❌ Error:', data.error);
63
- return null;
64
- }
65
- } catch (error) {
66
- console.error('❌ Request failed:', error);
67
- return null;
68
- }
69
-}
70
-
71
-// Call the function
72
-sendMessage().then(result => {
73
- if (result) {
74
- console.log('Message sent successfully!');
75
- }
76
-});
77
-```
78
-
79
-#### Conversation Continuation Example
80
-
81
-```javascript
82
-// Continue conversation example
83
-async function continueConversation(contextId) {
84
- try {
85
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_message', {
86
- method: 'POST',
87
- headers: {
88
- 'Content-Type': 'application/json',
89
- 'X-API-KEY': 'YOUR_API_KEY'
90
- },
91
- body: JSON.stringify({
92
- context_id: contextId,
93
- message: "Can you tell me more about that?",
94
- lifetime_hours: 24
95
- })
96
- });
97
-
98
- const data = await response.json();
99
-
100
- if (response.ok) {
101
- console.log('✅ Continuation Success!');
102
- console.log('Response:', data.response);
103
- return data;
104
- } else {
105
- console.error('❌ Error:', data.error);
106
- return null;
107
- }
108
- } catch (error) {
109
- console.error('❌ Request failed:', error);
110
- return null;
111
- }
112
-}
113
-
114
-// Example: First send a message, then continue the conversation
115
-async function fullConversationExample() {
116
- const firstResult = await sendMessage();
117
- if (firstResult && firstResult.context_id) {
118
- await continueConversation(firstResult.context_id);
119
- }
120
-}
121
-
122
-fullConversationExample();
123
-```
124
-
125
-#### File Attachment Example
126
-
127
-```javascript
128
-// File attachment example
129
-async function sendWithAttachment() {
130
- try {
131
- // Example with text content (convert to base64)
132
- const textContent = "Hello World from attachment!";
133
- const base64Content = btoa(textContent);
134
-
135
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_message', {
136
- method: 'POST',
137
- headers: {
138
- 'Content-Type': 'application/json',
139
- 'X-API-KEY': 'YOUR_API_KEY'
140
- },
141
- body: JSON.stringify({
142
- message: "Please analyze this file:",
143
- attachments: [
144
- {
145
- filename: "document.txt",
146
- base64: base64Content
147
- }
148
- ],
149
- lifetime_hours: 12
150
- })
151
- });
152
-
153
- const data = await response.json();
154
-
155
- if (response.ok) {
156
- console.log('✅ File sent successfully!');
157
- console.log('Response:', data.response);
158
- return data;
159
- } else {
160
- console.error('❌ Error:', data.error);
161
- return null;
162
- }
163
- } catch (error) {
164
- console.error('❌ Request failed:', error);
165
- return null;
166
- }
167
-}
168
-
169
-// Call the function
170
-sendWithAttachment();
171
-```
172
-
173
-#### Project Usage Example
174
-
175
-```javascript
176
-// Working with projects
177
-async function sendMessageWithProject() {
178
- try {
179
- // First message - activate project
180
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_message', {
181
- method: 'POST',
182
- headers: {
183
- 'Content-Type': 'application/json',
184
- 'X-API-KEY': 'YOUR_API_KEY'
185
- },
186
- body: JSON.stringify({
187
- message: "Analyze the project structure",
188
- project_name: "my-web-app" // Activates this project
189
- })
190
- });
191
-
192
- const data = await response.json();
193
-
194
- if (response.ok) {
195
- console.log('✅ Project activated!');
196
- console.log('Context ID:', data.context_id);
197
- console.log('Response:', data.response);
198
-
199
- // Continue conversation - project already set
200
- const followUp = await fetch('YOUR_AGENT_ZERO_URL/api_message', {
201
- method: 'POST',
202
- headers: {
203
- 'Content-Type': 'application/json',
204
- 'X-API-KEY': 'YOUR_API_KEY'
205
- },
206
- body: JSON.stringify({
207
- context_id: data.context_id,
208
- message: "What files are in the project?"
209
- // Do NOT include project_name here - already set on first message
210
- })
211
- });
212
-
213
- const followUpData = await followUp.json();
214
- console.log('Follow-up response:', followUpData.response);
215
- return followUpData;
216
- } else {
217
- console.error('❌ Error:', data.error);
218
- return null;
219
- }
220
- } catch (error) {
221
- console.error('❌ Request failed:', error);
222
- return null;
223
- }
224
-}
225
-
226
-// Call the function
227
-sendMessageWithProject();
228
-```
229
-
230
----
231
-
232
-## `GET/POST /api_log_get`
233
-
234
-Retrieve log data by context ID, limited to a specified number of entries from the newest.
235
-
236
-### API Reference
237
-
238
-**Parameters:**
239
-* `context_id` (string, required): Context ID to get logs from
240
-* `length` (integer, optional): Number of log items to return from newest (default: 100)
241
-
242
-**Headers:**
243
-* `X-API-KEY` (required)
244
-* `Content-Type: application/json` (for POST)
245
-
246
-### JavaScript Examples
247
-
248
-#### GET Request Example
249
-
250
-```javascript
251
-// Get logs using GET request
252
-async function getLogsGET(contextId, length = 50) {
253
- try {
254
- const params = new URLSearchParams({
255
- context_id: contextId,
256
- length: length.toString()
257
- });
258
-
259
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_log_get?' + params, {
260
- method: 'GET',
261
- headers: {
262
- 'X-API-KEY': 'YOUR_API_KEY'
263
- }
264
- });
265
-
266
- const data = await response.json();
267
-
268
- if (response.ok) {
269
- console.log('✅ Logs retrieved successfully!');
270
- console.log('Total items:', data.log.total_items);
271
- console.log('Returned items:', data.log.returned_items);
272
- console.log('Log items:', data.log.items);
273
- return data;
274
- } else {
275
- console.error('❌ Error:', data.error);
276
- return null;
277
- }
278
- } catch (error) {
279
- console.error('❌ Request failed:', error);
280
- return null;
281
- }
282
-}
283
-
284
-// Example usage
285
-getLogsGET('ctx_abc123', 20);
286
-```
287
-
288
-#### POST Request Example
289
-
290
-```javascript
291
-// Get logs using POST request
292
-async function getLogsPOST(contextId, length = 50) {
293
- try {
294
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_log_get', {
295
- method: 'POST',
296
- headers: {
297
- 'Content-Type': 'application/json',
298
- 'X-API-KEY': 'YOUR_API_KEY'
299
- },
300
- body: JSON.stringify({
301
- context_id: contextId,
302
- length: length
303
- })
304
- });
305
-
306
- const data = await response.json();
307
-
308
- if (response.ok) {
309
- console.log('✅ Logs retrieved successfully!');
310
- console.log('Context ID:', data.context_id);
311
- console.log('Log GUID:', data.log.guid);
312
- console.log('Total items:', data.log.total_items);
313
- console.log('Returned items:', data.log.returned_items);
314
- console.log('Start position:', data.log.start_position);
315
- console.log('Progress:', data.log.progress);
316
- console.log('Log items:', data.log.items);
317
- return data;
318
- } else {
319
- console.error('❌ Error:', data.error);
320
- return null;
321
- }
322
- } catch (error) {
323
- console.error('❌ Request failed:', error);
324
- return null;
325
- }
326
-}
327
-
328
-// Example usage - get latest 10 log entries
329
-getLogsPOST('ctx_abc123', 10);
330
-```
331
-
332
----
333
-
334
-## `POST /api_terminate_chat`
335
-
336
-Terminate and remove a chat context to free up resources. Similar to the MCP `finish_chat` function.
337
-
338
-### API Reference
339
-
340
-**Parameters:**
341
-* `context_id` (string, required): Context ID of the chat to terminate
342
-
343
-**Headers:**
344
-* `X-API-KEY` (required)
345
-* `Content-Type: application/json`
346
-
347
-### JavaScript Examples
348
-
349
-#### Basic Termination Examples
350
-
351
-```javascript
352
-// Basic terminate chat function
353
-async function terminateChat(contextId) {
354
- try {
355
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_terminate_chat', {
356
- method: 'POST',
357
- headers: {
358
- 'Content-Type': 'application/json',
359
- 'X-API-KEY': 'YOUR_API_KEY'
360
- },
361
- body: JSON.stringify({
362
- context_id: contextId
363
- })
364
- });
365
-
366
- const data = await response.json();
367
-
368
- if (response.ok) {
369
- console.log('✅ Chat deleted successfully!');
370
- console.log('Message:', data.message);
371
- return data;
372
- } else {
373
- console.error('❌ Error:', data.error);
374
- return null;
375
- }
376
- } catch (error) {
377
- console.error('❌ Request failed:', error);
378
- return null;
379
- }
380
-}
381
-
382
-// Example 1: Terminate a specific chat
383
-terminateChat('ctx_abc123');
384
-
385
-// Example 2: Complete workflow - send message, then terminate
386
-async function simpleWorkflow() {
387
- // Send a message
388
- const result = await sendMessage();
389
-
390
- if (result && result.context_id) {
391
- console.log('Chat created:', result.context_id);
392
-
393
- // Do some work with the chat...
394
- // await continueConversation(result.context_id);
395
-
396
- // Clean up when done
397
- await terminateChat(result.context_id);
398
- console.log('Chat cleaned up');
399
- }
400
-}
401
-
402
-// Run the workflow
403
-simpleWorkflow();
404
-```
405
-
406
----
407
-
408
-## `POST /api_reset_chat`
409
-
410
-Reset a chat context to clear conversation history while keeping the `context_id` alive for continued use.
411
-
412
-### API Reference
413
-
414
-**Parameters:**
415
-* `context_id` (string, required): Context ID of the chat to reset
416
-
417
-**Headers:**
418
-* `X-API-KEY` (required)
419
-* `Content-Type: application/json`
420
-
421
-### JavaScript Examples
422
-
423
-#### Basic Reset Examples
424
-
425
-```javascript
426
-// Basic reset chat function
427
-async function resetChat(contextId) {
428
- try {
429
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_reset_chat', {
430
- method: 'POST',
431
- headers: {
432
- 'Content-Type': 'application/json',
433
- 'X-API-KEY': 'YOUR_API_KEY'
434
- },
435
- body: JSON.stringify({
436
- context_id: contextId
437
- })
438
- });
439
-
440
- const data = await response.json();
441
-
442
- if (response.ok) {
443
- console.log('✅ Chat reset successfully!');
444
- console.log('Message:', data.message);
445
- console.log('Context ID:', data.context_id);
446
- return data;
447
- } else {
448
- console.error('❌ Error:', data.error);
449
- return null;
450
- }
451
- } catch (error) {
452
- console.error('❌ Request failed:', error);
453
- return null;
454
- }
455
-}
456
-
457
-// Example 1: Reset a specific chat
458
-resetChat('ctx_abc123');
459
-
460
-// Example 2: Reset and continue conversation
461
-async function resetAndContinue() {
462
- const contextId = 'ctx_abc123';
463
-
464
- // Reset the chat to clear history
465
- const resetResult = await resetChat(contextId);
466
-
467
- if (resetResult) {
468
- console.log('Chat reset, starting fresh conversation...');
469
-
470
- // Continue with same context_id but fresh history
471
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_message', {
472
- method: 'POST',
473
- headers: {
474
- 'Content-Type': 'application/json',
475
- 'X-API-KEY': 'YOUR_API_KEY'
476
- },
477
- body: JSON.stringify({
478
- context_id: contextId, // Same context ID
479
- message: "Hello, this is a fresh start!",
480
- lifetime_hours: 24
481
- })
482
- });
483
-
484
- const data = await response.json();
485
- console.log('New conversation started:', data.response);
486
- }
487
-}
488
-
489
-// Run the example
490
-resetAndContinue();
491
-```
492
-
493
----
494
-
495
-## `POST /api_files_get`
496
-
497
-Retrieve file contents by paths, returning files as base64 encoded data. Useful for retrieving uploaded attachments.
498
-
499
-### API Reference
500
-
501
-**Parameters:**
502
-* `paths` (array, required): Array of file paths to retrieve (e.g., `["/a0/usr/uploads/file.txt"]`)
503
-
504
-**Headers:**
505
-* `X-API-KEY` (required)
506
-* `Content-Type: application/json`
507
-
508
-### JavaScript Examples
509
-
510
-#### File Retrieval Examples
511
-
512
-```javascript
513
-// Basic file retrieval
514
-async function getFiles(filePaths) {
515
- try {
516
- const response = await fetch('YOUR_AGENT_ZERO_URL/api_files_get', {
517
- method: 'POST',
518
- headers: {
519
- 'Content-Type': 'application/json',
520
- 'X-API-KEY': 'YOUR_API_KEY'
521
- },
522
- body: JSON.stringify({
523
- paths: filePaths
524
- })
525
- });
526
-
527
- const data = await response.json();
528
-
529
- if (response.ok) {
530
- console.log('✅ Files retrieved successfully!');
531
- console.log('Retrieved files:', Object.keys(data));
532
-
533
- // Convert base64 back to text for display
534
- for (const [filename, base64Content] of Object.entries(data)) {
535
- try {
536
- const textContent = atob(base64Content);
537
- console.log(`${filename}: ${textContent.substring(0, 100)}...`);
538
- } catch (e) {
539
- console.log(`${filename}: Binary file (${base64Content.length} chars)`);
540
- }
541
- }
542
-
543
- return data;
544
- } else {
545
- console.error('❌ Error:', data.error);
546
- return null;
547
- }
548
- } catch (error) {
549
- console.error('❌ Request failed:', error);
550
- return null;
551
- }
552
-}
553
-
554
-// Example 1: Get specific files
555
-const filePaths = [
556
- "/a0/usr/uploads/document.txt",
557
- "/a0/usr/uploads/data.json"
558
-];
559
-getFiles(filePaths);
560
-
561
-// Example 2: Complete attachment workflow
562
-async function attachmentWorkflow() {
563
- // Step 1: Send message with attachments
564
- const messageResponse = await fetch('YOUR_AGENT_ZERO_URL/api_message', {
565
- method: 'POST',
566
- headers: {
567
- 'Content-Type': 'application/json',
568
- 'X-API-KEY': 'YOUR_API_KEY'
569
- },
570
- body: JSON.stringify({
571
- message: "Please analyze this file",
572
- attachments: [{
573
- filename: "test.txt",
574
- base64: btoa("Hello, this is test content!")
575
- }],
576
- lifetime_hours: 1
577
- })
578
- });
579
-
580
- if (messageResponse.ok) {
581
- console.log('Message sent with attachment');
582
-
583
- // Step 2: Retrieve the uploaded file
584
- const retrievedFiles = await getFiles(["/a0/usr/uploads/test.txt"]);
585
-
586
- if (retrievedFiles && retrievedFiles["test.txt"]) {
587
- const originalContent = atob(retrievedFiles["test.txt"]);
588
- console.log('Retrieved content:', originalContent);
589
- }
590
- }
591
-}
592
-
593
-// Run the complete workflow
594
-attachmentWorkflow();
595
-```
596
-
597
----
598
-
599
-## MCP Server Connectivity
600
-
601
-Agent Zero includes an MCP Server that allows other MCP-compatible clients to connect to it. The server runs on the same URL and port as the Web UI.
602
-
603
-It provides two endpoint types:
604
-- **SSE (`/mcp/sse`):** For clients that support Server-Sent Events.
605
-- **Streamable HTTP (`/mcp/http/`):** For clients that use streamable HTTP requests.
606
-
607
-> [!NOTE]
608
-> This section describes **Agent Zero as an MCP server**. To configure Agent Zero as an MCP **client** (consuming external tools), see [MCP Setup](../guides/mcp-setup.md).
609
-
610
-### Example MCP Server Configuration
611
-
612
-Below is an example of a `mcp.json` configuration file that a client could use to connect to the Agent Zero MCP server.
613
-
614
-**Note:** You can find your personalized connection URLs under `Settings > MCP Server > MCP Server`.
615
-
616
-```json
617
-{
618
- "mcpServers":
619
- {
620
- "agent-zero": {
621
- "type": "sse",
622
- "url": "YOUR_AGENT_ZERO_URL/mcp/t-YOUR_API_TOKEN/sse"
623
- },
624
- "agent-zero-http": {
625
- "type": "streamable-http",
626
- "url": "YOUR_AGENT_ZERO_URL/mcp/t-YOUR_API_TOKEN/http/"
627
- }
628
- }
629
-}
630
-```
631
-
632
-### Project Support in MCP
633
-
634
-You can specify a project for MCP connections by including it in the URL path:
635
-
636
-```json
637
-{
638
- "mcpServers": {
639
- "agent-zero-with-project": {
640
- "type": "sse",
641
- "url": "YOUR_AGENT_ZERO_URL/mcp/t-YOUR_API_TOKEN/p-my-project-name/sse"
642
- },
643
- "agent-zero-http-with-project": {
644
- "type": "streamable-http",
645
- "url": "YOUR_AGENT_ZERO_URL/mcp/t-YOUR_API_TOKEN/p-my-project-name/http/"
646
- }
647
- }
648
-}
649
-```
650
-
651
-When a project is specified in the URL:
652
-- All new chats will be created within that project context
653
-- The agent will have access to project-specific instructions, knowledge, and file structure
654
-- Attempting to use an existing chat_id from a different project will result in an error
655
-
656
----
657
-
658
-## A2A (Agent-to-Agent) Connectivity
659
-
660
-Agent Zero's A2A Server enables communication with other agents using the FastA2A protocol. Other agents can connect to your instance using the connection URL.
661
-
662
-### A2A Connection URL
663
-
664
-To connect another agent to your Agent Zero instance, use the following URL format.
665
-
666
-**Note:** You can find your specific A2A connection URL under `Settings > External Services > A2A Connection`.
35
+> [!TIP]
36
+> For exact request and response details, check the current source or the
37
+> matching DeepWiki page. That keeps the API reference tied to the code that is
38
+> actually running.
39
668
-```
669
-YOUR_AGENT_ZERO_URL/a2a/t-YOUR_API_TOKEN
670
-```
40
+## MCP And A2A
41
672
-To connect with a specific project active:
42
+Use MCP when you want Agent Zero to call tools from another app or service.
43
674
-```
675
-YOUR_AGENT_ZERO_URL/a2a/t-YOUR_API_TOKEN/p-PROJECT_NAME
676
-```
44
+Use A2A when you want another agent to talk to Agent Zero as a collaborator.
45
678
-When a project is specified:
679
-- All A2A conversations will run in the context of that project
680
-- The agent will have access to project-specific resources, instructions, and knowledge
681
-- This enables project-isolated agent-to-agent communication
46
+Both use the same Agent Zero instance and can be project-aware when configured
47
+that way.
48
683
-### Practical Use Cases
684
-- Connect two Agent Zero instances for long-running, isolated workflows
685
-- Delegate specialized tasks to a dedicated agent instance
686
-- Maintain strict context separation between agents
49
+## Related
50
688
-> [!TIP]
689
-> If you need tool access rather than chat delegation, use MCP instead of A2A. See [MCP Setup](../guides/mcp-setup.md).
51
+- [A0 CLI Connector](../guides/a0-cli-connector.md)
52
+- [MCP Setup](../guides/mcp-setup.md)
53
+- [A2A Setup](../guides/a2a-setup.md)
54
+- [API Integration](../guides/api-integration.md)
55
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
docs/developer/contributing-skills.md
+2
-2
@@ -123,8 +123,8 @@ More instructions...
123
124
## Related Skills
125
126
-- [related-skill-1](../related-skill-1/SKILL.md)
127
-- [related-skill-2](../related-skill-2/SKILL.md)
126
+- `related-skill-1`
127
+- `related-skill-2`
128
```
129
130
### Required Fields
docs/developer/extensions.md
+32
-401
@@ -1,415 +1,46 @@
1
-# Extensions Framework
1
+# Extensions
2
3
-> [!NOTE]
4
-> 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.
3
+Extensions are an advanced way to change how Agent Zero behaves.
4
6
-## Extensible components
7
-- 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.
8
-- This way individual components can be easily replaced, upgraded or extended.
5
+If you are new, start with plugins instead. Plugins are easier to create, test,
6
+disable, and remove.
7
10
-Here's a summary of the extensible components:
8
+Architecture details, extension points, and source-linked explanations now live
9
+in [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). This
10
+local page stays short on purpose.
11
12
-### Extensions
13
-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.
12
+## Start Here
13
15
-#### Extension Points
16
-Agent Zero provides several extension points where custom code can be injected:
14
+| Goal | Start here |
15
+| --- | --- |
16
+| Add a small user-facing feature | [Create a Small Plugin](../guides/create-plugin.md) |
17
+| Change agent behavior for a project | [Projects](../guides/projects.md) |
18
+| Create a specialized agent style | [Agent Profiles](../guides/agent-profiles.md) |
19
+| Study extension internals | [DeepWiki](https://deepwiki.com/agent0ai/agent-zero) |
20
18
-- **agent_init**: Executed when an agent is initialized
19
-- **before_main_llm_call**: Executed before the main LLM call is made
20
-- **message_loop_start**: Executed at the start of the message processing loop
21
-- **message_loop_prompts_before**: Executed before prompts are processed in the message loop
22
-- **message_loop_prompts_after**: Executed after prompts are processed in the message loop
23
-- **message_loop_end**: Executed at the end of the message processing loop
24
-- **monologue_start**: Executed at the start of agent monologue
25
-- **monologue_end**: Executed at the end of agent monologue
26
-- **reasoning_stream**: Executed when reasoning stream data is received
27
-- **response_stream**: Executed when response stream data is received
28
-- **system_prompt**: Executed when system prompts are processed — split into focused extensions (see below)
21
+## When Extensions Make Sense
22
30
-#### Extension Mechanism
31
-The extension mechanism in Agent Zero works through the `call_extensions` function in `agent.py`, which:
23
+Use an extension only when a normal plugin, project instruction, skill, or agent
24
+profile is not enough.
25
33
-1. Loads default extensions from `/python/extensions/{extension_point}/`
34
-2. Loads agent-specific extensions from `/agents/{agent_profile}/extensions/{extension_point}/`
35
-3. Merges them, with agent-specific extensions overriding default ones based on filename
36
-4. Executes each extension in order
26
+Good extension candidates:
27
38
-#### Creating Extensions
39
-To create a custom extension:
28
+- adding behavior at a specific lifecycle point;
29
+- shaping prompts in a reusable way;
30
+- integrating tightly with core tools;
31
+- preparing framework-owned state before a task starts.
32
41
-1. Create a Python class that inherits from the `Extension` base class
42
-2. Implement the `execute` method
43
-3. Place the file in the appropriate extension point directory:
44
- - Default extensions: `/python/extensions/{extension_point}/`
45
- - Agent-specific extensions: `/agents/{agent_profile}/extensions/{extension_point}/`
33
+Avoid extensions for simple UI changes, one-off scripts, or work that should be
34
+easy to remove. A plugin is usually the cleaner home for that.
35
47
-**Example extension:**
36
+## Maintenance Rule
37
49
-```python
50
-# File: /agents/_example/extensions/agent_init/_10_example_extension.py
51
-from helpers.extension import Extension
38
+Keep extension changes small and easy to explain. If a reader needs the full
39
+architecture to understand why the extension exists, link to the relevant
40
+DeepWiki page instead of copying the architecture into this repository.
41
53
-class ExampleExtension(Extension):
54
- async def execute(self, **kwargs):
55
- # rename the agent to SuperAgent0
56
- self.agent.agent_name = "SuperAgent" + str(self.agent.number)
57
-```
42
+## Related
43
59
-#### Extension Override Logic
60
-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.
61
-
62
-For example, if both these files exist:
63
-- `/python/extensions/agent_init/example.py`
64
-- `/agents/my_agent/extensions/agent_init/example.py`
65
-
66
-The version in `/agents/my_agent/extensions/agent_init/example.py` will be used, completely replacing the default version.
67
-
68
-#### System Prompt Extensions
69
-The system prompt is built by multiple focused extensions in `extensions/python/system_prompt/`, each handling one concern:
70
-
71
-| Extension | Section | Decorator |
72
-|-----------|---------|-----------|
73
-| `_10_main_prompt.py` | Main system manual | `@extensible` |
74
-| `_11_tools_prompt.py` | Tool instructions + vision | `@extensible` |
75
-| `_12_mcp_prompt.py` | MCP server tools | `@extensible` |
76
-| `_13_skills_prompt.py` | Available skills | `@extensible` |
77
-| `_13_secrets_prompt.py` | Secrets and variables | `@extensible` |
78
-| `_14_project_prompt.py` | Project context | `@extensible` |
79
-
80
-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.
81
-
82
-The implicit path is composed from the function's full module path and full nested `__qualname__` path:
83
-
84
-- `_functions/<module path>/<qualname path>/start`
85
-- `_functions/<module path>/<qualname path>/end`
86
-
87
-For example, a top-level function `build_prompt` in module `extensions.python.system_prompt._10_main_prompt` maps to:
88
-
89
-- `extensions/python/_functions/extensions/python/system_prompt/_10_main_prompt/build_prompt/start/`
90
-- `extensions/python/_functions/extensions/python/system_prompt/_10_main_prompt/build_prompt/end/`
91
-
92
-For nested callables, every namespace-like segment is kept. For example, `helpers.something -> Outer.Inner.__init__` maps to:
93
-
94
-- `_functions/helpers/something/Outer/Inner/__init__/start`
95
-- `_functions/helpers/something/Outer/Inner/__init__/end`
96
-
97
-This deep directory structure avoids collisions between functions that previously would have been flattened into the same extension point name.
98
-
99
-Numbers `_10`–`_14` run before plugin extensions (which start at `_15`+), ensuring core prompt sections are built first.
100
-
101
-**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:
102
-
103
-```python
104
-# plugins/my_plugin/extensions/python/system_prompt/_09_my_config.py
105
-class MyConfig(Extension):
106
- async def execute(self, **kwargs):
107
- tool_kwargs = self.agent.data.setdefault("_tool_prompt_kwargs", {})
108
- tool_kwargs["agent.system.tool.my_tool.md"] = {"my_var": "value"}
109
-```
110
-
111
-### Tools
112
-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.
113
-
114
-#### Tool Structure
115
-Each tool is implemented as a Python class that inherits from the base `Tool` class. Tools are located in:
116
-- Default tools: `/python/tools/`
117
-- Agent-specific tools: `/agents/{agent_profile}/tools/`
118
-
119
-#### Tool Override Logic
120
-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.
121
-
122
-**Example tool override:**
123
-
124
-```python
125
-# File: /agents/_example/tools/response.py
126
-from helpers.tool import Tool, Response
127
-
128
-# example of a tool redefinition
129
-# the original response tool is in python/tools/response.py
130
-# for the example agent this version will be used instead
131
-
132
-class ResponseTool(Tool):
133
- async def execute(self, **kwargs):
134
- print("Redefined response tool executed")
135
- return Response(message=self.args["text"] if "text" in self.args else self.args["message"], break_loop=True)
136
-```
137
-
138
-#### Tool Execution Flow
139
-When a tool is called, it goes through the following lifecycle:
140
-1. Tool initialization
141
-2. `before_execution` method
142
-3. `execute` method (main functionality)
143
-4. `after_execution` method
144
-
145
-### API Endpoints
146
-API endpoints expose Agent Zero functionality to external systems or the user interface. They are modular and can be extended or replaced.
147
-
148
-API endpoints are located in:
149
-- Default endpoints: `/python/api/`
150
-
151
-Each endpoint is a separate Python file that handles a specific API request.
152
-
153
-### Helpers
154
-Helper modules provide utility functions and shared logic used across the framework. They support the extensibility of other components by providing common functionality.
155
-
156
-Helpers are located in:
157
-- Default helpers: `/python/helpers/`
158
-
159
-### Prompts
160
-Prompts define the instructions and context provided to the LLM. They are highly extensible and can be customized for different agents.
161
-
162
-Prompts are located in:
163
-- Default prompts: `/prompts/`
164
-- Agent-specific prompts: `/agents/{agent_profile}/prompts/`
165
-
166
-> [!NOTE]
167
-> Since v0.9.7, custom prompts should be placed under `agents/<agent_profile>/prompts/` instead of a shared `prompts` subdirectory.
168
-
169
-#### Prompt Features
170
-Agent Zero's prompt system supports several powerful features:
171
-
172
-##### Variable Placeholders
173
-Prompts can include variables using the `{{var}}` syntax. These variables are replaced with actual values when the prompt is processed.
174
-
175
-**Example:**
176
-```markdown
177
-# Current system date and time of user
178
-- current datetime: {{date_time}}
179
-- rely on this info always up to date
180
-```
181
-
182
-##### Dynamic Variable Loaders
183
-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.
184
-
185
-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.
186
-
187
-**Example:**
188
-If you have a prompt file `agent.system.tools.md`, you can create `agent.system.tools.py` alongside it:
189
-
190
-```python
191
-from helpers.files import VariablesPlugin
192
-from helpers import files
193
-
194
-class Tools(VariablesPlugin):
195
- def get_variables(self, file: str, backup_dirs: list[str] | None = None) -> dict[str, Any]:
196
- # Dynamically collect all tool instruction files
197
- folder = files.get_abs_path(os.path.dirname(file))
198
- folders = [folder]
199
- if backup_dirs:
200
- folders.extend([files.get_abs_path(d) for d in backup_dirs])
201
-
202
- prompt_files = files.get_unique_filenames_in_dirs(folders, "agent.system.tool.*.md")
203
-
204
- tools = []
205
- for prompt_file in prompt_files:
206
- tool = files.read_file(prompt_file)
207
- tools.append(tool)
208
-
209
- return {"tools": "\n\n".join(tools)}
210
-```
211
-
212
-Then in your `agent.system.tools.md` prompt file, you can use:
213
-```markdown
214
-# Available Tools
215
-{{tools}}
216
-```
217
-
218
-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.
219
-
220
-##### File Includes
221
-Prompts can include content from other prompt files using the `{{ include "path/to/file.md" }}` syntax. This allows for modular prompt design and reuse.
222
-
223
-**Example:**
224
-```markdown
225
-# Agent Zero System Manual
226
-
227
-{{ include "agent.system.main.role.md" }}
228
-
229
-{{ include "agent.system.main.environment.md" }}
230
-
231
-{{ include "agent.system.main.communication.md" }}
232
-```
233
-
234
-##### Include Original
235
-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.
236
-
237
-**Example:** Override `agents/developer/prompts/agent.system.main.communication.md`:
238
-```markdown
239
-{{include original}}
240
-
241
-- always explain your reasoning
242
-- include code snippets in responses
243
-```
244
-
245
-This resolves to: find `agent.system.main.communication.md` in the next directory up the hierarchy → finds the default in `prompts/` → includes it. Result:
246
-
247
-```markdown
248
-## Communication
249
-- be concise
250
-- use markdown formatting
251
-- ask clarifying questions when unsure
252
-
253
-- always explain your reasoning
254
-- include code snippets in responses
255
-```
256
-
257
-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.
258
-
259
-##### Agent Specifics File
260
-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.
261
-
262
-**Example:** `agents/developer/prompts/agent.system.main.specifics.md`:
263
-```markdown
264
-## Developer specifics
265
-- always use git branches for new features
266
-- prefer Python 3.12+ syntax
267
-- run tests before committing
268
-```
269
-
270
-#### Prompt Override Logic
271
-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.
272
-
273
-**Example of a prompt override:**
274
-
275
-```markdown
276
-> !!!
277
-> This is an example prompt file redefinition.
278
-> The original file is located at /prompts.
279
-> Only copy and modify files you need to change, others will stay default.
280
-> !!!
281
-
282
-## Your role
283
-You are Agent Zero, a sci-fi character from the movie "Agent Zero".
284
-```
285
-
286
-This example overrides the default role definition in `/prompts/agent.system.main.role.md` with a custom one for a specific agent profile.
287
-
288
-## Subagent Customization
289
-Agent Zero supports creating specialized subagents with customized behavior. The `_example` agent in the `/agents/_example/` directory demonstrates this pattern.
290
-
291
-### Creating a Subagent
292
-
293
-1. Create a directory in `/usr/agents/{agent_profile}/` for user-created profiles, or `/agents/{agent_profile}/` only for built-in framework profiles.
294
-2. Override or extend default components by mirroring the structure in the root directories:
295
- - `/usr/agents/{agent_profile}/agent.yaml` - required profile metadata
296
- - `/usr/agents/{agent_profile}/extensions/` - custom extensions
297
- - `/usr/agents/{agent_profile}/tools/` - custom tools
298
- - `/usr/agents/{agent_profile}/prompts/` - custom prompts
299
-
300
-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:
301
-
302
-```text
303
-/a0/usr/agents/{agent_profile}/plugins/_model_config/config.json
304
-```
305
-
306
-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](../guides/agent-profiles.md) for details.
307
-
308
-### Example Subagent Structure
309
-
310
-```
311
-/usr/agents/my-profile/
312
-├── agent.yaml
313
-├── extensions/
314
-│ └── agent_init/
315
-│ └── _10_example_extension.py
316
-├── prompts/
317
-│ └── ...
318
-├── tools/
319
-│ ├── example_tool.py
320
-│ └── response.py
321
-└── plugins/
322
- └── _model_config/
323
- └── config.json
324
-```
325
-
326
-In this example:
327
-- `_10_example_extension.py` is an extension that renames the agent when initialized
328
-- `response.py` overrides the default response tool with custom behavior
329
-- `example_tool.py` is a new tool specific to this agent
330
-- `plugins/_model_config/config.json` optionally gives this profile its own Main, Utility, and Embedding model settings
331
-
332
-## Projects
333
-
334
-Projects provide isolated workspaces for individual chats, keeping prompts, memory, knowledge, files, and secrets scoped to a specific use case.
335
-
336
-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.
337
-
338
-### Project Location and Structure
339
-
340
-- Projects are located under `/a0/usr/projects/`
341
-- Each project has its own subdirectory, created by users via the UI
342
-- A project can be backed up or restored by copying or downloading its entire directory
343
-
344
-Each project directory contains a hidden `.a0proj` folder with project metadata and configuration:
345
-
346
-```
347
-/a0/usr/projects/{project_name}/
348
-└── .a0proj/
349
- ├── project.json # project metadata and settings
350
- ├── instructions/ # additional prompt/instruction files
351
- ├── knowledge/ # files to be imported into memory
352
- ├── memory/ # project-specific memory storage
353
- ├── plugins/ # project-scoped plugin configuration
354
- ├── secrets.env # sensitive variables (secrets)
355
- └── variables.env # non-sensitive variables
356
-```
357
-
358
-### Behavior When a Project Is Active in a Chat
359
-
360
-When a project is activated for a chat:
361
-
362
-- The agent is instructed to work **inside the project directory**
363
-- Project prompts (instructions) from `.a0proj/instructions/` are **automatically injected** into the context window (all text files are imported)
364
-- Memory can be configured as **project-specific**, meaning:
365
- - It does not mix with global memory
366
- - The memory file is stored under `.a0proj/memory/`
367
-- Files created or modified by the agent are located within the project directory
368
-
369
-The `.a0proj/knowledge/` folder contains files that are imported into the project’s memory, enabling project-focused knowledge bases.
370
-
371
-### Secrets and Variables
372
-
373
-Each project manages its own configuration values via environment files in `.a0proj/`:
374
-
375
-- `secrets.env` – **sensitive variables**, such as API keys or passwords
376
-- `variables.env` – **non-sensitive variables**, such as configuration flags or identifiers
377
-
378
-These files allow you to keep credentials and configuration tightly scoped to a single project.
379
-
380
-Plugin-owned project configuration is stored under `.a0proj/plugins/<plugin_name>/`. For example, `_model_config` stores project model settings and project-only presets here:
381
-
382
-```text
383
-/a0/usr/projects/{project_name}/.a0proj/plugins/_model_config/config.json
384
-/a0/usr/projects/{project_name}/.a0proj/plugins/_model_config/presets.yaml
385
-```
386
-
387
-The `_model_config/presets.yaml` file is a plain YAML list:
388
-
389
-```yaml
390
-- name: Research
391
- chat:
392
- provider: openrouter
393
- name: anthropic/claude-sonnet-4.6
394
- utility:
395
- provider: openrouter
396
- name: openai/gpt-5.4-mini
397
-```
398
-
399
-### When to Use Projects
400
-
401
-Projects are the recommended way to create specialized workflows in Agent Zero when you need to:
402
-
403
-- Add specific instructions without affecting global behavior
404
-- Isolate file context, knowledge, and memory for a particular task or client
405
-- Keep passwords and other secrets scoped to a single workspace
406
-- Run multiple independent flows side by side under the same Agent Zero installation
407
-
408
-See [Usage → Tasks & Scheduling](../guides/usage.md#tasks--scheduling) for how to pair projects with scheduled tasks.
409
-
410
-## Best Practices
411
-- Keep extensions focused on a single responsibility
412
-- Use the appropriate extension point for your functionality
413
-- Leverage existing helpers rather than duplicating functionality
414
-- Test extensions thoroughly to ensure they don't interfere with core functionality
415
-- Document your extensions to make them easier to maintain and share
44
+- [Create a Small Plugin](../guides/create-plugin.md)
45
+- [Agent Profiles](../guides/agent-profiles.md)
46
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
docs/developer/mcp-configuration.md
+40
-364
@@ -1,50 +1,14 @@
1
# Advanced MCP Configuration
2
3
-This guide provides comprehensive technical details for configuring and utilizing external tool providers through the Model Context Protocol (MCP) with Agent Zero. This allows Agent Zero to leverage tools hosted by separate local or remote MCP-compliant servers.
3
+Most users should start with [MCP Setup](../guides/mcp-setup.md).
4
5
-> [!NOTE]
6
-> For a quick start guide on adding MCP servers through the UI, see [MCP Setup](../guides/mcp-setup.md).
5
+This page is for people who need to paste or review MCP JSON by hand. MCP
6
+architecture and source-linked internals live in
7
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
8
8
-> [!NOTE]
9
-> This guide covers Agent Zero as an MCP **client**. To expose Agent Zero as an MCP **server**, see [Connectivity → MCP Server](connectivity.md#mcp-server-connectivity).
9
+## Basic Shape
10
11
-## MCP Server Types
12
-
13
-Agent Zero supports three main types of MCP servers:
14
-
15
-1. **Local Stdio Servers**: Local executables that Agent Zero communicates with via standard input/output (stdio).
16
-2. **Remote SSE Servers**: Network-accessible servers that use Server-Sent Events (SSE), usually over HTTP/S.
17
-3. **Remote Streaming HTTP Servers**: Servers using the streamable HTTP transport protocol for MCP communication.
18
-
19
-## How Agent Zero Consumes MCP Tools
20
-
21
-Agent Zero discovers and integrates MCP tools dynamically through the following process:
22
-
23
-1. **Configuration**: MCP servers are defined in the Agent Zero configuration, primarily through the Settings UI.
24
-2. **Saving Settings**: When saved via the UI, Agent Zero updates `usr/settings.json`, specifically the `"mcp_servers"` key.
25
-3. **Server Startup**: Agent Zero initializes configured MCP servers (stdio) or connects to them (remote). For `npx`/`uvx` based servers, the first run downloads packages.
26
-4. **Tool Discovery**: Upon initialization, Agent Zero connects to each enabled MCP server and queries for available tools, descriptions, and parameters.
27
-5. **Dynamic Prompting**: Tool information is injected into the agent's system prompt. The `{{tools}}` placeholder in templates (e.g., `prompts/agent.system.mcp_tools.md`) is replaced with the formatted tool list.
28
-6. **Tool Invocation**: When the LLM requests an MCP tool, Agent Zero's `process_tools` method (`mcp_handler.py`) routes the request to the appropriate MCP server.
29
-
30
-## Configuration File Structure
31
-
32
-### Settings Location
33
-
34
-MCP server configurations are stored in:
35
-- `usr/settings.json` (primary storage)
36
-
37
-### The `mcp_servers` Setting
38
-
39
-Within `usr/settings.json`, MCP servers are defined under the `"mcp_servers"` key:
40
-
41
-- **Value Type**: JSON formatted string containing:
42
- - A JSON object with `"mcpServers"` (recommended, matches UI)
43
- - Or a JSON array of server configurations
44
-- **Default Value**: Empty config (`{"mcpServers": {}}`)
45
-- **Manual Editing**: While UI configuration is recommended, manual editing is possible. Ensure proper JSON string formatting with escaped quotes.
46
-
47
-### Recommended Configuration Format
11
+Command-based MCP tool:
12
13
```json
14
{
@@ -52,353 +16,65 @@ Within `usr/settings.json`, MCP servers are defined under the `"mcp_servers"` ke
16
"sqlite": {
17
"command": "uvx",
18
"args": ["mcp-server-sqlite", "--db-path", "/root/db.sqlite"]
55
- },
56
- "deep-wiki": {
57
- "description": "Use this MCP to analyze GitHub repositories",
58
- "url": "https://mcp.deepwiki.com/sse"
19
}
20
}
21
}
22
```
23
64
-> [!NOTE]
65
-> In `usr/settings.json`, the entire `"mcp_servers"` value is stored as a single string. The Settings UI handles escaping automatically.
66
-
67
-### Upgrading Existing Installations
68
-
69
-For existing `settings.json` files without MCP support:
70
-
71
-1. Ensure you're running a version with MCP support
72
-2. Open the settings UI
73
-3. Save settings (even without changes)
74
-4. This writes the complete settings structure including `"mcp_servers": ""`
75
-5. Configure servers via UI or careful manual editing
76
-
77
-## Server Configuration Templates
78
-
79
-### 1. Local Stdio Server
80
-
81
-```json
82
-{
83
- "name": "My Local Tool Server",
84
- "description": "Optional: A brief description of this server.",
85
- "type": "stdio",
86
- "command": "python",
87
- "args": ["path/to/your/mcp_stdio_script.py", "--some-arg"],
88
- "env": {
89
- "PYTHONPATH": "/path/to/custom/libs:.",
90
- "ANOTHER_VAR": "value"
91
- },
92
- "encoding": "utf-8",
93
- "encoding_error_handler": "strict",
94
- "disabled": false
95
-}
96
-```
97
-
98
-**Configuration Fields:**
99
-- `type`: Optional, auto-detected. Can be `"stdio"`, `"sse"`, or streaming variants
100
-- `command`: **Required**. The executable to run
101
-- `args`: Optional list of command arguments
102
-- `env`: Optional environment variables for the process
103
-- `encoding`: Optional, default `"utf-8"`
104
-- `encoding_error_handler`: Optional, can be `"strict"`, `"ignore"`, or `"replace"`
105
-
106
-### 2. Remote SSE Server
107
-
108
-```json
109
-{
110
- "name": "My Remote API Tools",
111
- "description": "Optional: Description of the remote SSE server.",
112
- "type": "sse",
113
- "url": "https://api.example.com/mcp-sse-endpoint",
114
- "headers": {
115
- "Authorization": "Bearer YOUR_API_KEY_OR_TOKEN",
116
- "X-Custom-Header": "some_value"
117
- },
118
- "timeout": 5.0,
119
- "sse_read_timeout": 300.0,
120
- "disabled": false
121
-}
122
-```
123
-
124
-**Configuration Fields:**
125
-- `url`: **Required**. Full URL for the SSE endpoint
126
-- `headers`: Optional HTTP headers for authentication/custom headers
127
-- `timeout`: Optional connection timeout in seconds (default: 5.0)
128
-- `sse_read_timeout`: Optional read timeout for SSE stream (default: 300.0)
129
-
130
-### 3. Remote Streaming HTTP Server
131
-
132
-```json
133
-{
134
- "name": "My Streaming HTTP Tools",
135
- "description": "Optional: Description of the remote streaming HTTP server.",
136
- "type": "streaming-http",
137
- "url": "https://api.example.com/mcp-http-endpoint",
138
- "headers": {
139
- "Authorization": "Bearer YOUR_API_KEY_OR_TOKEN",
140
- "X-Custom-Header": "some_value"
141
- },
142
- "timeout": 5.0,
143
- "sse_read_timeout": 300.0,
144
- "disabled": false
145
-}
146
-```
147
-
148
-**Streaming HTTP Variants:**
149
-Type can be: `"http-stream"`, `"streaming-http"`, `"streamable-http"`, or `"http-streaming"`
150
-
151
-### Example in settings.json
152
-
153
-```json
154
-{
155
- "mcp_servers": "[{'name': 'MyPythonTools', 'command': 'python3', 'args': ['mcp_scripts/my_server.py'], 'disabled': false}, {'name': 'ExternalAPI', 'url': 'https://data.example.com/mcp', 'headers': {'X-Auth-Token': 'supersecret'}, 'disabled': false}]"
156
-}
157
-```
158
-
159
-## Key Configuration Fields
160
-
161
-### Common Fields
162
-
163
-- **`name`**: Unique server identifier. Used to prefix tools (e.g., `server_name.tool_name`). Normalized internally (lowercase, spaces/hyphens → underscores)
164
-- **`type`**: Optional explicit type. Auto-detected if omitted based on `command` (stdio) or `url` (defaults to sse)
165
-- **`disabled`**: Boolean. Set `true` to ignore this server without removing configuration
166
-- **`description`**: Optional human-readable description
167
-
168
-### Type-Specific Required Fields
169
-
170
-- **Stdio servers**: Require `command`
171
-- **Remote servers**: Require `url`
172
-
173
-## Docker Networking Considerations
174
-
175
-### Agent Zero in Docker, MCP Server on Host
176
-
177
-**macOS/Windows:**
178
-```json
179
-{
180
- "url": "http://host.docker.internal:PORT/endpoint"
181
-}
182
-```
183
-
184
-**Linux:**
185
-- Run MCP server in the same Docker network
186
-- Reference by container name: `http://container_name:PORT/endpoint`
187
-
188
-### Remote MCP Servers
189
-
190
-Use standard HTTPS URLs:
191
-```json
192
-{
193
- "url": "https://api.example.com/mcp-endpoint"
194
-}
195
-```
196
-
197
-## Using MCP Tools
198
-
199
-### Tool Naming Convention
200
-
201
-MCP tools are prefixed with the normalized server name:
202
-
203
-- Server name: `"sequential-thinking"`
204
-- Tool name from server: `"run_chain"`
205
-- Final tool name in Agent Zero: `sequential_thinking.run_chain`
206
-
207
-### Agent Interaction
208
-
209
-Instruct the agent to use MCP tools directly:
210
-
211
-```
212
-"Agent, use the sequential_thinking.run_chain tool with the following input..."
213
-```
214
-
215
-The LLM formulates the appropriate JSON request automatically.
216
-
217
-### Execution Flow
218
-
219
-1. `process_tools` method receives tool request
220
-2. `mcp_handler.py` checks if tool name exists in `MCPConfig`
221
-3. If found: delegates to corresponding MCP server
222
-4. If not found: attempts to find built-in tool with that name
223
-
224
-This prioritization allows MCP tools to extend or override built-in functionality.
225
-
226
-## Troubleshooting
227
-
228
-### Server Not Connecting
229
-
230
-**Check status in UI:**
231
-- Settings → MCP/A2A → External MCP Servers
232
-- Green indicator = connected
233
-- Red indicator = connection failed
234
-
235
-**Common issues:**
236
-- Wrong URL or port
237
-- Missing authentication headers
238
-- Network/firewall blocking connection
239
-- Server not running
240
-
241
-### Tools Not Appearing
242
-
243
-**Verification steps:**
244
-1. Confirm server shows as connected (green status)
245
-2. Check server exposes tools (count shown in UI)
246
-3. Verify tool names match server documentation
247
-4. For `npx`/`uvx` servers, first run downloads packages (may take time)
248
-
249
-### Encoding Issues (Stdio Servers)
250
-
251
-Adjust encoding settings:
252
-```json
253
-{
254
- "encoding": "utf-8",
255
- "encoding_error_handler": "replace"
256
-}
257
-```
258
-
259
-Error handler options:
260
-- `"strict"`: Fail on encoding errors (default)
261
-- `"ignore"`: Skip problematic characters
262
-- `"replace"`: Replace with placeholder character
263
-
264
-## Security Considerations
265
-
266
-### API Keys and Secrets
267
-
268
-Store sensitive data securely:
269
-- Use environment variables when possible
270
-- Avoid committing secrets to version control
271
-- Use header-based authentication for remote servers
272
-
273
-### Network Security
274
-
275
-- Use HTTPS for remote MCP servers
276
-- Validate SSL certificates (default behavior)
277
-- Restrict network access to trusted servers only
278
-
279
-### Local Stdio Servers
280
-
281
-- Only run trusted executables
282
-- Review server code before execution
283
-- Use environment isolation when possible
284
-
285
-## Performance Optimization
286
-
287
-### Connection Timeouts
288
-
289
-Adjust for network conditions:
290
-```json
291
-{
292
- "timeout": 10.0, // Initial connection
293
- "sse_read_timeout": 600.0 // Long-running operations
294
-}
295
-```
296
-
297
-### Server Pooling
298
-
299
-For high-frequency tool usage:
300
-- Agent Zero maintains persistent connections to remote servers
301
-- Stdio servers are kept alive between tool calls
302
-- Reduces overhead for repeated operations
303
-
304
-## Advanced Examples
305
-
306
-### Multi-Server Configuration
24
+URL-based MCP tool:
25
26
```json
27
{
28
"mcpServers": {
311
- "browser": {
312
- "command": "npx",
313
- "args": ["-y", "chrome-devtools-mcp@latest"]
314
- },
315
- "database": {
316
- "command": "uvx",
317
- "args": ["mcp-server-sqlite", "--db-path", "/data/app.db"]
318
- },
29
"external-api": {
30
"url": "https://api.example.com/mcp",
31
"headers": {
322
- "Authorization": "Bearer token123"
323
- }
324
- },
325
- "backup-api": {
326
- "url": "https://backup.example.com/mcp",
327
- "disabled": true
328
- }
329
- }
330
-}
331
-```
332
-
333
-### Custom Environment Variables
334
-
335
-```json
336
-{
337
- "mcpServers": {
338
- "python-tools": {
339
- "command": "python3",
340
- "args": ["/opt/tools/mcp_server.py"],
341
- "env": {
342
- "PYTHONPATH": "/opt/libs:/usr/local/lib/python3.9",
343
- "API_KEY": "secret_key",
344
- "DEBUG": "true"
32
+ "Authorization": "Bearer YOUR_API_KEY"
33
}
34
}
35
}
36
}
37
```
38
351
-## Integration Patterns
352
-
353
-### Tool Composition
354
-
355
-Combine multiple MCP servers for complex workflows:
356
-1. Browser MCP for data extraction
357
-2. Database MCP for storage
358
-3. Workflow MCP for orchestration
359
-
360
-Agent Zero can chain these tools automatically based on task requirements.
39
+## Common Fields
40
362
-### Fallback Configuration
363
-
364
-```json
365
-{
366
- "mcpServers": {
367
- "primary-service": {
368
- "url": "https://primary.example.com/mcp"
369
- },
370
- "fallback-service": {
371
- "url": "https://fallback.example.com/mcp",
372
- "disabled": true
373
- }
374
- }
375
-}
376
-```
41
+| Field | Meaning |
42
+| --- | --- |
43
+| `command` | Starts a local MCP tool from a command. |
44
+| `args` | Arguments passed to that command. |
45
+| `url` | Connects to an MCP tool that is already running. |
46
+| `headers` | Optional HTTP headers, often used for authentication. |
47
+| `env` | Optional environment variables for command-based tools. |
48
+| `disabled` | Temporarily turns one MCP entry off. |
49
378
-Enable fallback manually when primary service is unavailable.
50
+Use `command` for local tools and `url` for tools that are already running
51
+somewhere else.
52
380
-## Development and Testing
53
+## Docker Addresses
54
382
-### Testing MCP Configurations
55
+If Agent Zero runs in Docker, remember that "localhost" means the container, not
56
+always your host machine.
57
384
-1. Add server with `disabled: false`
385
-2. Save and check connection status
386
-3. Test individual tools via agent prompts
387
-4. Monitor logs for errors
388
-5. Adjust configuration as needed
58
+| Where the MCP tool runs | Address to use from Agent Zero |
59
+| --- | --- |
60
+| Host machine on macOS or Windows | `host.docker.internal` |
61
+| Another container | The container name on the same Docker network |
62
+| Remote machine | Its reachable HTTPS URL |
63
+| Inside Agent Zero's container | A command-based config |
64
390
-### Creating Custom MCP Servers
65
+On Linux, `host.docker.internal` may need extra Docker setup. Running the MCP
66
+tool in the same Docker network is often simpler.
67
392
-For developing custom MCP servers:
393
-- Follow MCP protocol specifications
394
-- Implement stdio or HTTP transport
395
-- Provide clear tool descriptions
396
-- Test with Agent Zero before production
68
+## Safety
69
398
-See [MCP Protocol Documentation](https://modelcontextprotocol.io) for implementation details.
70
+- Use MCP tools you trust.
71
+- Keep real API keys out of public screenshots and repositories.
72
+- Prefer project secrets or environment variables for credentials.
73
+- Remove MCP tools you no longer use.
74
400
-## Related Documentation
75
+## Related
76
402
-- [MCP Setup](../guides/mcp-setup.md) - Quick start guide
403
-- [Connectivity: MCP Server](connectivity.md#mcp-server-connectivity) - Exposing Agent Zero as MCP server
404
-- [Advanced: Extensions](extensions.md) - Custom tools and extensions
77
+- [MCP Setup](../guides/mcp-setup.md)
78
+- [Browser Guide](../guides/browser.md)
79
+- [A0 CLI Connector](../guides/a0-cli-connector.md)
80
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
docs/developer/notifications.md
+1
-1
@@ -3,7 +3,7 @@
3
Quick guide for using the notification system in Agent Zero.
4
5
> [!TIP]
6
-> Notifications pair well with scheduled tasks. See [Tasks & Scheduling](../guides/usage.md#tasks--scheduling) for automation patterns.
6
+> Notifications pair well with scheduled tasks. See [Tasks & Scheduling](../guides/usage.md#tasks-and-scheduling) for automation patterns.
7
8
## Backend Usage
9
docs/developer/plugins.md
+35
-308
@@ -1,333 +1,60 @@
1
# Plugins
2
3
-This page documents the current Agent Zero plugin system, including manifest format, discovery rules, scoped configuration, activation behavior, and how to share a plugin with the community.
3
+Most people should start with the practical guide:
4
+[Create a Small Plugin](../guides/create-plugin.md).
5
5
-## Overview
6
+Plugin architecture and source-linked internals live in
7
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). This page
8
+stays intentionally small so the repository does not maintain a second plugin
9
+manual.
10
7
-Plugins extend Agent Zero through convention-based folders. A plugin can provide:
11
+## What To Use
12
9
-- Backend: API handlers, tools, helpers, Python lifecycle extensions, and implicit `@extensible` hooks
10
-- Frontend: WebUI components and extension-point injections
11
-- Agent profiles: plugin-scoped subagent definitions
12
-- Settings: scoped plugin configuration loaded through the plugin settings store
13
-- Activation control: global and per-scope ON/OFF rules
13
+| Goal | Start here |
14
+| --- | --- |
15
+| Build your first plugin | [Create a Small Plugin](../guides/create-plugin.md) |
16
+| Understand how plugins are loaded | [DeepWiki](https://deepwiki.com/agent0ai/agent-zero) |
17
+| Decide what is safe to publish | [Sharing and Safety](sharing-and-safety.md) |
18
+| Contribute a plugin upstream | [Contributing Guide](../guides/contribution.md) |
19
15
-Primary roots (priority order):
20
+## Minimum Local Plugin
21
17
-1. `usr/plugins/` (user/custom plugins)
18
-2. `plugins/` (core/built-in plugins)
19
-
20
-On name collisions, user plugins take precedence.
21
-
22
-## Manifest (`plugin.yaml`)
23
-
24
-Every plugin must contain `plugin.yaml`. This is the **runtime manifest** — it drives Agent Zero behavior. It is distinct from the index manifest used when publishing to the Plugin Index (see [Publishing to the Plugin Index](#publishing-to-the-plugin-index) below).
25
-
26
-```yaml
27
-name: my_plugin # required for community plugins (^[a-z0-9_]+$, must match dir name)
28
-title: My Plugin
29
-description: What this plugin does.
30
-version: 1.0.0
31
-settings_sections:
32
- - agent
33
-per_project_config: false
34
-per_agent_config: false
35
-always_enabled: false
36
-```
37
-
38
-Field reference:
39
-
40
-- `name`: plugin identifier; required by CI for index submission; must be `^[a-z0-9_]+$` and match the index folder name exactly
41
-- `title`: UI display name
42
-- `description`: short plugin summary
43
-- `version`: plugin version string
44
-- `settings_sections`: where plugin settings appear (`agent`, `external`, `mcp`, `developer`, `backup`)
45
-- `per_project_config`: enables project-scoped settings/toggles
46
-- `per_agent_config`: enables agent-profile-scoped settings/toggles
47
-- `always_enabled`: forces ON state and disables toggle controls
48
-
49
-## Recommended Structure
22
+A local plugin usually lives here:
23
24
```text
52
-usr/plugins/<plugin_name>/
25
+/a0/usr/plugins/<plugin_name>/
26
├── plugin.yaml
54
-├── execute.py # optional user-triggered plugin script
55
-├── hooks.py # optional runtime hook functions callable by the framework
56
-├── default_config.yaml # optional defaults
57
-├── README.md # optional locally; strongly recommended for community plugins
58
-├── LICENSE # optional locally (shown in Plugin List UI when present); required at repo root for Plugin Index submission
59
-├── api/ # ApiHandler implementations
60
-├── tools/ # Tool implementations
61
-├── helpers/ # shared Python logic
62
-├── prompts/
63
-├── agents/
64
-│ └── <profile>/agent.yaml # optional plugin-distributed agent profile
65
-├── extensions/
66
-│ ├── python/<extension_point>/
67
-│ ├── python/_functions/<module>/<qualname>/<start|end>/
68
-│ └── webui/<extension_point>/
27
+├── README.md
28
└── webui/
70
- ├── config.html # optional settings UI
71
- └── ...
29
```
30
74
-## Python Extension Layouts
75
-
76
-Use one of these backend layouts:
77
-
78
-- `extensions/python/<extension_point>/` for named lifecycle hooks such as `agent_init`, `system_prompt`, or `tool_execute_before`
79
-- `extensions/python/_functions/<module>/<qualname>/<start|end>/` for implicit `@extensible` hook targets
80
-
81
-The `_functions` layout keeps the full module path and nested `__qualname__` path, which avoids collisions between similarly named functions. Do not create the retired flattened form `extensions/python/<module>_<qualname>_<start|end>/`; it is stale and will not be resolved by the current extensible system.
82
-
83
-## Python Imports for User Plugins
84
-
85
-For plugin-local Python imports inside `usr/plugins/<plugin_name>/`, use the
86
-fully qualified `usr.plugins.<plugin_name>...` path.
87
-
88
-Good:
89
-
90
-```python
91
-from usr.plugins.my_plugin.helpers.runtime import do_work
92
-import usr.plugins.my_plugin.helpers.state as state
93
-```
94
-
95
-Avoid:
96
-
97
-```python
98
-sys.path.insert(0, ...)
99
-from helpers.runtime import do_work
100
-
101
-from plugins.my_plugin.helpers.runtime import do_work
102
-```
103
-
104
-This is the preferred pattern because it keeps plugin imports explicit,
105
-requires no directory renaming like `name_helpers`, requires no symlink into
106
-`plugins/`, and leaves no global import hack behind when the plugin is deleted.
107
-
108
-## Plugin Script (`execute.py`)
109
-
110
-Plugins can include an optional `execute.py` at the plugin root for user-triggered operations such as setup, post-install actions, maintenance, repair steps, or other manual tasks that should run only when explicitly requested.
111
-
112
-- Triggered manually from the Plugin List UI — never runs automatically
113
-- Suitable for rerunnable operations such as refreshing caches, rebuilding generated files, running migrations, or syncing plugin-managed resources
114
-- Execution state is recorded per plugin with timestamp and exit code metadata
115
-- The modal streams output in real time and shows success/failure on completion
116
-
117
-```python
118
-import subprocess
119
-import sys
120
-
121
-def main():
122
- print("Installing dependencies...")
123
- result = subprocess.run(
124
- [sys.executable, "-m", "pip", "install", "requests==2.31.0"],
125
- text=True,
126
- )
127
- if result.returncode != 0:
128
- print("ERROR: Installation failed")
129
- return result.returncode
130
- print("Refreshing plugin resources...")
131
- print("Done.")
132
- return 0
133
-
134
-if __name__ == "__main__":
135
- sys.exit(main())
136
-```
137
-
138
-Return `0` on success, non-zero on failure. Print progress for user feedback. Use `sys.executable` for pip commands. Prefer making the script safe to run more than once; if reruns are not safe, detect the current state and print a clear explanation.
139
-
140
-First rule of plugin side effects: do not modify the system permanently unless
141
-the user explicitly asked for it and the plugin also provides a cleanup path.
142
-Deleting a plugin should not leave behind symlinks, orphaned services,
143
-framework patches, or unmanaged files outside plugin-owned locations.
144
-
145
-## Runtime Hooks (`hooks.py`)
146
-
147
-Plugins can also include an optional `hooks.py` at the plugin root. Agent Zero loads this module on demand and calls exported functions by name through `helpers.plugins.call_plugin_hook(...)`.
148
-
149
-- `hooks.py` executes inside the **Agent Zero framework runtime and Python environment**.
150
-- Use it for framework-internal operations such as install hooks, pre-update hooks, registration, cache preparation, file setup, or other work that needs direct access to framework internals.
151
-- Hook functions may be synchronous or async.
152
-- Hook modules are cached, so edits may require a plugin refresh or cache clear before changes are picked up.
153
-- Hooks should be reversible and cleanup-safe. Prefer plugin-owned paths and framework-managed state over permanent system modifications.
154
-
155
-Use `execute.py` when the user should explicitly decide when the operation runs. Use `hooks.py` or lifecycle extensions when the work belongs to framework-managed behavior.
156
-
157
-Current built-in usage:
158
-- the plugin installer calls `install()` from `hooks.py` after copying a plugin into place
159
-- the plugin updater calls `pre_update()` from `hooks.py` immediately before pulling new plugin code into place
160
-
161
-### Dependency and environment behavior
162
-
163
-- If `hooks.py` runs `sys.executable -m pip install ...`, it installs into the **same Python environment that is currently running Agent Zero**.
164
-- That is the correct target for dependencies needed by your plugin's backend code inside the framework runtime.
165
-- It is not automatically the right target for packages intended only for the separate agent execution runtime or for system-level binaries.
166
-
167
-If you need to install into a different environment, do it explicitly from a subprocess. In practice, that means targeting the correct interpreter or activating the correct environment inside the subprocess before running `pip` or another package manager.
168
-
169
-Examples of the right approach:
170
-
171
-- call a specific Python executable for the target runtime
172
-- activate the target virtualenv in a subprocess shell command before invoking `pip`
173
-- run OS-level package installation from a subprocess prepared for the intended environment
174
-
175
-In Docker deployments, `hooks.py` normally affects the framework runtime at `/opt/venv-a0`, while the agent execution runtime is `/opt/venv`.
31
+The smallest useful `plugin.yaml` looks like this:
32
177
-## Settings Resolution
178
-
179
-Plugin settings are resolved by scope. Higher priority overrides lower priority:
180
-
181
-1. `project/.a0proj/agents/<profile>/plugins/<name>/config.json`
182
-2. `project/.a0proj/plugins/<name>/config.json`
183
-3. `usr/agents/<profile>/plugins/<name>/config.json`
184
-4. `usr/plugins/<name>/config.json`
185
-5. `plugins/<name>/default_config.yaml` (fallback defaults)
186
-
187
-Notes:
188
-
189
-- Runtime reads support JSON and YAML fallback files.
190
-- Save path is scope-specific and persisted through plugin settings APIs.
191
-
192
-## Activation Model
193
-
194
-Activation is independent per scope and file-based:
195
-
196
-- `.toggle-1` means ON
197
-- `.toggle-0` means OFF
198
-- no explicit rule means ON by default
199
-
200
-WebUI activation states:
201
-
202
-- `ON`: explicit ON or implicit default
203
-- `OFF`: explicit OFF rule at selected scope
204
-- `Advanced`: at least one project/agent-profile override exists
205
-
206
-`always_enabled: true` bypasses OFF state and keeps the plugin ON in both backend and UI.
207
-
208
-## UI Flow
209
-
210
-Current plugin UX surfaces activation in two places:
211
-
212
-- Plugin list: simple ON/OFF selector, with `Advanced` option when scoped overrides are enabled
213
-- Plugin switch modal: scope-aware ON/OFF controls per project/profile, with direct handoff to settings
214
-
215
-Scope synchronization behavior:
216
-
217
-- Opening "Configure Plugin" from the switch modal propagates current scope into settings store
218
-- Switching scope in settings also mirrors into toggle store so activation status stays aligned
219
-
220
-## API Surface
221
-
222
-Core plugin management endpoint: `POST /api/plugins`
223
-
224
-Supported actions:
225
-
226
-- `get_config`
227
-- `save_config`
228
-- `list_configs`
229
-- `delete_config`
230
-- `toggle_plugin`
231
-- `get_doc` (fetches README.md or LICENSE for display in the UI)
232
-
233
-## Publishing to the Plugin Index
234
-
235
-The **Plugin Index** is a community-maintained repository at https://github.com/agent0ai/a0-plugins. Plugins listed there are discoverable by all Agent Zero users.
236
-
237
-### Two Distinct Manifest Files
238
-
239
-There are two completely different manifest files — they must not be confused:
240
-
241
-**Runtime manifest** (`plugin.yaml`, inside your plugin's own repo — drives Agent Zero behavior):
33
```yaml
243
-name: my_plugin # REQUIRED for index submission; must match index folder name
34
+name: my_plugin
35
title: My Plugin
245
-description: What this plugin does.
36
+description: A short sentence that explains what it does.
37
version: 1.0.0
247
-settings_sections:
248
- - agent
249
-per_project_config: false
250
-per_agent_config: false
251
-always_enabled: false
252
-```
253
-
254
-**Index manifest** (`index.yaml`, submitted to `a0-plugins` under `plugins/<your_plugin_name>/` — drives discoverability only):
255
-```yaml
256
-title: My Plugin
257
-description: What this plugin does.
258
-github: https://github.com/yourname/your-plugin-repo
259
-tags:
260
- - tools
261
- - example
262
-screenshots: # optional, up to 5 full image URLs
263
- - https://raw.githubusercontent.com/yourname/your-plugin-repo/main/docs/screen.png
264
-```
265
-
266
-The index manifest file is named `index.yaml` (not `plugin.yaml`). Required fields: `title`, `description`, `github`. Optional: `tags` (up to 5), `screenshots` (up to 5 URLs). The `github` URL must point to a public GitHub repository that contains a runtime `plugin.yaml` at the **repository root**, and that `plugin.yaml` must include a `name` field matching the index folder name exactly. That repository must also include a `LICENSE` file at its root (Plugin Index / community contribution requirement).
267
-
268
-### Repository Structure for Community Plugins
269
-
270
-Plugin repos should expose the plugin contents at the repo root, so they can be cloned directly into `usr/plugins/<name>/`:
271
-
272
-```text
273
-your-plugin-repo/ ← GitHub repository root
274
-├── plugin.yaml ← runtime manifest (must include name field)
275
-├── default_config.yaml
276
-├── README.md
277
-├── LICENSE ← required for Plugin Index listings
278
-├── api/
279
-├── tools/
280
-├── extensions/
281
-└── webui/
38
```
39
284
-### Submission Process
285
-
286
-1. Create a GitHub repository with the runtime `plugin.yaml` (including the `name` field) at the repo root.
287
-2. Fork `https://github.com/agent0ai/a0-plugins`.
288
-3. Create folder `plugins/<your_plugin_name>/` and add `index.yaml` (the index manifest, not `plugin.yaml`). Optionally add a square thumbnail image (≤ 20 KB, named `thumbnail.png|jpg|webp`).
289
-4. Open a Pull Request. One PR must add exactly one new plugin folder.
290
-5. CI validates automatically. A maintainer reviews and merges.
291
-
292
-Submission rules:
293
-- Folder name: unique, stable, `^[a-z0-9_]+$` (lowercase, numbers, underscores — no hyphens)
294
-- Folder name must exactly match the `name` field in your remote `plugin.yaml`
295
-- The GitHub repo must include `LICENSE` at its root (community contribution requirement)
296
-- Folders starting with `_` are reserved for internal use
297
-- `title`: max 50 characters
298
-- `description`: max 500 characters
299
-- `index.yaml` total: max 2000 characters
300
-- `tags`: optional, up to 5, see https://github.com/agent0ai/a0-plugins/blob/main/TAGS.md
301
-- `screenshots`: optional, up to 5 full image URLs (png/jpg/webp, each ≤ 2 MB)
302
-
303
-### Plugin Hub
304
-
305
-Agent Zero now exposes the community **Plugin Hub** through the always-enabled **Plugin Installer** plugin. Users can browse Plugin Index entries directly from the Plugins UI without leaving the application.
306
-
307
-Users can open the Plugin Hub from the **Plugins** dialog in two ways:
308
-
309
-- click the **Browse** tab after **Custom** and **Builtin**
310
-- click **Install** in the plugin list toolbar to open the installer modal, which starts on its own **Browse** tab
311
-
312
-The Plugin Hub supports search, filtering, sorting, and a plugin detail view with README content and the install action.
313
-
314
-## User Feedback in Plugin UI (Notifications)
315
-
316
-Plugin UIs must use the **A0 notification system** for user feedback. Do not show errors or success via inline elements (e.g. a red box bound to `store.error`).
40
+Ask Agent Zero to keep the first version small. A tiny plugin that does one
41
+visible thing is easier to test, review, and share.
42
318
-- **Frontend**: Use `toastFrontendError(message, title)`, `toastFrontendSuccess(message, title)`, etc. from `/components/notifications/notification-store.js`, or `$store.notificationStore.frontendError(...)` in templates.
319
-- **Backend**: Use `AgentNotification.error(...)`, `AgentNotification.success(...)` from `helpers.notification`.
43
+## Sharing A Plugin
44
321
-This keeps toasts and notification history consistent. See [Notifications](notifications.md) for the full API.
45
+Before publishing a plugin:
46
323
-## See Also
47
+- keep it in its own public repository;
48
+- include a clear `README.md`;
49
+- include a `LICENSE`;
50
+- avoid secrets, local paths, and machine-specific files;
51
+- explain what the plugin changes and how to remove it.
52
325
-- `docs/agents/AGENTS.plugins.md` for full architecture details
326
-- `skills/a0-plugin-router/SKILL.md` for the primary agent-facing entry point across plugin create/review/manage/contribute/debug tasks
327
-- `skills/a0-create-plugin/SKILL.md` for direct plugin authoring workflow when the task is specifically to build or extend a plugin
328
-- `plugins/README.md` for core plugin directory overview
53
+For Plugin Index submission, use the current instructions in the
54
+[`agent0ai/a0-plugins`](https://github.com/agent0ai/a0-plugins) repository.
55
330
-## Frontend Extension Notes
56
+## Related
57
332
-- HTML breakpoints are preferred when the core template already exposes an `x-extension` anchor.
333
-- JS hooks are the right fit for runtime-built UI surfaces. For example, `confirm_dialog_after_render` can extend the shared confirm dialog using the supplied DOM nodes and caller `extensionContext`.
58
+- [Create a Small Plugin](../guides/create-plugin.md)
59
+- [Sharing and Safety](sharing-and-safety.md)
60
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
docs/developer/sharing-and-safety.md
+2
-1
@@ -40,7 +40,8 @@ If yes:
40
3. Test it locally from `usr/plugins/`.
41
4. Submit its `index.yaml` entry to `agent0ai/a0-plugins`.
42
43
-See [`plugins.md`](plugins.md) for the Plugin Index rules and packaging details.
43
+See [`agent0ai/a0-plugins`](https://github.com/agent0ai/a0-plugins) for the
44
+current Plugin Index rules and packaging details.
45
46
### 3. Is this a reusable skill?
47
docs/developer/websockets.md
+22
-709
@@ -1,718 +1,31 @@
1
-# WebSocket Infrastructure Guide
1
+# WebSockets
2
3
-This guide consolidates everything you need to design, implement, and troubleshoot Agent Zero WebSocket flows. It complements the feature specification by describing day-to-day developer tasks, showing how backend handlers and frontend clients cooperate, and documenting practical patterns for producers and consumers on both sides of the connection.
3
+Agent Zero WebSocket architecture is documented in
4
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
5
5
----
6
+This local page is only a handoff. Keeping the full protocol guide here would
7
+duplicate source-linked documentation and become stale.
8
7
-## Table of Contents
9
+## When You Are Working On WebSockets
10
9
-1. [Architecture at a Glance](#architecture-at-a-glance)
10
-2. [Terminology & Metadata](#terminology--metadata)
11
-3. [Connection Lifecycle](#connection-lifecycle)
12
-4. [Backend Cookbook (Handlers & Manager)](#backend-cookbook-handlers--manager)
13
-5. [Frontend Cookbook (websocket.js)](#frontend-cookbook-websocketjs)
14
-6. [Producer & Consumer Patterns](#producer--consumer-patterns)
15
-7. [Metadata Flow & Envelopes](#metadata-flow--envelopes)
16
-8. [Diagnostics, Harness & Logging](#diagnostics-harness--logging)
17
-9. [Best Practices Checklist](#best-practices-checklist)
18
-10. [Quick Reference Tables](#quick-reference-tables)
19
-11. [Further Reading](#further-reading)
11
+Start with the source and DeepWiki:
12
21
----
13
+- `helpers/ws.py`
14
+- `helpers/ws_manager.py`
15
+- `api/ws_*.py`
16
+- `webui/js/websocket.js`
17
+- WebSocket pages in [DeepWiki](https://deepwiki.com/agent0ai/agent-zero)
18
23
-## Architecture at a Glance
19
+## Keep These Rules In Mind
20
25
-- **Runtime (`run_ui.py`)** – boots `python-socketio.AsyncServer` inside an ASGI stack served by Uvicorn. Flask routes are mounted via `uvicorn.middleware.wsgi.WSGIMiddleware`, and Flask + Socket.IO share the same process so session cookies and CSRF semantics stay aligned.
26
-- **Handler base class** – every handler derives from `WsHandler` (defined in `helpers/ws.py`) and implements `process(event, data, sid)`. Handlers are instantiated directly and registered with the manager.
27
-- **Dispatcher offload** – handler entrypoints (`process`, `on_connect`, `on_disconnect`) run in a background worker loop (via `DeferredTask`) so blocking handlers cannot stall the Socket.IO transport. Socket.IO emits/disconnects are marshalled back to the dispatcher loop. Diagnostic timing and payload summaries are only built when Event Console watchers are subscribed (development mode).
28
-- **`helpers/ws_manager.py`** – orchestrates routing, buffering, aggregation, metadata envelopes, and session tracking. Think of it as the "switchboard" for every WebSocket event.
29
-- **`webui/js/websocket.js`** – frontend singleton exposing a minimal client API (`emit`, `request`, `on`, `off`) with lazy connection management and development-only logging (no client-side `broadcast()` or `requestAll()` helpers).
30
-- **Developer Harness (`webui/components/settings/developer/websocket-test-store.js`)** – manual and automatic validation suite for emit/request flows, timeout behaviour (including the default unlimited wait), correlation ID propagation, envelope metadata, subscription persistence across reconnect, and development-mode diagnostics.
31
-- **Specs & Contracts** – canonical definitions live under `specs/003-websocket-event-handlers/`. This guide references those documents but focuses on applied usage.
21
+- Preserve authentication and CSRF checks.
22
+- Keep payloads JSON-serializable.
23
+- Prefer small, named events over large catch-all events.
24
+- Test reconnects, timeouts, and duplicate deliveries.
25
+- Keep user-facing behavior documented in the relevant guide, not in this
26
+ protocol handoff page.
27
33
----
28
+## Related
29
35
-## Terminology & Metadata
36
-
37
-| Term | Where it Appears | Meaning |
38
-|------|------------------|---------|
39
-| `sid` | Socket.IO | Connection identifier for a Socket.IO namespace connection. With only the root namespace (`/`), each tab has one `sid`. When connecting to multiple namespaces, a tab has one `sid` per namespace. Treat connection identity as `(namespace, sid)`. |
40
-| `handlerId` | Manager Envelope | Fully-qualified Python class name (e.g., `api.ws_webui.WsWebui`). Used for result aggregation and logging. |
41
-| `eventId` | Manager Envelope | UUIDv4 generated for every server→client delivery. Unique per emission. Useful when correlating broadcast fan-out or diagnosing duplicates. |
42
-| `correlationId` | Bidirectional flows | Thread that ties together request, response, and any follow-up events. Client may supply one; otherwise the manager generates and echoes it everywhere. |
43
-| `data` | Envelope payload | Application payload you define. Always a JSON-serialisable object. |
44
-| `user_to_sids` / `sid_to_user` | Manager session tracking | Single-user map today (`allUsers` bucket). Future-proof for multi-tenant routing but already handy when you need all active SIDs. |
45
-| Buffer | Manager | Up to 100 fire-and-forget events stored per temporarily disconnected SID (expires after 1 hour). Request/response events never buffer—clients receive standardised errors instead. |
46
-
47
-Useful mental model: **client ↔ manager ↔ handler**. The manager normalises metadata and enforces routing; handlers focus on business logic; the frontend uses the same identifiers, so logs are easy to stitch.
48
-
49
----
50
-
51
-## Connection Lifecycle
52
-
53
-1. **Lazy Connect** – `/js/websocket.js` connects only when a consumer uses the client API (e.g., `emit`, `request`, `on`). Consumers may still explicitly `await websocket.connect()` to block UI until the socket is ready.
54
-2. **Handshake** – Socket.IO connects using the existing Flask session cookie and a CSRF token provided via the Socket.IO `auth` payload (`csrf_token`). The token is obtained from `GET /csrf_token` (see `/js/api.js#getCsrfToken()`), which also sets the runtime-scoped cookie `csrf_token_{runtime_id}`. The server validates an **Origin allowlist** (RFC 6455 / OWASP CSWSH baseline) and then checks handler requirements (`requires_auth`, `requires_csrf`) before accepting.
55
-3. **Lifecycle Hooks** – After acceptance, `WsHandler.on_connect(sid)` fires for every registered handler. Use it for initial emits, state bookkeeping, or session tracking.
56
-4. **Normal Operation** – Client emits events. Manager routes them to the appropriate handlers, gathers results, and wraps outbound deliveries in the mandatory envelope.
57
-5. **Disconnection & Buffering** – If a tab goes away without a graceful disconnect, fire-and-forget events accumulate (max 100). On reconnect, the manager flushes the buffer via `emit_to`. Request flows respond with explicit `CONNECTION_NOT_FOUND` errors.
58
-6. **Reconnection Attempts** – Socket.IO handles reconnect attempts; the manager continues to buffer fire-and-forget events (up to 1 hour) for temporarily disconnected SIDs and flushes them on reconnect.
59
-
60
-### State Sync (Replacing `/poll`)
61
-
62
-Agent Zero can also push poll-shaped state snapshots over the WebSocket bus, replacing the legacy 4Hz `/poll` loop while preserving the existing UI update contract.
63
-
64
-- **Handshake**: the frontend sync store (`/components/sync/sync-store.js`) calls `websocket.request("state_request", { context, log_from, notifications_from, timezone })` to establish per-tab cursors and a `seq_base`.
65
-- **Push**: the server emits `state_push` events containing `{ runtime_epoch, seq, snapshot }`, where `snapshot` is exactly the `/poll` payload shape built by `python/helpers/state_snapshot.py`.
66
-- **Coalescing**: the backend `StateMonitor` coalesces dirties per SID (25ms window) so streaming updates stay smooth without unbounded trailing-edge debounce.
67
-- **Degraded fallback**: if the WebSocket handshake/push path is unhealthy, the UI enters `DEGRADED` and uses `/poll` as a fallback; while degraded, push snapshots are ignored to avoid racey double-writes.
68
-
69
-### Thinking in Roles
70
-
71
-- **Client** (frontend) is the page that imports `/js/websocket.js`. It acts as both a **producer** (calling `emit`, `request`) and a **consumer** (subscribing with `on`).
72
-- **Manager** (`WsManager`) sits server-side and routes everything. It resolves correlation IDs, wraps envelopes, and fans out results.
73
-- **Handler** (`WsHandler`) executes the application logic. Each handler may emit additional events back to the client or initiate its own requests to connected SIDs.
74
-
75
-### Flow Overview (by Operation)
76
-
77
-```
78
-Client emit() ───▶ Manager route_event() ───▶ Handler.process()
79
- │ │ └──(fire-and-forget, no ack)
80
- └── throws if └── validates payload + routes by namespace/event type
81
- not connected updates last_activity
82
-
83
-Client request() ─▶ Manager route_event() ─▶ Handlers (async gather)
84
- │ │ └── per-handler dict/None
85
- │ │
86
- │ └── builds {correlationId, results[]}
87
- └── Promise resolves with aggregated results (timeouts become error items)
88
-
89
-Server emit_to() ──▶ Manager.emit_to() ──▶ Socket.IO delivery/buffer
90
- │ │ └── envelope {handlerId,…}
91
- └── raises ConnectionNotFoundError for unknown sid (never seen)
92
-
93
-Server broadcast() ─▶ Manager.broadcast()
94
- │ └── iterates active sids (respecting exclude_sids)
95
- │ └── delegates to `Manager.emit_to()` → `socketio.emit(..., to=sid)`
96
- └── fire-and-forget (no ack)
97
-
98
-Server request() ─▶ Manager.request_for_sid() ─▶ route_event()
99
- │ │ └── per-handler responses
100
- └── Await aggregated {correlationId, results[]}
101
-
102
-Server request_all() ─▶ Manager.route_event_all() ─▶ route_event per sid
103
- │ │ └── per-handler results
104
- └── Await list[{sid, correlationId, results[]}]
105
-```
106
-
107
-These diagrams highlight the “who calls what” surface while the detailed semantics (envelopes, buffering, timeouts) remain consistent with the tables later in this guide.
108
-
109
-### End-to-End Examples
110
-
111
-1. **Client request ➜ multiple handlers**
112
-
113
- 1. Frontend calls `websocket.request("refresh_metrics", payload)`.
114
- 2. Manager routes to each handler registered for that event type and awaits `asyncio.gather`.
115
- 3. Each handler returns a dict (or raises); the manager wraps them in `results[]` and resolves the Promise with `{ correlationId, results }`.
116
- 4. The caller inspects per-handler data or errors, filtering by `handlerId` as needed.
117
-
118
-2. **Server broadcast with buffered replay**
119
-
120
- 1. Handler invokes `self.broadcast("notification_broadcast", data, exclude_sids=sid)`.
121
- 2. Manager iterates active connections. For connected SIDs it emits immediately with the mandatory envelope. For temporarily disconnected SIDs it enqueues into the per-SID buffer (up to 100 events).
122
- 3. When a buffered SID reconnects, `_flush_buffer()` replays the queued envelopes preserving `handlerId`, `eventId`, `correlationId`, and `ts`.
123
-
124
-3. **Server request_all ➜ client-side confirmations**
125
-
126
- 1. Handler issues `await self.request_all("confirm_close", { contextId }, timeout_ms=5000)`.
127
- 2. Manager fans out to every active SID, allowing `exclude_handlers` when provided.
128
- 3. Each subscribed client runs its `websocket.on("confirm_close", …)` callback and returns data through the Socket.IO acknowledgement.
129
- 4. The handler receives `[{ sid, correlationId, results[] }]`, inspects each response, and proceeds accordingly.
130
-
131
-These expanded flows complement the operation matrix later in the guide, ensuring every combination (client/server × emit/request and server request_all) is covered explicitly.
132
-
133
----
134
-
135
-## Backend Cookbook (Handlers & Manager)
136
-
137
-### 1. Handler Discovery & Setup
138
-
139
-Handlers are `WsHandler` subclasses discovered from `api/ws_*.py`:
140
-
141
-- **Example**: `api/ws_webui.py` → handles WebUI events
142
-- **Dev test**: `api/ws_dev_test.py` → developer harness handler
143
-- **Hello**: `api/ws_hello.py` → minimal example handler
144
-
145
-Create new handler files as `api/ws_<name>.py` and inherit from `WsHandler`.
146
-
147
-```python
148
-from helpers.ws import WsHandler
149
-
150
-class WsMyFeature(WsHandler):
151
-
152
- async def process(self, event: str, data: dict, sid: str) -> dict | None:
153
- if event == "dashboard_refresh":
154
- stats = await self._load_stats(data.get("scope", "all"))
155
- return {"ok": True, "stats": stats}
156
-
157
- if event == "dashboard_push":
158
- await self.broadcast(
159
- "dashboard_update",
160
- {"stats": data.get("stats", {}), "source": sid},
161
- exclude_sids=sid,
162
- )
163
- return None
164
-```
165
-
166
-Handlers are auto-loaded on startup. The `handlerId` is derived automatically from the fully-qualified class name (e.g., `api.ws_my_feature.WsMyFeature`). All registered handlers receive every event; use conditional logic inside `process()` to filter by event type.
167
-
168
-### 2. Consuming Client Events (Server as Consumer)
169
-
170
-- Implement `process` and return either `None` (fire-and-forget) or a dict that becomes the handler's contribution in `results[]`.
171
-- Use dependency injection (async functions, database calls, etc.) but keep event loop friendly—no blocking calls.
172
-- Validate input vigorously and return structured errors as needed.
173
-
174
-```python
175
-async def process(self, event: str, data: dict, sid: str) -> dict | None:
176
- if "query" not in data:
177
- return {"ok": False, "error": {"code": "VALIDATION", "error": "Missing query"}}
178
-
179
- rows = await self.search_backend(data["query"], limit=data.get("limit", 25))
180
- return {"ok": True, "data": rows, "count": len(rows)}
181
-```
182
-
183
-### 3. Producing Server Events (Server as Producer)
184
-
185
-Four helper methods mirror the frontend API. The table below summarises them (full table in [Quick Reference](#quick-reference-tables)).
186
-
187
-| Method | Target | Ack | Filters | Typical Use |
188
-|--------|--------|-----|---------|--------------|
189
-| `emit_to(sid, event, data, correlation_id=None)` | Single SID | No | None | Push job progress, reply to a request without using Socket.IO ack (already produced). |
190
-| `broadcast(event, data, exclude_sids=None, correlation_id=None)` | All SIDs | No | `exclude_sids` only | Fan-out notifications, multi-tab sync while skipping the caller. |
191
-| `request(sid, event, data, timeout_ms=0)` | Single SID | Yes (`results[]`) | None | Ask the client to run local logic (e.g., UI confirmation) and gather per-handler results. |
192
-| `request_all(event, data, timeout_ms=0)` | All SIDs | Yes (`[{sid, results[]}]`) | None | Fan-out to every tab, e.g., “refresh your panel” or “confirm unsaved changes”. |
193
-
194
-Each helper automatically injects `handlerId`, obeys metadata envelopes, enforces routing rules, and handles timeouts:
195
-
196
-```python
197
-aggregated = await self.request_all(
198
- "workspace_ping",
199
- {"payload": {"reason": "health_check"}},
200
- timeout_ms=2_000,
201
-)
202
-
203
-for entry in aggregated:
204
- self.log.info("sid %s replied: %s", entry["sid"], entry["results"])
205
-```
206
-
207
-Timeouts convert into `{ "ok": False, "error": {"code": "TIMEOUT", ...} }`; they do **not** raise.
208
-
209
-### 4. Multi-Handler Aggregation
210
-
211
-- When multiple handlers subscribe to the same event, the manager invokes them concurrently with `asyncio.gather`. Aggregated results preserve registration order. Use correlation IDs to map responses to original triggers.
212
-- Client-side handler include/exclude filters are intentionally not supported. Consumers filter `results[]` by `handlerId` when needed.
213
-
214
-```python
215
-if not results:
216
- return {
217
- "handlerId": self.identifier,
218
- "ok": False,
219
- "error": {"code": "NO_HANDLERS", "error": "No handler registered for this event type"},
220
- }
221
-```
222
-
223
-### 5. Session Tracking Helpers
224
-
225
-`WsManager` maintains lightweight mappings that you can use from handlers:
226
-
227
-```python
228
-all_sids = self.manager.get_sids_for_user() # today: every active sid
229
-maybe_user = self.manager.get_user_for_sid(sid) # currently None or "single_user"
230
-
231
-if updated_payload:
232
- await asyncio.gather(
233
- *[
234
- self.emit_to(other_sid, "dashboard_update", updated_payload)
235
- for other_sid in all_sids if other_sid != sid
236
- ]
237
- )
238
-```
239
-
240
-These helpers are future-proof for multi-tenant evolution and already handy to broadcast to every tab except the caller.
241
-
242
-**Future Multitenancy Mechanics**
243
-- **Registration**: When multi-user support ships, `handle_connect` will resolve the authenticated user identifier (e.g., from Flask session). `register()` will stash that identifier alongside the SID and place it into `user_to_sids[user_id]` while still populating the `allUsers` bucket for backward compatibility.
244
-- **Lookups**: `get_sids_for_user(user_id)` will return the tenant-specific SID set. Omitting the argument (or passing `None`) keeps today’s behaviour and yields the full `allUsers` list. `get_user_for_sid(sid)` will expose whichever identifier was recorded at registration.
245
-- **Utility**: These primitives unlock future features such as sending workspace notifications to every tab owned by the same account, ejecting all sessions for a suspended user, or correlating request/response traffic per tenant without rewriting handlers.
246
-- **Migration Story**: Existing handler code that loops over `get_sids_for_user()` automatically gains tenant-scoped behaviour once callers pass a `user_id`. Tests will exercise both single-user (default) and multi-tenant branches to guarantee compatibility.
247
-
248
----
249
-
250
-## Frontend Cookbook (`websocket.js`)
251
-
252
-### 1. Connecting
253
-
254
-```javascript
255
-import { getNamespacedClient } from "/js/websocket.js";
256
-
257
-const websocket = getNamespacedClient("/"); // reserved root (diagnostics-only by default)
258
-
259
-// Optional: await the handshake if you need to block UI until the socket is ready
260
-await websocket.connect();
261
-
262
-// Runtime metadata is exposed globally for Alpine stores / harness
263
-console.log(window.runtimeInfo.id, window.runtimeInfo.isDevelopment);
264
-```
265
-
266
-- The module connects lazily when a consumer uses the client API (e.g., `emit`, `request`, `on`). Components may still explicitly `await websocket.connect()` to block rendering on readiness or re-run diagnostics.
267
-- The server enforces an Origin allowlist during the Socket.IO connect handshake (baseline CSWSH mitigation). The browser session cookie remains the authentication mechanism, and CSRF is validated via the Socket.IO `auth` payload (`csrf_token`) plus the runtime-scoped CSRF cookie and session value.
268
-- Socket.IO handles reconnection attempts automatically.
269
-
270
-### Namespaces (end-state)
271
-
272
-- The root namespace (`/`) is reserved and intentionally unhandled by default for application events. Feature code should connect to the `/ws` namespace (defined as `NAMESPACE` in `helpers/ws.py`).
273
-- The frontend exposes `createNamespacedClient(namespace)` and `getNamespacedClient(namespace)` (one client instance per namespace per tab). Namespaced clients expose the same minimal API: `emit`, `request`, `on`, `off`.
274
-- Unknown namespaces are rejected deterministically during the Socket.IO connect handshake with a `connect_error` payload:
275
- - `err.message === "UNKNOWN_NAMESPACE"`
276
- - `err.data === { code: "UNKNOWN_NAMESPACE", namespace: "/requested" }`
277
-
278
-### 2. Client Operations
279
-
280
-- **Producers (client → server)** use `emit` and `request`. Payloads must be objects; primitive payloads throw.
281
-- **Consumers (server → client)** register callbacks with `on(eventType, callback)` and remove them with `off()`.
282
-
283
-Example (producer):
284
-
285
-```javascript
286
-await websocket.request("hello_request", { name: this.name }, {
287
- timeoutMs: 1500,
288
- correlationId: `greet-${crypto.randomUUID()}`,
289
-});
290
-```
291
-
292
-Example (consumer):
293
-
294
-```javascript
295
-websocket.on("dashboard_update", (envelope) => {
296
- const { handlerId, correlationId, ts, data } = envelope;
297
- this.debugLog({ handlerId, correlationId, ts });
298
- this.rows = data.rows;
299
-});
300
-
301
-// Later, during cleanup
302
-websocket.off("dashboard_update");
303
-```
304
-
305
-### 3. Envelope Awareness
306
-
307
-Subscribers always receive:
308
-
309
-```javascript
310
-interface ServerDeliveryEnvelope {
311
- handlerId: string;
312
- eventId: string;
313
- correlationId: string;
314
- ts: string; // ISO8601 UTC with millisecond precision
315
- data: object;
316
-}
317
-```
318
-
319
-Even if existing components only look at `data`, you should record `handlerId` and `correlationId` when building new features—doing so simplifies debugging multi-tab flows.
320
-
321
-### 4. Development-Only Logging
322
-
323
-`websocket.debugLog()` writes to the console only when `runtimeInfo.isDevelopment` is true. Use it liberally when diagnosing event flows without polluting production logs.
324
-
325
-```javascript
326
-websocket.debugLog("request", { correlationId: payload.correlationId, timeoutMs });
327
-```
328
-
329
-### 5. Helper Utilities
330
-
331
-`webui/js/websocket.js` exports helper utilities alongside the `websocket` singleton so correlation metadata and envelopes stay consistent:
332
-
333
-- `createCorrelationId(prefix?: string)` returns a UUID-based identifier, optionally prefixed (e.g. `createCorrelationId('hello') → hello-1234…`). Use it when chaining UI actions to backend logs.
334
-- `validateServerEnvelope(envelope)` guarantees subscribers receive the canonical `{ handlerId, eventId, correlationId, ts, data }` shape; throw if the payload is malformed.
335
-
336
-Example:
337
-
338
-```javascript
339
-import { getNamespacedClient, createCorrelationId, validateServerEnvelope } from '/js/websocket.js';
340
-
341
-const websocket = getNamespacedClient('/webui');
342
-
343
-const { results } = await websocket.request(
344
- 'hello_request',
345
- { name: this.name },
346
- { correlationId: createCorrelationId('hello') },
347
-);
348
-
349
-websocket.on('dashboard_update', (envelope) => {
350
- const validated = validateServerEnvelope(envelope);
351
- this.rows = validated.data.rows;
352
-});
353
-```
354
-
355
-### 6. Error Handling
356
-
357
-- Producer methods call `websocket.connect()` internally, so they wait for the handshake automatically. They only surface `Error("Not connected")` if the handshake ultimately fails (for example, the user is logged out or the server is down).
358
-- `request()` acknowledgement timeouts reject with `Error("Request timeout")`. Server-side fan-out timeouts (for example `request_all`) are represented as `results[]` entries with `error.code = "TIMEOUT"` (no Promise rejection).
359
-- For large payloads, the client throws before sending and the server rejects frames above the 50 MiB cap (`max_http_buffer_size` on the Socket.IO engine).
360
-
361
-### 7. Startup Broadcast
362
-
363
-- When **Broadcast server restart event** is enabled in Developer settings (on by default) the backend emits a fire-and-forget `server_restart` envelope the first time each connection is established after a process restart. The payload includes `runtimeId` and an ISO8601 timestamp so clients can reconcile cached state.
364
-- Disable the toggle if your deployment pipeline already publishes restart notifications.
365
-
366
----
367
-
368
-## Frontend Error Handling (Using the Registry)
369
-
370
-Client code should treat `RequestResultItem.error.code` as one of the documented values and branch behavior accordingly. Keep UI decisions localized and reusable.
371
-
372
-Recommended patterns
373
-- Centralize mapping from `WsErrorCode` → user-facing message and remediation hint.
374
-- Always surface hard errors (timeouts); gate debug details by dev flag.
375
-
376
-Example – request()
377
-```javascript
378
-import { getNamespacedClient } from '/js/websocket.js'
379
-
380
-const websocket = getNamespacedClient('/webui')
381
-
382
-function renderError(code, message) {
383
- // Map codes to UI copy; keep messages concise
384
- switch (code) {
385
- case 'NO_HANDLERS': return `No handler for this action (${message})`
386
- case 'TIMEOUT': return `Request timed out; try again or increase timeout`
387
- case 'CONNECTION_NOT_FOUND': return `Target connection unavailable; retry after reconnect`
388
- default: return message || 'Unexpected error'
389
- }
390
-}
391
-
392
-const res = await websocket.request('example_event', { foo: 'bar' }, { timeoutMs: 1500 })
393
-for (const item of res.results) {
394
- if (item.ok) {
395
- // use item.data
396
- } else {
397
- const msg = renderError(item.error?.code, item.error?.error)
398
- // show toast/log based on dev flag
399
- console.error('[ws]', msg)
400
- }
401
-}
402
-```
403
-
404
-Subscriptions – envelope handler
405
-```javascript
406
-import { getNamespacedClient } from '/js/websocket.js'
407
-
408
-const websocket = getNamespacedClient('/webui')
409
-
410
-websocket.on('example_broadcast', ({ data, handlerId, eventId, correlationId }) => {
411
- // handle data; errors should not typically arrive via broadcast
412
- // correlationId can link UI actions to backend logs
413
-})
414
-```
415
-
416
-See also
417
-- Error Codes Registry (above) for the authoritative code list
418
-- Contracts: `frontend-api.md` for method signatures and response shapes
419
-
420
----
421
-
422
-## Producer & Consumer Patterns
423
-
424
-### Pattern A – Fire-and-Forget Notification (Server Producer → Client Consumers)
425
-
426
-Backend:
427
-
428
-```python
429
-await self.broadcast(
430
- "notification_broadcast",
431
- {
432
- "message": data["message"],
433
- "level": data.get("level", "info"),
434
- "timestamp": datetime.now(timezone.utc).isoformat(),
435
- },
436
- exclude_sids=sid,
437
- correlation_id=data.get("correlationId"),
438
-)
439
-```
440
-
441
-Frontend:
442
-
443
-```javascript
444
-websocket.on("notification_broadcast", ({ data, correlationId, ts }) => {
445
- notifications.unshift({ ...data, correlationId, ts });
446
-});
447
-```
448
-
449
-### Pattern B – Request/Response With Multi-Handler Aggregation (Client Producer → Server Consumers)
450
-
451
-Client:
452
-
453
-```javascript
454
-const { correlationId, results } = await websocket.request(
455
- "refresh_metrics",
456
- { duration: "1h" },
457
- { timeoutMs: 2_000 }
458
-);
459
-
460
-results.forEach(({ handlerId, ok, data, error }) => {
461
- if (ok) renderMetrics(handlerId, data);
462
- else console.warn(handlerId, error);
463
-});
464
-```
465
-
466
-Server (two handlers listening to the same event):
467
-
468
-```python
469
-class TaskMetrics(WsHandler):
470
-
471
- async def process(self, event: str, data: dict, sid: str) -> dict | None:
472
- stats = await self._load_task_metrics(data["duration"])
473
- return {"metrics": stats}
474
-
475
-class HostMetrics(WsHandler):
476
-
477
- async def process(self, event: str, data: dict, sid: str) -> dict | None:
478
- return {"metrics": await self._load_host_metrics(data["duration"])}
479
-```
480
-
481
-### Pattern C – Fan-Out `request_all` (Server Producer → Many Client Consumers)
482
-
483
-Backend (server producer asking every tab to confirm a destructive operation):
484
-
485
-```python
486
-confirmations = await self.request_all(
487
- "confirm_close_tab",
488
- {"contextId": context_id},
489
- timeout_ms=5_000,
490
-)
491
-
492
-for entry in confirmations:
493
- self.log.info("%s responded: %s", entry["sid"], entry["results"])
494
-```
495
-
496
-Frontend consumer matching the envelope:
497
-
498
-```javascript
499
-websocket.on("confirm_close_tab", async ({ data, correlationId }) => {
500
- const accepted = await showModalAndAwaitUser(data.contextId);
501
- return { ok: accepted, correlationId, decision: accepted ? "close" : "stay" };
502
-});
503
-```
504
-
505
-### Pattern D – Server Reply Without Using `ack`
506
-
507
-Sometimes you want to acknowledge work immediately but stream additional updates later. Combine `request()` for the initial confirmation and `emit_to()` for follow-up events using the same correlation ID.
508
-
509
-```python
510
-async def process(self, event: str, data: dict, sid: str) -> dict | None:
511
- if event != "start_long_task":
512
- return None
513
-
514
- correlation_id = data.get("correlationId")
515
- asyncio.create_task(self._run_workflow(sid, correlation_id))
516
- return {"accepted": True, "correlationId": correlation_id}
517
-
518
-async def _run_workflow(self, sid: str, correlation_id: str | None):
519
- for step in range(10):
520
- await asyncio.sleep(1)
521
- await self.emit_to(
522
- sid,
523
- "task_progress",
524
- {"step": step, "total": 10},
525
- correlation_id=correlation_id,
526
- )
527
-```
528
-
529
----
530
-
531
-## Metadata Flow & Envelopes
532
-
533
-### Client → Server Payload
534
-
535
-Producers send an object payload as `data` (never primitives). Request metadata like `timeoutMs` and `correlationId` are passed as method options, not embedded into `data`.
536
-
537
-The manager validates the payload, resolves/creates `correlationId`, and passes a clean copy of `data` to handlers.
538
-
539
-### Server → Client Envelope (mandatory)
540
-
541
-```json
542
-{
543
- "handlerId": "api.ws_webui.WsWebui",
544
- "eventId": "b7e2a9cd-2857-4f7a-8bf4-12a736cb6720",
545
- "correlationId": "caller-supplied-or-generated",
546
- "ts": "2025-10-31T13:13:37.123Z",
547
- "data": { "message": "Hello!" }
548
-}
549
-```
550
-
551
-**Guidance:**
552
-
553
-- Use `eventId` alongside frontend logging to spot duplicate deliveries or buffered flushes.
554
-- `correlationId` ties together the user action that triggered the event, even if multiple handlers participate.
555
-- `handlerId` helps you distinguish which handler produced the payload, especially when multiple handlers share the same event type.
556
-
557
----
558
-
559
-## Diagnostics, Harness & Logging
560
-
561
-### Developer Harness
562
-
563
-- Location: `Settings → Developer → WebSocket Test Harness`.
564
-- Automatic mode drives emit, request, delayed request (default unlimited timeout), subscription persistence, and envelope validation. It asserts envelope metadata (handlerId, eventId, correlationId, ISO8601 timestamps) and correlation carryover.
565
-- Manual buttons let you trigger individual flows and inspect recent payloads.
566
-- Harness hides itself when `runtime.isDevelopment` is false so production builds incur zero overhead.
567
-- Helper APIs (`createCorrelationId`, `validateServerEnvelope`) are exercised end to end; subscription logs record the `server_restart` broadcast emitted on first connection after a runtime restart.
568
-
569
-### WebSocket Event Console
570
-
571
-- Location: `Settings → Developer → WebSocket Event Console`.
572
-- Enabling capture calls `websocket.request("ws_event_console_subscribe", { requestedAt })`. The handler (`DevWebsocketTestHandler`) refuses the subscription outside development mode and registers the SID as a **diagnostic watcher** by calling `WsManager.register_diagnostic_watcher`. Only connected SIDs can subscribe.
573
-- Disabling capture calls `websocket.request("ws_event_console_unsubscribe", {})`. Disconnecting also triggers `WsManager.unregister_diagnostic_watcher`, so stranded watchers never accumulate.
574
-- While at least one watcher exists, the manager streams `ws_dev_console_event` envelopes (documented in `contracts/event-schemas.md`). Each payload contains:
575
- - `kind`: `"inbound" | "outbound" | "lifecycle"`
576
- - `eventType`, `sid`, `targets[]`, delivery/buffer flags
577
- - `resultSummary` (handler counts, per-handler status, durationMs)
578
- - `payloadSummary` (first few keys + byte size)
579
-- Lifecycle broadcasts (`ws_lifecycle_connect` / `ws_lifecycle_disconnect`) are emitted asynchronously via `broadcast(..., diagnostic=True)` so long-running handlers can’t block dispatch.
580
-- The modal UI exposes:
581
- - Start/stop capture (explicitly controls subscription state).
582
- - Resubscribe button (detach + resubscribe) to recover gracefully after Socket.IO reconnects.
583
- - Clear button (resets the in-memory ring buffer).
584
- - “Handled-only” toggle that filters inbound entries to ones that resolved to registered handlers or produced errors.
585
-- When the watcher set becomes empty the manager immediately stops streaming diagnostics, guaranteeing zero steady-state overhead outside development.
586
-
587
-### Instrumentation & Logging
588
-
589
-- `WsManager` offloads handler execution via `DeferredTask` and may record `durationMs` when development diagnostics are active (Event Console watchers subscribed). These metrics flow into the Event Console stream (and may also appear in `request()` / `request_all()` results), keeping steady-state overhead near zero when diagnostics are closed.
590
-- Lifecycle events capture `connectionCount`, ISO8601 timestamps, and SID so dashboards can correlate UI behaviour with connection churn.
591
-- Backend logging: use `PrintStyle.debug/info/warning` and always include `handlerId`, `eventType`, `sid`, and `correlationId`. The manager already logs connection events, missing handlers, and buffer overflows.
592
-- Frontend logging: `websocket.debugLog()` mirrors backend debug messages but only when `window.runtimeInfo.isDevelopment` is true.
593
-
594
-### Access Logs & Transport Troubleshooting
595
-
596
-- Settings → Developer includes a persisted `uvicorn_access_logs_enabled` switch. When enabled, `run_ui.py` enables Uvicorn access logs so transport issues (CORS, handshake failures) can be traced.
597
-- The long-standing `websocket_server_restart_enabled` switch (same section) controls whether newly connected clients receive the `server_restart` broadcast that carries `runtimeId` metadata.
598
-
599
-### Common Issues
600
-
601
-1. **`CONNECTION_NOT_FOUND`** – `emit_to` called with an SID that never existed or expired long ago. Use `get_sids_for_user` before emitting or guard on connection presence.
602
-2. **Timeout Rejections** – `request()` and `request_all()` reject only when the transport times out, not when a handler takes too long. Inspect the returned result arrays for `TIMEOUT` entries and consider increasing `timeoutMs`.
603
-3. **Origin Rejected** – the Socket.IO handshake was rejected because the `Origin` header did not match the expected UI origin. Ensure you access the UI and the WebSocket endpoint on the same scheme/host/port, and verify any reverse proxy preserves the `Origin` header.
604
-4. **Diagnostics Subscriptions Failing** – only available in development mode and for connected SIDs. Verify the browser tab still holds an active session and that `window.runtimeInfo.isDevelopment` is true before opening the modal.
605
-
606
----
607
-
608
-## Best Practices Checklist
609
-
610
-- [ ] Always validate inbound payloads in `process()` (required fields, type constraints, length limits).
611
-- [ ] Propagate `correlationId` through multi-step workflows so logs and envelopes align.
612
-- [ ] Respect the 50 MB payload cap; prefer HTTP + polling for bulk data transfers.
613
-- [ ] Ensure long-running operations emit progress via `emit_to` or switch to an async task with periodic updates.
614
-- [ ] Buffer-sensitive actions (`emit_to`) should handle `ConnectionNotFoundError` from unknown SIDs gracefully.
615
-- [ ] When adding new handlers, update the developer harness if new scenarios need coverage.
616
-- [ ] Keep `PrintStyle` logs meaningful—include `handlerId`, `eventType`, `sid`, and `correlationId`.
617
-- [ ] In Alpine components, call `websocket.off()` during teardown to avoid duplicate subscriptions.
618
-
619
----
620
-
621
-## Quick Reference Tables
622
-
623
-### Operation Matrix
624
-
625
-| Direction | API | Ack? | Filters | Notes |
626
-|-----------|-----|------|---------|-------|
627
-| Client → Server | `emit(event, data, { correlationId? })` | No | None | Fire-and-forget. |
628
-| Client → Server | `request(event, data, { timeoutMs?, correlationId? })` | Yes (`{ correlationId, results[] }`) | None | Aggregates per handler. Timeout entries appear inside `results`. |
629
-| Server → Client | `emit_to(sid, ...)` | No | None | Raises `ConnectionNotFoundError` for unknown `sid`. Buffers if disconnected. |
630
-| Server → Client | `broadcast(...)` | No | `exclude_sids` only | Iterates over current connections; uses the same envelope as `emit_to`. |
631
-| Server → Client | `request(...)` | Yes (`{ correlationId, results[] }`) | None | Equivalent of client `request` but targeted at one SID from the server. |
632
-| Server → Client | `request_all(...)` | Yes (`[{ sid, correlationId, results[] }]`) | None | Server-initiated fan-out. |
633
-
634
-### Metadata Cheat Sheet
635
-
636
-| Field | Produced By | Guarantees |
637
-|-------|-------------|------------|
638
-| `correlationId` | Manager | Present on every response/envelope. Caller-supplied ID is preserved; otherwise manager generates UUIDv4 hex. |
639
-| `eventId` | Manager | Unique UUIDv4 per server→client delivery. Helpful for dedup / auditing. |
640
-| `handlerId` | Handler / Manager | Deterministic value `module.Class`. Used for results. |
641
-| `ts` | Manager | ISO8601 UTC with millisecond precision. Replaces `+00:00` with `Z`. |
642
-| `results[]` | Manager | Array of `{ handlerId, ok, data?, error? }`. Errors include `code`, `error`, and optional `details`. |
643
-
644
----
645
-
646
-## Further Reading
647
-
648
-- **QuickStart** – [`specs/003-websocket-event-handlers/quickstart.md`](../specs/003-websocket-event-handlers/quickstart.md) for a step-by-step introduction.
649
-- **Contracts** – Backend, frontend, schema, and security contracts define the canonical API surface:
650
- - [`websocket-handler-interface.md`](../specs/003-websocket-event-handlers/contracts/websocket-handler-interface.md)
651
- - [`frontend-api.md`](../specs/003-websocket-event-handlers/contracts/frontend-api.md)
652
- - [`event-schemas.md`](../specs/003-websocket-event-handlers/contracts/event-schemas.md)
653
- - [`security-contract.md`](../specs/003-websocket-event-handlers/contracts/security-contract.md)
654
-- **Implementation Reference** – Inspect `helpers/ws_manager.py`, `helpers/ws.py`, `webui/js/websocket.js`, and the developer harness in `webui/components/settings/developer/websocket-test-store.js` for concrete examples.
655
-
656
-> **Tip:** When extending the infrastructure (new metadata) start by updating the contracts, sync the manager/frontend helpers, and then document the change here so producers and consumers stay in lockstep.
657
-
658
-## Error Codes Registry
659
-
660
-The WebSocket stack standardizes backend error codes returned in `RequestResultItem.error.code`. This registry documents the currently used codes and their intended meaning. Client and server implementations should reference these values verbatim (UPPER_SNAKE_CASE).
661
-
662
-| Code | Scope | Meaning | Typical Remediation | Example Payload |
663
-|------|-------|---------|---------------------|-----------------|
664
-| `NO_HANDLERS` | Manager routing | No handler is registered for the requested `eventType`. | Register a handler for the event or correct the event name. | `{ "handlerId": "WsManager", "ok": false, "error": { "code": "NO_HANDLERS", "error": "No handler for 'missing'" } }` |
665
-| `TIMEOUT` | Aggregated or single request | The request exceeded `timeoutMs`. | Increase `timeoutMs`, reduce handler processing time, or split work. | `{ "handlerId": "ExampleHandler", "ok": false, "error": { "code": "TIMEOUT", "error": "Request timeout" } }` |
666
-| `CONNECTION_NOT_FOUND` | Single‑sid request | Target `sid` is not connected/known. | Use an active `sid` or retry after reconnect. | `{ "handlerId": "WsManager", "ok": false, "error": { "code": "CONNECTION_NOT_FOUND", "error": "Connection 'sid-123' not found" } }` |
667
-| `NOT_AVAILABLE` | Developer harness | Feature is restricted to development mode. | Ensure `runtime.is_development()` returns `True` or skip the operation. | `{ "handlerId": "api.ws_dev_test.WsDevTest", "ok": false, "error": { "code": "NOT_AVAILABLE", "error": "Event console is available only in development mode" } }` |
668
-| `SUBSCRIBE_FAILED` | Developer harness | Diagnostic watcher subscription failed. | Verify the SID is connected and retry. | `{ "handlerId": "api.ws_dev_test.WsDevTest", "ok": false, "error": { "code": "SUBSCRIBE_FAILED", "error": "Unable to subscribe to diagnostics" } }` |
669
-
670
-Notes
671
-- Error payload shape follows the contract documented in `contracts/event-schemas.md` (`RequestResultItem.error`).
672
-- Codes are case‑sensitive. Use exactly as listed.
673
-- Future codes will be appended here and referenced by inline docstrings/JSDoc.
674
-
675
-### Client-Side Error Codes (Draft)
676
-
677
-The frontend can originate errors during validation, connection, or request execution. Today these surface as thrown exceptions/promise rejections (not as `RequestResultItem`). When server→client request/ack lands in the future, these codes will also be serialised in `RequestResultItem.error.code` for protocol symmetry.
678
-
679
-| Code | Scope | Current Delivery | Meaning | Typical Remediation | Example |
680
-|------|-------|------------------|---------|---------------------|---------|
681
-| `VALIDATION_ERROR` | Producer options / payload | Exception (throw) | Invalid options (e.g., bad `timeoutMs`/`correlationId`) or non-object payload | Fix caller options and payload shapes | `new Error("timeoutMs must be a non-negative number")` |
682
-| `PAYLOAD_TOO_LARGE` | Size precheck (50MB cap) | Exception (throw) | Client precheck rejects payloads exceeding cap before emit | Reduce payload or chunk via HTTP; keep binaries off WS | `new Error("Payload size exceeds maximum (.. > .. bytes)")` |
683
-| `NOT_CONNECTED` | Socket status | Exception (throw) | Auto-connect could not establish a session (user logged out, server offline, handshake rejected) | Check login state, server availability, and Origin policy; optional `await websocket.connect()` for diagnostics | `new Error("Not connected")` |
684
-| `REQUEST_TIMEOUT` | request() | Not used (end-state) | Timeouts are represented inside `results[]` as `error.code="TIMEOUT"` (Promise resolves). | Inspect `results[]` for `TIMEOUT` items and handle in UI. | N/A |
685
-| `CONNECT_ERROR` | Socket connect_error | Exception (throw/log) | Transport/handshake failure | Check server availability, CORS, or network | `new Error("WebSocket connection failed: ...")` |
686
-
687
-Notes
688
-- These are currently local exceptions, not part of the aggregated results payload. Calling code should `try/catch` or handle promise rejections.
689
-- When server→client request/ack is introduced, the same codes will be serialised into `RequestResultItem.error.code` to maintain symmetry with backend codes.
690
-- Prefer branching on `code` when available; avoid coupling to full message strings.
691
-
692
-### IDE Hints (Non‑enforcing)
693
-
694
-To surface recognized codes without adding toolchain dependencies, front‑end can use a JSDoc union type near the helper exports:
695
-
696
-```javascript
697
-/** @typedef {('NO_HANDLERS'|'TIMEOUT'|'CONNECTION_NOT_FOUND')} WsErrorCode */
698
-```
699
-
700
-Back‑end can reference this registry via concise docstrings at error construction points (e.g., `_build_error_result`) to improve discoverability.
701
-
702
----
703
-
704
-## Phase 6 – Registry & Helper Work Status
705
-
706
-Current status
707
-- This registry table is drafted and linked; it documents codes already produced by the manager/helpers today.
708
-
709
-Remaining work (tracked in Phase 6 tasks)
710
-- T148: Ensure the registry is complete and cross‑referenced from comments/docstrings (backend) and JSDoc typedefs (frontend). No new linter/tooling.
711
-- T144: Reference the registry from contracts and quickstart examples; align all examples to documented codes.
712
-- T141/T143: Add/adjust tests to assert known codes only in helper/manager paths.
713
-- T145–T147: Ensure the harness logs/validates codes in envelopes/results as part of the automatic and manual suites.
714
-
715
-Related references
716
-- [`event-schemas.md`](../specs/003-websocket-event-handlers/contracts/event-schemas.md)
717
-- [`websocket-handler-interface.md`](../specs/003-websocket-event-handlers/contracts/websocket-handler-interface.md)
718
-- [`frontend-api.md`](../specs/003-websocket-event-handlers/contracts/frontend-api.md)
30
+- [Architecture](architecture.md)
31
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
docs/guides/a0-cli-connector.md
+170
-47
@@ -1,16 +1,19 @@
1
# A0 CLI Connector
2
3
-Agent Zero lives in Docker for a reason. That keeps it safer. The problem is that people see Docker and assume the agent can never really touch the code on their computer.
3
+A0 CLI connects your terminal to Agent Zero.
4
5
-A0 CLI is the answer to that.
5
+It is not a second agent. Agent Zero is still the one thinking, remembering, and
6
+using tools. A0 CLI is the doorway that lets Agent Zero work on the computer
7
+where the CLI is running.
8
7
-Agent Zero stays in Docker. A0 CLI installs on the host machine. That is what lets Agent Zero finally work on the real files on your real computer.
9
+Agent Zero lives in Docker because that is safer and easier to manage. A0 CLI is
10
+the intentional bridge for moments when you want Agent Zero to work with your
11
+real files, terminal, or browser on the host machine.
12
9
-The same connector can also expose a host browser. Agent Zero still runs
10
-server-side, but A0 CLI controls a real Chrome-family browser on the host and
11
-routes it through Agent Zero's existing `browser` tool.
13
+Agent Zero stays in Docker. A0 CLI installs on the host machine.
14
13
-For now, use the install commands below.
15
+The same connector can also let Agent Zero use a Chrome-family browser on your
16
+computer.
17
18
## Quick Install
19
@@ -26,7 +29,7 @@ irm https://cli.agent-zero.ai/install.ps1 | iex
29
30
Run these on the host machine, not inside the Agent Zero container.
31
29
-The installer uses `uv`, and `uv` will select or download a compatible Python if needed.
32
+The installer handles the small Python helper it needs.
33
34
## Open it and start working
35
@@ -37,26 +40,121 @@ The installer uses `uv`, and `uv` will select or download a compatible Python if
40
a0
41
```
42
40
-3. If Agent Zero is running on the same machine, A0 CLI will usually find it for you.
41
-4. If Agent Zero is somewhere else, enter the exact web address or set `AGENT_ZERO_HOST` as env variable before launching `a0`.
43
+3. If Agent Zero is running on the same machine, A0 CLI will usually find it.
44
+4. If Agent Zero is somewhere else, enter its web address.
45
5. Open or create a chat and confirm you can talk to Agent Zero from the host machine.
46
47
> [!NOTE]
45
-> Current Agent Zero builds starting from v1.9 include the builtin connector support that A0 CLI expects. If you see a connector-specific `404`, update Agent Zero first.
48
+> If A0 CLI says connector support is missing, update Agent Zero first.
49
+
50
+### Connection picker
51
+
52
+On launch, A0 CLI opens a host picker. If it finds Agent Zero on this machine,
53
+click **Connect**. If Agent Zero is somewhere else, click **Enter URL manually**
54
+and paste the address.
55
+
56
+
57
+
58
+Useful launch options:
59
+
60
+```bash
61
+a0 --host http://localhost:32080
62
+a0 --no-auto-connect
63
+a0 --no-docker-discovery
64
+```
65
+
66
+You can also set the address before launching:
67
+
68
+```bash
69
+export AGENT_ZERO_HOST=http://localhost:32080
70
+a0
71
+```
72
+
73
+If **Remember this host** is enabled, the CLI saves that address for next time.
74
+
75
+### The connected shell
76
+
77
+After connecting, the shell shows the Agent Zero address, current project, model,
78
+local folder, Agent Zero workspace, and the message box.
79
+
80
+
81
+
82
+Use the footer when your terminal supports function keys:
83
+
84
+| Key | Action |
85
+|---|---|
86
+| `F3` | Toggle host file read/write access for the active CLI session. |
87
+| `F4` | Toggle remote code execution through the active CLI session. |
88
+| `F5` | Clear the visible chat log. |
89
+| `F6` | Open the chat list. |
90
+| `F7` | Nudge the active agent run. |
91
+| `F8` | Pause the active agent run. |
92
+| `Ctrl+C` | Exit. |
93
+| `Ctrl+P` | Open the command palette. |
94
+
95
+`Ctrl+P` is the best fallback when an IDE terminal or SSH client captures
96
+function keys.
97
+
98
+
99
+
100
+### Slash commands
101
+
102
+Type a slash command in the message box and press Enter. Most commands are also
103
+available from `Ctrl+P`.
104
+
105
+| Command | Use it for |
106
+|---|---|
107
+| `/new` | Create a new empty chat. |
108
+| `/chats` | List previous chats. Add `--project`, `--all-projects`, or `--sort=updated|created|name` when needed. |
109
+| `/project` | Open the project menu, or switch directly with `/project <name>`. |
110
+| `/profile` | Pick or set the active Agent Zero Core profile. |
111
+| `/compact` | Compact the current chat after confirmation. |
112
+| `/pause` | Pause the active run. |
113
+| `/resume` | Resume a paused run. |
114
+| `/nudge` | Nudge the active run. |
115
+| `/presets` | Choose a model preset. |
116
+| `/models` | Edit the active models. |
117
+| `/browser` | Check or change Browser mode. |
118
+| `/attach` | Attach local image files to the next message. Aliases: `/image`, `/img`. |
119
+| `/keys` | Show or hide key and widget help. |
120
+| `/disconnect` | Disconnect and return to the host connection flow. |
121
+| `/help` | Print the available command list in the shell. |
122
+| `/quit` | Disconnect and exit the CLI. |
123
124
## Host Browser
125
49
-Use this when browser content should remain on the user's machine and you want
50
-to pair it with local-model enforcement for host-browser content.
126
+Use this when you want Agent Zero to browse with a browser on your computer.
127
+This is useful when the page, login, or browser profile should stay on your
128
+machine.
129
+
130
+### Setup Checklist
131
+
132
+- [ ] Keep A0 CLI connected to the Agent Zero chat.
133
+- [ ] In Agent Zero Web UI, open Browser plugin settings and choose **Bring Your
134
+ Own Browser**.
135
+- [ ] If you want Agent Zero to use an already-open personal Chrome window, open
136
+ that browser first.
137
+- [ ] In that browser, go to `chrome://inspect/#remote-debugging`.
138
+- [ ] Enable **Allow remote debugging for this browser instance**.
139
+
140
+
141
52
-1. Keep A0 CLI connected to the Agent Zero chat.
142
+When Agent Zero performs its first Browser action against that host browser,
143
+Chrome asks for confirmation. Click **Allow** if you trust this Agent Zero
144
+instance and A0 CLI connection.
145
54
-2. If you want Agent Zero to use an already-open personal Chrome window, open
55
- `chrome://inspect/#remote-debugging` and click **Allow** for that browser
56
- instance. A0 CLI detects Chrome's local `DevToolsActivePort` file; status and
57
- profile checks do not connect to Chrome.
146
+
147
59
-3. Optionally list or select a Chrome-family profile:
148
+A0 CLI does not take over the browser while it is only checking status. Browser
149
+control starts when Agent Zero actually needs to use the browser.
150
+
151
+> [!IMPORTANT]
152
+> Remote debugging gives the connected app full control of that Chrome session,
153
+> including access to saved data, cookies, site data, and navigation. Use it only
154
+> with trusted Agent Zero instances and browser windows you intend the agent to
155
+> control.
156
+
157
+### Browser Profiles
158
159
```bash
160
/browser profile
@@ -64,21 +162,26 @@ to pair it with local-model enforcement for host-browser content.
162
/browser profile chrome-a0 Default
163
```
164
67
-Chrome 136+ blocks Playwright remote debugging against the default personal
68
-Chrome data directory. If Chrome's own Remote debugging consent path is not
69
-available, choose the A0-controlled local profile (`chrome-a0 Default` for
70
-Google Chrome). Cookies and site data remain in that separate browser profile on
71
-the host, and the user may need to sign in there once.
165
+If your everyday Chrome window cannot be used, choose the separate A0 browser
166
+profile instead. It keeps its own cookies and sign-ins, so you may need to log in
167
+there once.
168
+
169
+### Choose Browser Mode
170
+
171
+In Agent Zero Web UI, open Browser plugin settings and choose one of:
172
73
-4. In Agent Zero WebUI, open Browser plugin settings and choose one of:
173
+- **Docker browser:** use Agent Zero's built-in Docker browser.
174
+- **Bring Your Own Browser:** use the browser on your computer through A0 CLI.
175
+ If A0 CLI is not connected, Agent Zero will tell you instead of quietly using
176
+ a different browser.
177
75
-- `container`: always use the Docker/server Playwright browser.
76
-- `host_when_available`: use the A0 CLI host browser when the subscribed CLI can provide it, otherwise fall back to container.
77
-- `host_required`: fail clearly unless a subscribed CLI can provide host browser control.
178
+You can also find the Browser commands from the CLI command palette:
179
79
-When host mode is selected in WebUI, the first Browser tool action asks the CLI
80
-to enable and launch host browser control automatically. The slash commands are
81
-still useful for diagnostics and manual override:
180
+
181
+
182
+When **Bring Your Own Browser** is selected, the first browsing request asks A0
183
+CLI to prepare the browser automatically. These commands are useful when you
184
+want to check or change the state yourself:
185
186
```bash
187
/browser status
@@ -86,22 +189,40 @@ still useful for diagnostics and manual override:
189
/browser relaunch
190
```
191
89
-5. If the selected Chrome profile is already open normally, A0 CLI reports
90
-`relaunch_required`. Close that browser and retry the agent request or run
91
-`/browser relaunch` manually.
192
+`/browser status` shows which Browser mode is selected and whether your browser
193
+is ready:
194
+
195
+
196
+
197
+`/browser host` switches the active chat to Bring Your Own Browser mode:
198
+
199
+
200
93
-The local-profile launch path uses Python Playwright against installed system
94
-Chrome, Chromium, or Edge. The user-authorized Chrome remote debugging path uses
95
-A0 CLI's built-in DevTools Protocol helper instead, so users do not need to
96
-install Chrome DevTools MCP. A0 does not copy browser credentials, cookies, or
97
-profile data out of the browser profile.
201
+Run `/browser container` to switch that chat back to Docker browser mode.
202
99
-Host-browser page content and screenshots are controlled by the Browser
100
-plugin's project-level policy:
203
+`/browser privacy` reminds users where the Browser content policy lives:
204
102
-- `enforce_local`: block content/screenshots unless the active chat model is local.
103
-- `warn`: allow and include a warning in the tool result.
104
-- `allow`: allow without warning.
205
+
206
+
207
+If the selected browser profile is already open in another window, close that
208
+window and try again. You can also run `/browser relaunch`.
209
+
210
+You do not need to install Chrome DevTools MCP for this. A0 CLI already includes
211
+what it needs to connect to the browser you approve.
212
+
213
+### Page Privacy
214
+
215
+Browser settings decide what Agent Zero may do with page text and screenshots
216
+from your own browser:
217
+
218
+- **Local models only:** use host-browser page content only with local models.
219
+- **Warn when using cloud:** allow cloud models, but show a warning.
220
+- **Allow:** allow without warning.
221
+
222
+> [!NOTE]
223
+> The live Browser surface shows the Docker browser. When Agent Zero uses your
224
+> host browser, results and screenshots appear in the chat, but the live Canvas
225
+> is not a stream of your personal browser window.
226
227
## Give this to another agent
228
@@ -116,11 +237,13 @@ Set up the A0 CLI connector for Agent Zero on this machine using the a0-setup-cl
237
- **Nothing appears locally:** Enter the Agent Zero web address manually or export `AGENT_ZERO_HOST`.
238
- **You tried to install from inside Docker:** A0 CLI belongs on the host machine. Agent Zero stays in Docker.
239
- **Function keys do nothing:** Some terminals and IDEs capture function keys. Use `Ctrl+P`.
119
-- **Connector route returns `404`:** Update Agent Zero to a build with builtin connector support.
120
-- **Host browser says Playwright is missing:** Install it in the A0 CLI environment with `python -m pip install playwright`.
121
-- **Host browser waits for relaunch:** The selected Chrome-family profile is already locked by normal Chrome. Close that profile and run `/browser relaunch`.
240
+- **A0 CLI says connector support is missing:** Update Agent Zero.
241
+- **Host browser says repair is needed:** Run `/browser repair`.
242
+- **Host browser waits for relaunch:** Close the selected Chrome, Edge, or Chromium profile and run `/browser relaunch`.
243
244
## Related links
245
246
- [Quick Start](../quickstart.md)
247
- [Installation Guide](../setup/installation.md)
248
+- [Browser Guide](browser.md)
249
+- [MCP Setup](mcp-setup.md)
docs/guides/agent-profiles.md
+58
-116
@@ -1,148 +1,90 @@
1
# Agent Profiles
2
3
-Agent profiles let you give Agent Zero different identities, prompt overrides, tools, extensions, and optionally model settings. Use them when you want a specialized agent such as a researcher, developer, security auditor, copywriter, or domain-specific assistant.
3
+Agent Profiles change the voice, habits, and prompt instructions driving the
4
+current chat.
5
5
-Use **Settings > Agent Config** to choose the default profile for new chats. The chat composer profile selector shows and changes the profile for the currently selected chat only, so different chats can keep different active profiles.
6
+Use a profile when you want Agent Zero to behave like a researcher, developer,
7
+security reviewer, writing partner, data analyst, or another repeatable working
8
+style.
9
7
-## Where Profiles Live
10
+For architecture and source-linked internals, use
11
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
12
9
-| Location | Purpose |
10
-|---|---|
11
-| `/a0/agents/<profile>/` | Built-in framework profiles. Do not edit these for custom work. |
12
-| `/a0/usr/agents/<profile>/` | User-created profiles. This is the normal place for custom profiles and survives updates. |
13
-| `/a0/usr/plugins/<plugin>/agents/<profile>/` | Plugin-distributed profiles tied to plugin functionality. |
14
-| `/a0/usr/projects/<project>/.a0proj/agents/<profile>/` | Project-scoped profiles available only inside one project. |
13
+## Switch Profile In A Chat
14
16
-## Required Profile Definition
15
+The profile menu lives in the status bar near the chat input.
16
18
-Every profile needs an `agent.yaml` file:
17
+
18
20
-```yaml
21
-title: Data Analyst
22
-description: Agent specialized in data analysis, visualization, and statistical modeling.
23
-context: Use this agent for data analysis tasks, creating visualizations, statistical
24
- analysis, and working with datasets in Python.
25
-```
19
+1. Open a chat.
20
+2. Click the current profile name near the chat input.
21
+3. Choose the profile you want.
22
+4. Continue the chat normally.
23
27
-`agent.yaml` intentionally has only these fields:
24
+The change applies to the selected chat. Other chats can keep their own profile.
25
29
-| Field | Purpose |
30
-|---|---|
31
-| `title` | Display name shown in the UI |
32
-| `description` | One-line summary of the specialization |
33
-| `context` | Instructions telling a superior agent when to delegate to this profile |
26
+> [!TIP]
27
+> Use **Settings -> Agent Config** when you want to change the default profile
28
+> for new chats.
29
35
-Do not put model settings, temperature, or tool allow-lists in `agent.yaml`.
30
+## Create A New Agent Profile
31
37
-## Prompt Overrides
32
+The same menu includes **Create new Agent Profile**.
33
39
-Profiles inherit the root prompt files from `/a0/prompts`. To customize a profile, copy only the prompt files you need into:
34
+
35
41
-```text
42
-/a0/usr/agents/<profile>/prompts/
43
-```
36
+When you click it, Agent Zero places a ready-to-send message in the chat input.
37
+Send that message and Agent Zero starts a guided profile-creation flow.
38
45
-The most common override is:
39
+The flow is intentionally conversational:
40
+
41
+- it asks what the new profile should be excellent at;
42
+- it suggests sensible defaults;
43
+- it confirms a compact summary before creating anything;
44
+- it uses the dedicated profile-creation skill to keep the process tidy.
45
+
46
+Good answers are practical:
47
48
```text
48
-prompts/agent.system.main.specifics.md
49
+This profile should help me plan YouTube scripts for technical demos. It should
50
+ask for the target audience, keep the tone simple, and suggest a visual outline.
51
```
52
51
-This file is intentionally empty by default and is the safest place to add role, expertise, workflow, and style instructions.
52
-
53
-Useful root prompt levers:
54
-
55
-| File | Use it for |
56
-|---|---|
57
-| `agent.system.main.specifics.md` | Role, expertise, persona, workflow, and behavioral specialization. |
58
-| `agent.system.main.communication.md` | Changing the response contract, such as replacing the default `thoughts`, `headline`, `tool_name`, `tool_args` JSON shape. |
59
-| `agent.system.main.solving.md` | Changing the problem-solving loop, autonomy level, delegation policy, or verification standard. |
60
-| `agent.system.main.environment.md` | Describing a different runtime or domain environment. |
61
-| `agent.system.main.role.md` | Replacing the base Agent Zero role. Use rarely; prefer `specifics.md` when possible. |
62
-| `agent.system.tool.<name>.md` | Documenting a profile-specific tool or overriding a tool prompt. |
63
-
64
-Only override what you actually want to change. Copying unchanged prompt files makes profiles harder to maintain when the framework updates.
65
-
66
-## Profile-Specific Models
67
-
68
-Main and Utility model settings are not part of `agent.yaml`. They are handled by the always-enabled `_model_config` plugin.
69
-
70
-To give one profile its own Main or Utility model, create a companion config file:
71
-
72
-| Profile scope | Model config path |
73
-|---|---|
74
-| User profile | `/a0/usr/agents/<profile>/plugins/_model_config/config.json` |
75
-| Plugin-distributed profile | `/a0/usr/plugins/<plugin>/agents/<profile>/plugins/_model_config/config.json` |
76
-| Project-scoped profile | `/a0/usr/projects/<project>/.a0proj/agents/<profile>/plugins/_model_config/config.json` |
77
-
78
-Example complete config:
79
-
80
-```json
81
-{
82
- "allow_chat_override": true,
83
- "chat_model": {
84
- "provider": "openrouter",
85
- "name": "anthropic/claude-sonnet-4.6",
86
- "api_base": "",
87
- "ctx_length": 200000,
88
- "ctx_history": 0.7,
89
- "vision": true,
90
- "rl_requests": 0,
91
- "rl_input": 0,
92
- "rl_output": 0,
93
- "kwargs": {}
94
- },
95
- "utility_model": {
96
- "provider": "openrouter",
97
- "name": "openai/gpt-5.4-mini",
98
- "api_base": "",
99
- "ctx_length": 128000,
100
- "ctx_input": 0.7,
101
- "rl_requests": 0,
102
- "rl_input": 0,
103
- "rl_output": 0,
104
- "kwargs": {}
105
- },
106
- "embedding_model": {
107
- "provider": "huggingface",
108
- "name": "sentence-transformers/all-MiniLM-L6-v2",
109
- "api_base": "",
110
- "rl_requests": 0,
111
- "rl_input": 0,
112
- "kwargs": {}
113
- }
114
-}
53
+```text
54
+I want a cautious finance analyst profile. It should separate facts from
55
+assumptions, prefer spreadsheets, and never present estimates as certainty.
56
```
57
117
-Important: scoped `_model_config/config.json` files are selected as a whole. They are not deep-merged with broader global or project config. If you create this file, include a complete effective config with `chat_model`, `utility_model`, and `embedding_model`. If you only want to customize Main or Utility, copy the other model sections from the current effective config.
58
+## Profile, Skill, Project, Or Model Preset?
59
119
-Do not store API keys in this file. API keys are managed globally through Settings and secrets.
60
+These controls are related, but they solve different problems.
61
121
-## Tools and Extensions
62
+| Use this | When you want to change |
63
+| --- | --- |
64
+| **Agent Profile** | The agent's role, tone, workflow, and prompt instructions. |
65
+| **Skill** | A specific procedure or capability the agent should keep available. |
66
+| **Project** | Files, workspace, memories, instructions, secrets, and long-running context. |
67
+| **Model Preset** | Which models are used for the chat. |
68
123
-Profiles can also add or override tools and extensions:
69
+Example:
70
125
-```text
126
-/a0/usr/agents/<profile>/tools/<tool_name>.py
127
-/a0/usr/agents/<profile>/extensions/<hook_point>/_NN_name.py
128
-```
71
+- use a **Project** for a client repository;
72
+- use an **Agent Profile** for "careful code reviewer";
73
+- pin a **Skill** for a repeated workflow;
74
+- choose a **Model Preset** for speed, cost, or maximum capability.
75
130
-If you add a tool, also add a matching prompt file:
76
+## Small Advanced Note
77
132
-```text
133
-/a0/usr/agents/<profile>/prompts/agent.system.tool.<tool_name>.md
134
-```
78
+Most users should create profiles through the menu above.
79
136
-## Quick Example
80
+If you edit files directly, custom profiles normally live in:
81
82
```text
139
-/a0/usr/agents/data-analyst/
140
-+-- agent.yaml
141
-+-- prompts/
142
-| +-- agent.system.main.specifics.md
143
-+-- plugins/
144
- +-- _model_config/
145
- +-- config.json
83
+/a0/usr/agents/<profile-name>/
84
```
85
148
-The `plugins/_model_config/config.json` file is optional. Use it only when this profile needs different models from the global or project settings.
86
+Custom prompts belong inside that profile's `prompts/` folder. Keep direct file
87
+edits small and documented so updates remain easy to understand later.
88
+
89
+For deeper file layout and prompt-loading details, use
90
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
docs/guides/api-integration.md
+26
-23
@@ -103,26 +103,24 @@ The agent confirms:
103
- File location: `/root/agent_zero_logo_0.jpg`
104
- File size: 378 KB
105
106
-## How Memory Works
106
+## How Memory Helps
107
108
-Here's where it gets interesting: **Agent Zero will remember this solution**.
108
+Agent Zero can save useful API patterns in memory so you do not have to explain
109
+the same integration every time.
110
110
-The next time you ask it to generate an image:
111
-- It will automatically use the Gemini API approach it learned
112
-- No need to provide the code snippet again
113
-- The API key is already configured
114
-- Dependencies are already installed
111
+For example, it may remember:
112
116
-The agent stores:
117
-- **How to use the API** (code structure, parameters)
118
-- **What the API does** (image generation)
119
-- **What credentials are needed** (`GEMINI_API_KEY`)
120
-- **Common patterns and best practices** from the interaction
113
+- what the API is useful for;
114
+- what credential name is needed;
115
+- which package or example worked;
116
+- how you prefer to use that service in this project.
117
122
-This memory persists across:
123
-- Multiple conversations
124
-- Agent restarts
125
-- Different projects (for global memory and global secrets)
118
+> [!IMPORTANT]
119
+> Memory still needs curation. If Agent Zero keeps using an old API pattern,
120
+> wrong credential name, or outdated package, open Memory and fix or remove that
121
+> memory. Memory should help the agent think, not trap it in yesterday's answer.
122
+
123
+See the [Memory Guide](memory.md) for cleanup and curation tips.
124
125
## Use Cases
126
@@ -219,13 +217,18 @@ Then in future chats:
217
218
## Conclusion
219
222
-By leveraging Agent Zero's ability to learn from API code snippets, you can:
220
+By showing Agent Zero a working API example, you can:
221
+
222
+- add a new service to a project;
223
+- keep credentials in settings or project secrets;
224
+- reuse working patterns later;
225
+- clean up memory when an old pattern stops helping.
226
224
-- **Add new capabilities instantly** without writing integration code
225
-- **Keep solutions in memory** for reuse across conversations
226
-- **Manage credentials securely** with global or project-scoped secrets
227
-- **Scale across any public API** using the same simple workflow
227
+This is not magic permanence. It works best when you keep the example, secrets,
228
+project instructions, and memories tidy.
229
229
-This makes Agent Zero incredibly versatile - it's not limited to its built-in features. Show it how to use an API once, and it becomes part of its permanent toolkit.
230
+## Related
231
231
-Ready to try it yourself? Pick any API you want to integrate and follow the steps above!
232
+- [Memory Guide](memory.md)
233
+- [Projects Guide](projects.md)
234
+- [MCP Setup](mcp-setup.md)
docs/guides/browser.md
new
+213
@@ -0,0 +1,213 @@
1
+# Browser Guide
2
+
3
+Agent Zero has a built-in Browser for real web pages.
4
+
5
+Use it for research, forms, screenshots, UI review, downloads, extensions, and
6
+anything else that works best in a browser.
7
+
8
+
9
+
10
+## Two Parts
11
+
12
+The Browser has two connected parts:
13
+
14
+- **The Browser tool:** the agent can browse even when the Browser surface is not open.
15
+- **The Browser surface:** The right-side Canvas panel where you can watch and interact with the live Docker browser.
16
+
17
+The Browser surface does not open automatically every time the agent browses.
18
+Open it when you want to watch, steer, or annotate the page.
19
+
20
+## Open The Browser Surface
21
+
22
+1. Open the right-side Canvas.
23
+2. Select **Browser**.
24
+3. Click **Open Browser** or the plus button to create a new browser tab.
25
+4. Enter a URL in the Browser address bar.
26
+
27
+
28
+
29
+The surface shows Browser tabs, back/forward/reload controls, an address bar, an annotation toggle, and Browser settings.
30
+
31
+## Ask The Agent To Browse
32
+
33
+You can ask naturally:
34
+
35
+```text
36
+Use the Browser tool to open https://example.com, read the page content, and take a screenshot. Keep the response short.
37
+```
38
+
39
+The agent can:
40
+
41
+- open pages;
42
+- read page content;
43
+- click links and buttons;
44
+- type into forms;
45
+- upload files;
46
+- take screenshots.
47
+
48
+When a page is read, Agent Zero gets simple references such as `[link 1]`,
49
+`[button 2]`, or `[input text 3]`. It can use those references to act on the
50
+right part of the page.
51
+
52
+<details>
53
+<summary>Advanced Browser actions</summary>
54
+
55
+```text
56
+list
57
+state
58
+set_active
59
+navigate
60
+back
61
+forward
62
+reload
63
+hover
64
+double_click
65
+right_click
66
+drag
67
+scroll
68
+evaluate
69
+key_chord
70
+mouse
71
+wheel
72
+keyboard
73
+clipboard
74
+set_viewport
75
+multi
76
+close
77
+close_all
78
+```
79
+
80
+</details>
81
+
82
+
83
+
84
+## Screenshots And History
85
+
86
+When Agent Zero takes a Browser screenshot, the image is saved and shown in the
87
+chat history.
88
+
89
+Many Browser steps also keep a small history screenshot. That means an older
90
+chat can show the page as it looked when the agent worked on it, not just the
91
+latest page frame.
92
+
93
+## Annotate Pages
94
+
95
+Annotate mode lets you mark a page element or region and send a targeted comment back into the chat. This is useful for UI review: you can point at the exact thing that needs to change instead of describing it from memory.
96
+
97
+1. Open the Browser surface.
98
+2. Navigate to the page you want to review.
99
+3. Click **Annotate**. The button changes to **Annotating**.
100
+4. Click the page element or region.
101
+5. Write the comment and click **Add**.
102
+
103
+
104
+
105
+## Browser Settings
106
+
107
+Open Browser settings from the Browser toolbar or from the Browser plugin settings.
108
+
109
+
110
+
111
+The toolbar menu includes:
112
+
113
+- **Browser LLM Preset:** Optional model choice for Browser helper work.
114
+- **Chrome Extensions:** Install a Chrome Web Store URL, create a new extension with Agent Zero, or scan an extension with Agent Zero.
115
+- **Settings:** Opens the full Browser plugin settings.
116
+
117
+
118
+
119
+The full settings include:
120
+
121
+- **Browser location:** Use the Docker browser or **Bring Your Own Browser** through A0 CLI.
122
+- **Page content access:** Controls host-browser page text and screenshots.
123
+- **Starting page:** The default URL for new Browser sessions.
124
+- **Autofocus active page:** Lets an already-open Browser surface follow the agent's browsing.
125
+- **Extensions:** Choose which installed Chrome extensions load in the Docker browser.
126
+
127
+## Docker Browser
128
+
129
+The Docker browser is the default. It is a separate browser inside Agent Zero's
130
+Docker environment, and it is the browser shown in the live Browser surface.
131
+
132
+Use Docker browser mode when you want a clean, separate browser that Agent Zero
133
+can show in the Canvas.
134
+
135
+In normal Docker installs, the needed browser is already included. In local
136
+development, Agent Zero can install it the first time it is needed.
137
+
138
+## Bring Your Own Browser
139
+
140
+Bring Your Own Browser lets Agent Zero use Chrome, Edge, or Chromium on your own
141
+computer through A0 CLI.
142
+
143
+Use it when the page, login, or browser profile should stay on your machine.
144
+
145
+Requirements:
146
+
147
+- [ ] Keep A0 CLI connected to the Agent Zero chat.
148
+- [ ] Choose **Bring Your Own Browser** in Browser settings.
149
+- [ ] Use Chrome, Edge, or Chromium on the host.
150
+- [ ] For personal Chrome remote debugging, open the host browser first, go to `chrome://inspect/#remote-debugging`, and enable **Allow remote debugging for this browser instance**.
151
+
152
+
153
+
154
+The first time Agent Zero tries to operate that browser, Chrome shows an **Allow
155
+remote debugging?** prompt. Click **Allow** if you trust the connected Agent Zero
156
+instance and A0 CLI session.
157
+
158
+
159
+
160
+> [!IMPORTANT]
161
+> Remote debugging grants full control of that browser session, including access
162
+> to saved data, cookies, site data, and navigation. Enable it only for browser
163
+> instances you intend Agent Zero to control.
164
+
165
+Browser settings decide what Agent Zero may do with page text and screenshots
166
+from your own browser:
167
+
168
+- **Local models only:** Block host-browser content and screenshots unless the active chat model is local.
169
+- **Warn when using cloud:** Allow content and include a warning.
170
+- **Allow:** Allow without warning.
171
+
172
+> [!NOTE]
173
+> The live Browser surface shows the Docker browser. When Agent Zero uses your
174
+> host browser, page results and screenshots appear in the chat, but the live
175
+> Canvas is not a stream of your personal browser window.
176
+
177
+For setup details, profiles, and troubleshooting, see the [A0 CLI Connector guide](a0-cli-connector.md#host-browser).
178
+
179
+## Chrome Extensions
180
+
181
+Browser can load Chrome extensions into the Docker browser.
182
+
183
+Only enable extensions you trust. They run inside the Docker browser, but they
184
+can still change what happens in that browser.
185
+
186
+## MCP Alternatives
187
+
188
+Start with Agent Zero's built-in Browser.
189
+
190
+Use an MCP browser option only when you specifically need another browser tool
191
+or an external automation service.
192
+
193
+Common alternatives include:
194
+
195
+- Chrome DevTools MCP
196
+- Playwright MCP
197
+- Browser OS MCP
198
+
199
+See [MCP Setup](mcp-setup.md) for MCP setup.
200
+
201
+## Troubleshooting
202
+
203
+- **Browser says Playwright is missing:** Docker installs already include the browser. In local development, let Agent Zero install it on first use or preinstall it with `PLAYWRIGHT_BROWSERS_PATH=tmp/playwright playwright install chromium`.
204
+- **The Browser surface does not open automatically:** That is expected. Open the Browser surface manually or ask the agent to show it.
205
+- **The Canvas does not follow the agent:** Enable **Autofocus active page** in Browser settings.
206
+- **Bring Your Own Browser cannot start:** Keep A0 CLI connected, verify Browser location is **Bring Your Own Browser**, and check `/browser status` in A0 CLI.
207
+- **Host-browser content is blocked:** Switch to a local model or change Browser **Page content access** from **Local models only** to **Warn when using cloud** or **Allow**.
208
+
209
+## Related
210
+
211
+- [A0 CLI Connector](a0-cli-connector.md): host Browser setup, profiles, and CLI commands.
212
+- [MCP Setup](mcp-setup.md): external browser tools when you need a different setup.
213
+- [Desktop Guide](desktop.md): Linux GUI apps and LibreOffice Cowork in the Canvas.
docs/guides/contribution.md
+9
-6
@@ -4,9 +4,9 @@ Contributions to improve Agent Zero are very welcome! This guide outlines how t
4
5
## Getting Started
6
7
-- See [development](development.md) for instructions on how to set up a development environment.
8
-- See [extensions](../developer/extensions.md) for instructions on how to create custom extensions.
9
-- See [websocket infrastructure](websocket-infrastructure.md) for guidance on building real-time handlers and client integrations.
7
+- See [Development Setup](../setup/dev-setup.md) for a local development environment.
8
+- See [Create a Small Plugin](create-plugin.md) before building a new plugin.
9
+- Use [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero) for architecture and source-linked internals.
10
11
1. **Fork the Repository:** Fork the Agent Zero repository on GitHub.
12
2. **Clone Your Fork:** Clone your forked repository to your local machine.
@@ -43,12 +43,15 @@ If your fork contains GitHub Actions workflows, be careful with GitHub's "Allow
43
## Choosing The Right Publication Path
44
45
- **Core bugfixes and docs for Agent Zero itself:** prepare them in a clean fork/clone of `agent-zero` and open a PR back to the upstream repository.
46
-- **Community plugins:** publish the plugin in its own public repository, then submit its `index.yaml` entry to `agent0ai/a0-plugins` as described in `../developer/plugins.md`.
46
+- **Community plugins:** publish the plugin in its own public repository, then submit it to [`agent0ai/a0-plugins`](https://github.com/agent0ai/a0-plugins).
47
- **Skills:** develop locally in `usr/skills/`, then move stable skills to `skills/` for Agent Zero contributions or publish them in a dedicated public repository/collection.
48
- **Private experiments, credentials, local R&D, or customer-specific assets:** keep them out of public forks and upstream pull requests.
49
50
-For a contributor-focused decision guide that covers fixes, plugins, skills, and what should stay private, see `../developer/sharing-and-safety.md`.
50
+For a contributor-focused decision guide that covers fixes, plugins, skills, and
51
+what should stay private, see [Sharing and Safety](../developer/sharing-and-safety.md).
52
53
## Documentation Stack
54
54
-- The documentation is built using Markdown. We appreciate your contributions even if you don't know Markdown, and look forward to improve Agent Zero for everyone's benefit.
55
+- Write local docs for practical setup, screenshots, and user workflows.
56
+- Point architecture and deep internals to [DeepWiki](https://deepwiki.com/agent0ai/agent-zero).
57
+- Use GitHub Flavored Markdown when it helps: tables, task lists, callouts, and fenced code blocks.
docs/guides/create-plugin.md
new
+158
@@ -0,0 +1,158 @@
1
+# Create A Small Plugin
2
+
3
+The fastest way to understand Agent Zero plugins is to make one small enough to
4
+hold in your head.
5
+
6
+This guide walks through a real example: a local plugin named `unread_dot` that
7
+adds a pulsing dot beside a chat when that chat receives new activity while you
8
+are looking somewhere else.
9
+
10
+
11
+
12
+For architecture and source-linked internals, use
13
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). This page
14
+stays practical: what to ask, where files appear, what to check, and how to know
15
+the plugin actually works.
16
+
17
+## What You Are Making
18
+
19
+`unread_dot` is intentionally tiny:
20
+
21
+- it does not add a server endpoint;
22
+- it adds no tool;
23
+- it installs no package;
24
+- it makes no network calls;
25
+- it touches only the Web UI and one browser `localStorage` key.
26
+
27
+That makes it a good first plugin. You can see the whole shape without learning
28
+every plugin feature at once.
29
+
30
+## Ask Agent Zero To Build It
31
+
32
+Open a new chat and give Agent Zero a very specific plugin task:
33
+
34
+```text
35
+Use the a0-create-plugin skill.
36
+
37
+Create a local-only plugin named unread_dot in /a0/usr/plugins/unread_dot.
38
+The plugin should show a pulsing dot in the chat list whenever a non-selected
39
+chat receives new agent activity.
40
+
41
+Keep it minimal and frontend-only:
42
+- no external dependencies;
43
+- no backend API;
44
+- no tools;
45
+- no network calls.
46
+
47
+If the plugin already exists, improve it instead of creating a duplicate.
48
+When finished, run the a0-review-plugin skill on unread_dot and summarize
49
+PASS/WARN/FAIL. Do not run CodeRabbit.
50
+```
51
+
52
+The important part is not the exact wording. The important part is giving Agent
53
+Zero the plugin name, the location, the visible behavior, and the boundaries.
54
+
55
+## Where The Files Go
56
+
57
+Local plugins live under `/a0/usr/plugins/<plugin_name>/` inside the running
58
+Agent Zero instance. For this example, the final plugin shape is:
59
+
60
+```text
61
+/a0/usr/plugins/unread_dot/
62
+├── plugin.yaml
63
+├── README.md
64
+├── extensions/
65
+│ └── webui/
66
+│ ├── apply_snapshot_before/
67
+│ │ └── track-unread.js
68
+│ └── initFw_end/
69
+│ └── bootstrap-unread-dot.js
70
+└── webui/
71
+ ├── unread-dot.css
72
+ └── unread-dot-store.js
73
+```
74
+
75
+`plugin.yaml` is the plugin's name tag:
76
+
77
+```yaml
78
+name: unread_dot
79
+title: Unread Dot
80
+description: Shows a pulsing dot beside chats that received new activity while you were elsewhere.
81
+version: 1.0.0
82
+settings_sections: []
83
+per_project_config: false
84
+per_agent_config: false
85
+```
86
+
87
+The two Web UI extension files are the little doorways into the running
88
+interface:
89
+
90
+- `initFw_end/bootstrap-unread-dot.js` loads the store and stylesheet after the Web UI starts.
91
+- `apply_snapshot_before/track-unread.js` watches state snapshots so the plugin can notice when another chat changes.
92
+
93
+The store keeps the unread state. The CSS draws the dot.
94
+
95
+## Try It For Real
96
+
97
+After creating or changing a plugin, restart Agent Zero so the Web UI extension
98
+list is rebuilt.
99
+
100
+Then test the behavior:
101
+
102
+1. Open a fresh chat.
103
+2. Send a short prompt, such as:
104
+
105
+ ```text
106
+ Please reply with one short sentence: unread dot live test complete.
107
+ ```
108
+
109
+3. Immediately switch to another chat.
110
+4. Wait for Agent Zero to keep working in the first chat.
111
+5. Look at the chat list.
112
+
113
+If the first chat receives new activity while it is not selected, the dot appears.
114
+When you open that chat again, the dot clears.
115
+
116
+This example watches for chat activity. In normal use, that means "the agent did
117
+something in a chat you were not watching." It does not read every message in
118
+every other chat.
119
+
120
+## Review It
121
+
122
+Run the plugin review skill before treating the plugin as done:
123
+
124
+```text
125
+Use the a0-review-plugin skill to review /a0/usr/plugins/unread_dot.
126
+Report PASS/WARN/FAIL by phase.
127
+```
128
+
129
+For this example, the review result is:
130
+
131
+| Phase | Result | Notes |
132
+| --- | --- | --- |
133
+| Manifest | PASS | `plugin.yaml` is valid, named correctly, and uses simple local settings. |
134
+| Structure | PASS with WARN | The layout is standard. `LICENSE` is absent, which is fine locally but blocks Plugin Index submission. |
135
+| Code patterns | PASS with WARN | The store uses Agent Zero's `createStore` pattern. The unread signal is chat activity, not a parsed message-author check. |
136
+| Security and index | PASS with WARN | No secrets, subprocesses, dependencies, or outbound calls. The community index already has a related `Chat Status Marklet` plugin, so treat this as a learning example unless you make it clearly different. |
137
+
138
+Status: ready as a local demo plugin. Not ready as a new community submission
139
+until it has a license and a reason to exist separately from similar plugins.
140
+
141
+## Make The Example Yours
142
+
143
+Once the small version works, change only one thing at a time:
144
+
145
+- move the dot to a different place in the row;
146
+- use a badge instead of a dot;
147
+- add a plugin setting for color or animation;
148
+- show a different status for running chats and finished chats;
149
+- turn the plugin into a publishable project with a `LICENSE`, screenshots, and a clearer README.
150
+
151
+Small plugins are good teachers. You can see the whole machine turning without
152
+standing inside the engine.
153
+
154
+## Related
155
+
156
+- [Usage Guide](usage.md#plugins-and-plugin-hub): where plugins appear in the Web UI.
157
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero): source-linked architecture when you need it.
158
+- [Contributing Guide](contribution.md): expectations before sharing changes upstream.
docs/guides/desktop.md
new
+126
@@ -0,0 +1,126 @@
1
+# Desktop Guide
2
+
3
+Agent Zero has its own Linux desktop inside the right-side Canvas.
4
+
5
+Open it by clicking the **Desktop** icon in the Canvas rail. The surface starts
6
+an XFCE desktop that Agent Zero can also control when a task needs a real GUI.
7
+
8
+
9
+
10
+Use the Desktop when the work is visual: opening Linux apps, inspecting files in
11
+a file manager, checking a document layout, or LibreOffice Cowork.
12
+
13
+For architecture and source-linked internals, use
14
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). This page
15
+is the practical tour.
16
+
17
+## What The Desktop Is For
18
+
19
+The Desktop is a live Linux workspace. You can use it yourself, and Agent Zero
20
+can use its Linux Desktop skill to observe the screen, act through the GUI, and
21
+verify what changed.
22
+
23
+Good uses:
24
+
25
+- open the graphical file manager for `Workdir`, `Projects`, `Skills`, `Agents`, or `Downloads`;
26
+- run Linux GUI apps that are available in the Agent Zero environment;
27
+- open a terminal when a visual terminal session is useful;
28
+- inspect or polish LibreOffice Writer, Calc, and Impress files;
29
+- Cowork with the agent in a document, spreadsheet, or presentation.
30
+
31
+For normal web browsing, use the **Browser** surface instead of launching a
32
+browser inside the Desktop. The Browser surface has dedicated page inspection,
33
+screenshots, history, annotations, and host-browser support.
34
+
35
+## Start From The Canvas
36
+
37
+The Desktop lives next to the Browser surface in the Canvas.
38
+
39
+1. Open Agent Zero.
40
+2. Click the **Desktop** icon on the right Canvas rail.
41
+3. Wait for the desktop to finish starting.
42
+4. Click **Open as window** if you want more room.
43
+
44
+The first start after an update can take longer while the Desktop gets ready.
45
+After that, it normally opens much faster.
46
+
47
+## Create Or Open Files
48
+
49
+The Desktop toolbar has a **New** menu.
50
+
51
+
52
+
53
+Use it to create:
54
+
55
+- **Markdown** for notes, drafts, and simple documents;
56
+- **Writer** for LibreOffice text documents;
57
+- **Spreadsheet** for LibreOffice Calc workbooks;
58
+- **Presentation** for LibreOffice Impress decks.
59
+
60
+Use **Open** when you already have a file in the Agent Zero workspace.
61
+
62
+Agent Zero usually creates document files through its document tools first, then
63
+lets you open them in the Desktop when you want to inspect or polish them. That
64
+keeps content changes reliable while still giving you the full GUI when it
65
+matters.
66
+
67
+## Cowork In LibreOffice
68
+
69
+LibreOffice Writer, Calc, and Impress run inside the Desktop.
70
+
71
+
72
+
73
+You can type directly in the app, save, rename, and close the file from the
74
+Canvas header. Agent Zero can also work with the same file: it can create the
75
+first draft, update cells, revise slides, or use the visible Desktop to check
76
+layout before reporting back.
77
+
78
+Good prompts:
79
+
80
+```text
81
+Create a Writer document for this meeting note and open it in Desktop so I can edit with you.
82
+```
83
+
84
+```text
85
+Open this spreadsheet in Calc, add a small summary table, save it, and show me the result in Desktop.
86
+```
87
+
88
+```text
89
+Create a short Impress deck, then use Desktop to check that the slides look clean.
90
+```
91
+
92
+For default formats, think:
93
+
94
+- Writer -> ODT;
95
+- Calc -> ODS;
96
+- Impress -> ODP.
97
+
98
+Ask for DOCX, XLSX, or PPTX only when you need Microsoft Office compatibility.
99
+
100
+## How Agent Zero Uses It
101
+
102
+When you ask for Desktop work, Agent Zero uses a careful loop:
103
+
104
+1. create or edit the file in the most reliable way;
105
+2. open the Desktop only when the GUI is useful;
106
+3. observe the visible state;
107
+4. act through the app when needed;
108
+5. save and verify the result.
109
+
110
+This means the Desktop is not just a remote screen. It is a shared workspace
111
+where the agent can do GUI work and you can take over at any time.
112
+
113
+## Practical Tips
114
+
115
+- Use **Open as window** for large Writer, Calc, or Impress sessions.
116
+- Save before closing if you edited by hand.
117
+- Use Markdown for quick notes and drafts unless you need a LibreOffice file.
118
+- Use Writer, Calc, or Impress when layout, formulas, charts, or slide polish matter.
119
+- If a GUI app feels stuck, ask Agent Zero to verify the Desktop state before continuing.
120
+- Keep the Browser surface for websites and the Desktop surface for Linux apps.
121
+
122
+## Related
123
+
124
+- [Browser Guide](browser.md): web pages, screenshots, annotations, and host-browser mode.
125
+- [Memory Guide](memory.md): what to check when behavior keeps repeating in an unwanted way.
126
+- [Usage Guide](usage.md): the main Web UI workflows in one guided tour.
docs/guides/mcp-setup.md
+101
-48
@@ -1,33 +1,47 @@
1
-# MCP Server Setup
1
+# MCP Setup
2
3
-Agent Zero can connect to external MCP (Model Context Protocol) servers to extend its capabilities with additional tools. This guide shows you how to add MCP servers through the Settings UI.
3
+MCP lets Agent Zero use tools from other apps and services.
4
5
-## What are MCP Servers?
5
+Think of each MCP connection as a bridge. One bridge might connect Gmail,
6
+another might connect a database, and another might connect an automation app.
7
7
-MCP servers are external tools that Agent Zero can use to perform specialized tasks. Popular examples include:
8
-
9
-- **Browser automation** (Chrome DevTools, Playwright)
10
-- **Workflow automation** (n8n)
11
-- **Email operations** (Gmail)
12
-- **Database access** (SQLite)
8
+Use MCP when you have a clear external tool you want Agent Zero to call. For
9
+normal browsing, start with Agent Zero's built-in Browser first.
10
11
> [!NOTE]
15
-> This guide covers connecting to external MCP servers as a client. For exposing Agent Zero as an MCP server, see the [advanced documentation](../developer/mcp-configuration.md).
12
+> This page is about giving Agent Zero tools from other apps. For deeper MCP
13
+> details, see the [advanced MCP reference](../developer/mcp-configuration.md).
14
+
15
+## When To Use MCP
16
+
17
+| Need | Good first stop |
18
+| --- | --- |
19
+| Browse, screenshot, annotate, or use the Docker browser | [Browser Guide](browser.md) |
20
+| Use your host Chrome-family browser through A0 CLI | [A0 CLI Connector](a0-cli-connector.md#host-browser) |
21
+| Connect a third-party app or service with MCP support | This guide |
22
+| Paste or review MCP JSON by hand | [Advanced MCP Configuration](../developer/mcp-configuration.md) |
23
17
-## Adding an MCP Server
24
+## Before You Add One
25
19
-### Step 1: Open MCP Configuration
26
+- [ ] You know what app or service you want to connect.
27
+- [ ] You trust the package or URL.
28
+- [ ] You know where it will run: inside Agent Zero, on your computer, or online.
29
+- [ ] You have any needed credentials ready.
30
+- [ ] You know whether the tool should be project-specific or global.
31
21
-1. Click **Settings** in the sidebar
22
-2. Navigate to the **MCP/A2A** tab
23
-3. Click on **External MCP Servers**
24
-4. Click the **Open** button to access the configuration editor
32
+## Open MCP Settings
33
+
34
+1. Click **Settings** in the sidebar.
35
+2. Open the **MCP/A2A** tab.
36
+3. Find **External MCP Servers**.
37
+4. Click **Open**.
38
39
40
28
-### Step 2: Add Your MCP Server
41
+## Add A Connection
42
30
-In the JSON editor, add your MCP server configuration. Here's a simple example:
43
+The configuration editor accepts JSON. A command-based MCP connection looks like
44
+this:
45
46
```json
47
{
@@ -42,20 +56,36 @@ In the JSON editor, add your MCP server configuration. Here's a simple example:
56
57
58
45
-### Step 3: Apply and Verify
46
-
47
-1. Click **Apply now** to save your configuration
48
-2. The server status will appear below, showing:
49
- - Server name (e.g., `chrome_devtools`)
50
- - Number of available tools
51
- - Connection status (green indicator = connected)
59
+Click **Apply now** after editing.
60
61
> [!TIP]
54
-> The first time you run an `npx`-based MCP server, it may take a few moments to download and initialize.
62
+> The first launch of an `npx` or `uvx` server can take a little longer because
63
+> the package may need to download.
64
56
-## Common MCP Server Examples
65
+## Check That It Connected
66
58
-### Local Command-Based Server
67
+After applying the config, look for the status below the editor.
68
+
69
+| Signal | What it means |
70
+| --- | --- |
71
+| Name | The connection Agent Zero found. |
72
+| Tool count | How many tools are available. |
73
+| Green status | The connection is working. |
74
+| Error text | The command, URL, network, or credentials need attention. |
75
+
76
+MCP tools become available automatically after the connection works.
77
+
78
+You can still ask naturally:
79
+
80
+```text
81
+Use the connected Gmail tools to find the last message from Alice and summarize it.
82
+```
83
+
84
+## Common Examples
85
+
86
+### Tool Started By A Command
87
+
88
+Use this pattern when Agent Zero should start the tool itself.
89
90
```json
91
{
@@ -68,7 +98,9 @@ In the JSON editor, add your MCP server configuration. Here's a simple example:
98
}
99
```
100
71
-### Remote HTTP Server
101
+### Tool At A URL
102
+
103
+Use this pattern when the tool is already running at a URL.
104
105
```json
106
{
@@ -83,35 +115,56 @@ In the JSON editor, add your MCP server configuration. Here's a simple example:
115
}
116
```
117
118
+> [!IMPORTANT]
119
+> Do not paste real API keys into public files, screenshots, or issue reports.
120
+> Prefer project secrets or environment variables when possible.
121
+
122
## Docker Networking
123
88
-If Agent Zero runs in Docker and your MCP server runs on the host:
124
+If Agent Zero runs in Docker and the MCP tool runs somewhere else, the address
125
+matters.
126
90
-- **macOS/Windows:** Use `host.docker.internal` in URLs
91
-- **Linux:** Run the MCP server in the same Docker network and use the container name
127
+| Where the MCP tool runs | What to use from Agent Zero |
128
+| --- | --- |
129
+| Host machine on macOS or Windows | `host.docker.internal` |
130
+| Another container | Same Docker network plus the container name |
131
+| Remote server | The reachable HTTPS URL |
132
+| Inside Agent Zero's container | Local command config |
133
93
-## Using MCP Tools
134
+On Linux, `host.docker.internal` is not always available by default. Running the
135
+MCP tool in the same Docker network is usually cleaner.
136
95
-Once connected, MCP tools become available to Agent Zero automatically. Tools are named with the server prefix, for example:
137
+## Browser MCP Or Built-In Browser?
138
97
-- Server name: `chrome-devtools`
98
-- Tool becomes: `chrome_devtools.navigate_to_url`
139
+For most browsing tasks, use Agent Zero's built-in `_browser` plugin and direct
140
+`browser` tool. It covers the Docker browser surface, screenshots, annotations,
141
+Chrome extensions, and optional A0 CLI host-browser mode.
142
100
-Simply ask Agent Zero to perform tasks, and it will use the appropriate MCP tools when needed.
143
+MCP-based browser tools are still useful when another browser tool is required
144
+for a specific workflow.
145
102
-## Advanced Configuration
146
+See the [Browser Guide](browser.md) for the built-in workflow.
147
104
-For detailed configuration options, server types, environment variables, and troubleshooting, see the [Advanced MCP Configuration Guide](../developer/mcp-configuration.md).
148
+## Recommended Server Types
149
106
-## Recommended MCP Servers
150
+| Tool type | Useful for |
151
+| --- | --- |
152
+| Chrome DevTools MCP | Direct Chrome debugging/control workflows |
153
+| Playwright MCP | Alternative browser automation stacks |
154
+| n8n MCP | Workflow automation |
155
+| Gmail MCP | Email workflows |
156
+| VS Code MCP | IDE-centered workflows |
157
108
-Community-tested and reliable MCP servers:
158
+## Troubleshooting
159
110
-- **Chrome DevTools MCP** - Direct Chrome control
111
-- **Playwright MCP** - Cross-browser automation
112
-- **n8n MCP** - Workflow automation
113
-- **Gmail MCP** - Email management
114
-- **VSCode MCP** - IDE workflows
160
+- **No tools appear:** confirm the JSON is valid and click **Apply now** again.
161
+- **Command not found:** install the command where Agent Zero can run it, or use a URL-based tool instead.
162
+- **Package launch is slow:** wait for the first package download to finish.
163
+- **Host service unreachable:** check Docker networking and try `host.docker.internal` on macOS or Windows.
164
+- **Credentials fail:** rotate or re-enter the credential, then restart or reapply the config.
165
116
-> [!TIP]
117
-> For browser automation tasks, the built-in `_browser` plugin and direct `browser` tool cover the default workflow. MCP-based browser tools are still useful when you need a different browser stack, remote browser control, or an alternative to the built-in Playwright Chromium (preinstalled in Docker; on demand via `ensure_playwright_binary()` in local dev).
166
+## Related
167
+
168
+- [Browser Guide](browser.md): built-in browsing, screenshots, annotations, Docker browser, and host-browser mode.
169
+- [A0 CLI Connector](a0-cli-connector.md): host-machine access and Bring Your Own Browser setup.
170
+- [Advanced MCP Configuration](../developer/mcp-configuration.md): complete configuration reference.
docs/guides/memory.md
new
+142
@@ -0,0 +1,142 @@
1
+# Memory Guide
2
+
3
+Agent Zero can remember useful facts, solutions, preferences, and imported
4
+knowledge so future chats do not always start from zero.
5
+
6
+That power needs curation. Long-term AI memory is not a solved problem, even for
7
+large AI labs and companies. A memory system can help the agent become more
8
+useful, but it can also preserve stale assumptions, wrong conclusions, old test
9
+data, or instructions that no longer fit. A sustainable memory system needs some
10
+human gardening.
11
+
12
+When Agent Zero does something unexpected, keeps repeating a bad habit, or seems
13
+strangely confident about the wrong thing, Memory is one of the first places to
14
+look.
15
+
16
+## Open Memory
17
+
18
+Open **Memory** from the dashboard or sidebar.
19
+
20
+
21
+
22
+The dashboard shows remembered entries and imported knowledge chunks. Each row
23
+has metadata, a content preview, copy and delete actions, and a detail view.
24
+
25
+## Search And Filter
26
+
27
+Use the controls at the top to narrow what you are looking at.
28
+
29
+
30
+
31
+The most useful controls are:
32
+
33
+- **Memory Directory:** choose the memory store you want to inspect.
34
+- **Area:** filter between `main`, `fragments`, `solutions`, and `skills`.
35
+- **Search:** find memories related to a phrase, behavior, project, tool, error, or preference.
36
+- **Threshold:** adjust how strict the similarity match should be.
37
+- **Limit:** control how many results are returned.
38
+- **Clear:** reset the filters.
39
+
40
+Start with ordinary words. If Agent Zero keeps using the wrong command, search
41
+for the command. If it keeps assuming the wrong project rule, search for the
42
+rule, client name, repo name, or phrase it keeps repeating.
43
+
44
+## Inspect And Edit
45
+
46
+Click a memory row to open its details.
47
+
48
+
49
+
50
+In the detail view you can:
51
+
52
+- read the full content;
53
+- check whether it came from conversation memory or imported knowledge;
54
+- copy the memory with metadata;
55
+- copy only the content;
56
+- edit the text;
57
+- delete the entry.
58
+
59
+Edit a memory when it is almost right but needs correction. Delete it when it is
60
+wrong, obsolete, duplicated, too vague, or harmful to future reasoning.
61
+
62
+## What To Keep
63
+
64
+Good memories are durable and useful:
65
+
66
+- stable user preferences;
67
+- project-specific conventions;
68
+- commands that were verified and still apply;
69
+- decisions that should persist across chats;
70
+- known solutions to recurring problems;
71
+- important constraints that are not obvious from files alone.
72
+
73
+Good memory reads like a note you would happily give a future teammate.
74
+
75
+## What To Remove
76
+
77
+Remove or rewrite memories that are likely to poison future processing:
78
+
79
+- stale setup instructions;
80
+- old paths, ports, service names, or commands;
81
+- temporary experiments;
82
+- failed guesses saved as facts;
83
+- outdated project decisions;
84
+- broad personality instructions that make the agent overcorrect;
85
+- private data that should not have been remembered;
86
+- memories copied from a confused or interrupted chat.
87
+
88
+The danger is not that one bad memory always wins. The danger is that it becomes
89
+one more piece of "evidence" nudging the agent in the wrong direction again and
90
+again.
91
+
92
+## When Behavior Looks Wrong
93
+
94
+Check Memory early when Agent Zero:
95
+
96
+- keeps following an old instruction after you corrected it;
97
+- keeps using a tool, path, or workflow you no longer want;
98
+- mixes two projects together;
99
+- remembers a false preference;
100
+- repeats a wrong explanation;
101
+- ignores current project instructions in favor of old context;
102
+- acts as if a test result or setup step happened when it did not.
103
+
104
+A good debugging loop is:
105
+
106
+1. Search Memory for the repeated behavior or phrase.
107
+2. Open likely entries and read the full content.
108
+3. Edit entries that are useful but inaccurate.
109
+4. Delete entries that are simply wrong.
110
+5. Run the task again with a clear correction in the chat.
111
+
112
+## Use Project Memory For Project Context
113
+
114
+Keep project-specific memories in the project where they belong. Client rules,
115
+repository conventions, local commands, and workflow preferences should not leak
116
+into unrelated work.
117
+
118
+If Agent Zero is mixing contexts, check whether the memory belongs in global
119
+memory or project memory. Moving from "global forever" to "this project only" is
120
+one of the simplest ways to keep the system sane.
121
+
122
+## Be Careful With Bulk Cleanup
123
+
124
+The dashboard can select multiple rows and copy, export, or delete them.
125
+
126
+Before deleting many memories:
127
+
128
+- export or back up important entries;
129
+- search narrowly instead of deleting by broad category;
130
+- delete obvious junk first;
131
+- keep useful solutions even if they are old;
132
+- avoid wiping imported knowledge unless you know how to rebuild it.
133
+
134
+Memory curation is not about making the database empty. It is about keeping the
135
+right signal and removing the noise that makes the agent less trustworthy.
136
+
137
+## Related
138
+
139
+- [Usage Guide](usage.md): where Memory fits in the everyday Agent Zero workflow.
140
+- [Projects Guide](projects.md): how project memory keeps client, repo, and task context separated.
141
+- [Troubleshooting](troubleshooting.md): quick checks when Agent Zero behaves unexpectedly.
142
+- [Backup And Restore](usage.md#backup-and-restore): what to do before large memory cleanup.
docs/guides/model-presets.md
new
+84
@@ -0,0 +1,84 @@
1
+# Model Presets
2
+
3
+Model Presets are named shortcuts for model choices.
4
+
5
+Use them when you want to switch a chat between setups such as "fast", "cheap",
6
+"local", "balanced", or "maximum power" without rebuilding the settings each
7
+time.
8
+
9
+## Choose A Preset
10
+
11
+The preset menu is the first dropdown on the left side of the chat status bar.
12
+
13
+
14
+
15
+1. Open a chat.
16
+2. Click the current preset name.
17
+3. Choose the preset you want.
18
+
19
+The selected preset affects the current chat.
20
+
21
+## Edit Presets
22
+
23
+Click **Edit presets** from the same menu.
24
+
25
+
26
+
27
+From this screen you can:
28
+
29
+- rename presets;
30
+- choose the main model;
31
+- choose the utility model;
32
+- open API key settings;
33
+- save the preset list.
34
+
35
+Think of a preset as a label on a model setup.
36
+
37
+| Field | Simple meaning |
38
+| --- | --- |
39
+| **Main model** | The model that does the main conversation and reasoning. |
40
+| **Utility model** | A smaller helper model for lighter internal tasks. |
41
+
42
+## Add A Preset
43
+
44
+Click **Add Preset**, give it a name, choose models, then click **Save Presets**.
45
+
46
+
47
+
48
+Good preset names are easy to spot quickly:
49
+
50
+- `Max Power`
51
+- `Balanced`
52
+- `Fast Cheap`
53
+- `Local Private`
54
+- `GPT-5 Mini`
55
+- `Claude Opus`
56
+- `Kimi Budget`
57
+
58
+Some people prefer names based on purpose. Others prefer names that look like
59
+the model they use most. Both are fine. The important thing is that your eyes
60
+can find the right option quickly.
61
+
62
+## A Simple Starting Set
63
+
64
+If you are not sure what to create, start with three presets:
65
+
66
+| Preset | Use it for |
67
+| --- | --- |
68
+| **Best** | Hard work where quality matters more than cost or speed. |
69
+| **Balanced** | Everyday chats, coding, writing, and research. |
70
+| **Cheap** | Simple tasks, quick drafts, summaries, and tests. |
71
+
72
+You can always rename them later.
73
+
74
+## How Presets Fit With Other Controls
75
+
76
+| Control | What it changes |
77
+| --- | --- |
78
+| **Model Preset** | Which models power the chat. |
79
+| **Agent Profile** | The agent's role, tone, and prompt behavior. |
80
+| **Project** | Workspace, files, memory, secrets, and project instructions. |
81
+| **Skill** | A specific procedure added to prompt extras. |
82
+
83
+For example, you can use the same "Researcher" Agent Profile with a cheaper
84
+preset for simple questions and a stronger preset for difficult investigations.
docs/guides/projects.md
+122
-443
@@ -1,518 +1,197 @@
1
-# Working with Projects
1
+# Projects
2
3
-Projects are one of Agent Zero's most powerful features for organizing your work. They create isolated workspaces with dedicated context, instructions, memory, and secrets - preventing context bleed between unrelated tasks or clients.
3
+Projects tell Agent Zero what world it is working in.
4
5
-This tutorial will guide you through creating, configuring, and using projects effectively.
5
+Use a project when you want a chat to have its own purpose, instructions, files,
6
+memory, secrets, and model choices. A project can be a client, a codebase, a
7
+research topic, a recurring workflow, or any other focused workspace.
8
7
-## What Are Projects?
9
+
10
9
-A project in Agent Zero is an isolated workspace that includes:
11
+## When To Use One
12
11
-- **Dedicated folder structure** under `/a0/usr/projects/<project_name>/`
12
-- **Custom instructions** automatically injected into the agent's system prompt
13
-- **Isolated or shared memory** to prevent context pollution
14
-- **Project-specific secrets and variables** for secure credential management
15
-- **Custom agent configurations** including subagent settings
16
-- **Knowledge base integration** with project-scoped documents
17
-- **Git repository integration** for version-controlled codebases
18
-- **File structure injection** for automatic codebase awareness
13
+Create a project when you want Agent Zero to remember context that should not
14
+leak into every other chat.
15
20
-Think of projects as separate "personas" or "modes" for your agent - each with its own context, memory, and capabilities.
16
+Good project examples:
17
22
-## Creating Your First Project
18
+- A Git repository you want Agent Zero to work on.
19
+- A client workspace with its own tone, files, and credentials.
20
+- A research topic with its own sources and notes.
21
+- A recurring report that always follows the same steps.
22
+- A documentation workspace with a clear writing style.
23
24
-There are two ways to access the Projects interface:
24
+Stay in a normal chat when the task is quick, disposable, or unrelated to a
25
+larger body of work.
26
26
-### Method 1: Dashboard Access
27
-1. Open the **Dashboard** from the sidebar
28
-2. Click the **Projects** button
29
-3. The Projects modal will open
27
+## Open Projects
28
31
-### Method 2: Quick Access
32
-1. Look at the top-right corner of the interface where it shows **"No project"**
33
-2. Click on it to open the project dropdown
34
-3. If you have no projects yet, click **"Projects"** to open the modal
29
+From the dashboard, click **Projects**.
30
36
-
31
+
32
38
-### Creating an Empty Project
33
+If you have no projects yet, the list starts empty and offers **Create
34
+project**.
35
40
-Once in the Projects modal:
36
+
37
42
-1. Click **"Create project"** button
43
-2. You'll see the project creation wizard
38
+## Create A Project
39
45
-
40
+Click **Create project** and give it a clear title. The title is what you will
41
+recognize later in the project picker.
42
47
-The wizard includes:
43
+
44
49
-- **Title**: A human-readable name displayed in the UI
50
-- **Color tag**: Visual identifier for quick recognition (choose from the color palette)
51
-- **Git Repository** (optional): URL to clone a repository (see next section)
45
+For a simple project, the title is enough. If you want Agent Zero to clone a
46
+repository into the project, paste the Git URL in **Git Repository** before you
47
+continue.
48
53
-> [!TIP]
54
-> Choose meaningful titles and distinct colors, especially if you plan to work with multiple projects. This helps you quickly identify which project is active.
49
+After creating the project, Agent Zero opens the edit screen.
50
56
-### Creating a Git-Based Project
51
+## Write Helpful Instructions
52
58
-Agent Zero's **Git Projects** feature allows you to clone repositories directly into your project workspace:
53
+The most important part of a project is the **Instructions** field.
54
60
-1. In the creation form, enter a Git repository URL in the **Git Repository** field
61
- - Supports both public and private repositories
62
- - For private repositories, you can provide an authentication token
63
-2. Click **"Create and continue"**
64
-3. Agent Zero will clone the repository
55
+Description answers: "What is this project?"
56
66
-
57
+Instructions answer: "How should Agent Zero behave when this project is active?"
58
68
-The cloning process:
69
-- Downloads the repository to `/a0/usr/projects/<project_name>/`
70
-- By default, clones the `main` branch
71
-- Supports authentication via token (stored securely, never in URLs)
72
-- You can ask the agent to checkout different branches later
59
+
60
74
-
61
+Good instructions are usually short and specific. Tell Agent Zero:
62
76
-After cloning completes, you'll see:
77
-- Repository URL
78
-- Current branch
79
-- Clean/dirty status
80
-- Last commit information
63
+- what the project is for,
64
+- what style of answer you want,
65
+- where files should be read or written,
66
+- what quality rules matter,
67
+- when it should ask before acting.
68
82
-> [!NOTE]
83
-> If the cloned repository already contains a `.a0proj/` folder with `project.json`, Agent Zero will merge the existing configuration with your specified title and color preferences.
69
+Example:
70
85
-## Project Configuration
86
-
87
-Once created, you can configure your project through the Edit Project interface:
88
-
89
-
90
-
91
-### Description and Instructions
92
-
93
-#### Description
94
-The **Description** field helps both you and the agent understand the project's purpose. This is purely informational and helps provide context when switching between projects.
95
-
96
-**Example:**
97
-```
98
-An intelligent Excel automation system that processes financial spreadsheets
99
-from multiple sources, performs data validation and cleaning, consolidates
100
-information, generates executive reports, and flags anomalies or compliance issues.
101
-```
102
-
103
-#### Instructions
104
-The **Instructions** field is critical - these are automatically injected into the agent's system prompt when the project is active. Write clear, specific instructions that guide the agent's behavior for this project.
105
-
106
-**Example:**
71
```markdown
108
-## Your Role
109
-You are an expert Financial Data Analyst and Excel Automation Specialist.
110
-Your job is to process, analyze, and report on financial spreadsheet data
111
-with precision and business acumen.
112
-
113
-## Operational Context
114
-- Work directory: `/usr/projects/excel-finance/`
115
-- Input data location: `/usr/projects/excel-finance/data/incoming/`
116
-- Processed files: `/usr/projects/excel-finance/data/processed/`
117
-- Reports output: `/usr/projects/excel-finance/reports/`
118
-- Templates: `/usr/projects/excel-finance/templates/`
119
-
120
-## Core Responsibilities
121
-
122
-### 1. Data Ingestion & Discovery
123
-- Scan `/data/incoming/` for new Excel/CSV files
124
-- Identify data types, sheets, and file structures
125
-- Log source details and timestamps
126
-
127
-### 2. Data Validation & Cleaning
128
-- Check for missing values, duplicates, and format inconsistencies
129
-- Validate numerical ranges and date formats
130
-- Flag suspicious patterns or outliers
131
-- Document all cleaning operations
132
-
133
-### 3. Data Consolidation
134
-- Merge data from multiple sources
135
-- Normalize column names and formats
136
-- Handle currency conversions and date standardization
137
-- Create master datasets for reporting
138
-
139
-### 4. Executive Reporting
140
-- Generate summary reports using templates in `/templates/`
141
-- Include key metrics, trends, and visualizations
142
-- Highlight anomalies and compliance issues
143
-- Export as formatted Excel files with proper styling
144
-
145
-### 5. Compliance & Quality Checks
146
-- Flag potential compliance issues
147
-- Verify calculations and formulas
148
-- Maintain audit trail of all operations
149
-- Alert on critical errors or anomalies
150
-
151
-## Quality Standards
152
-- Always validate input data before processing
153
-- Use professional Excel formatting in outputs
154
-- Include metadata (processing date, sources, versions)
155
-- Document assumptions and limitations
156
-- Provide clear error messages and suggestions
157
-```
158
-
159
-> [!IMPORTANT]
160
-> Well-written instructions are the key to effective project-specific agent behavior. Be specific about:
161
-> - The agent's role and expertise level
162
-> - Directory paths and file locations
163
-> - Expected workflows and procedures
164
-> - Quality standards and validation rules
165
-> - Output formats and requirements
72
+You are working inside the Docs Example Workspace.
73
167
-### Additional Instruction Files
74
+Use this project for small documentation examples and user-facing guidance.
75
169
-Besides the main instructions field, you can add multiple instruction files in the `.a0proj/instructions/` directory. These are automatically loaded and concatenated with the main instructions.
170
-
171
-This is useful for:
172
-- Organizing complex instructions into logical sections
173
-- Sharing common instructions across similar projects
174
-- Version controlling instruction updates via Git
175
-
176
-### Memory Isolation
76
+When this project is active:
77
+- Explain steps in plain language before technical detail.
78
+- Prefer screenshots, checklists, and concrete examples.
79
+- Keep generated files inside this project unless I ask otherwise.
80
+- Ask before using credentials, private data, or external accounts.
81
+- When editing docs, focus on what the user sees and what they should do next.
82
+```
83
178
-Projects support two memory modes:
84
+That is enough. A project prompt does not need to be a constitution. Start small,
85
+then improve it when you notice what the agent should do differently.
86
180
-- **Own memory** (default): The project has its own isolated memory directory
181
-- **Global memory**: The project shares the default memory pool
87
+## Activate A Project
88
183
-> [!TIP]
184
-> Use **own memory** for:
185
-> - Client projects with confidential information
186
-> - Different programming languages/frameworks
187
-> - Distinct domains (e.g., finance vs. marketing)
188
->
189
-> Use **global memory** for:
190
-> - Related sub-projects in the same domain
191
-> - When you want the agent to remember across all work
192
-> - Personal projects without sensitive data
89
+Open or create a chat. In the top-right corner, click the project picker. It may
90
+say **No project** if the chat is not attached to a project yet.
91
194
-### Variables and Secrets
92
+
93
196
-Projects support scoped configuration values:
94
+Choose your project.
95
198
-#### Variables (Non-sensitive)
199
-Stored in `.a0proj/variables.env`:
200
-```bash
201
-API_BASE_URL=https://api.example.com
202
-DEFAULT_TIMEOUT=30
203
-OUTPUT_FORMAT=json
204
-LOG_LEVEL=info
205
-```
96
+
97
207
-#### Secrets (Sensitive)
208
-Stored in `.a0proj/secrets.env`:
209
-```bash
210
-API_KEY=sk-abc123xyz...
211
-DATABASE_PASSWORD=super_secret_pwd
212
-GITHUB_TOKEN=ghp_xyz789...
213
-SMTP_PASSWORD=email_pwd_here
214
-```
98
+When the project name appears in the top bar, the chat is now using that
99
+project. Agent Zero will use the project instructions and work with the project
100
+workspace for that chat.
101
216
-> [!IMPORTANT]
217
-> - Secrets are stored locally in the container
218
-> - They are masked in the UI when editing
219
-> - Backups may not include secrets - keep a separate copy
220
-> - Reference secrets in prompts by name: "Use my `API_KEY` to authenticate"
102
+Each chat can use a different project. This lets you keep a client chat, a code
103
+chat, and a research chat separate at the same time.
104
222
-### Subagent Configuration
105
+## What Changes After Activation
106
224
-Projects can enable or disable specific subagents. This is configured via the UI and stored in `.a0proj/agents.json`. The browser tool is not a subagent; it is a built-in plugin.
107
+When a project is active, Agent Zero can use:
108
226
-### Project LLM Configuration
109
+- the project instructions,
110
+- files stored in the project workspace,
111
+- project memory,
112
+- project variables and secrets,
113
+- project-specific model settings when configured.
114
228
-Projects can carry their own model settings without adding model data to `.a0proj/project.json`. The selected project model config is stored in the `_model_config` plugin's project-scoped path:
115
+Try prompts like:
116
117
```text
231
-/a0/usr/projects/<project_name>/.a0proj/plugins/_model_config/config.json
118
+Read the project instructions and tell me how you will work in this workspace.
119
```
120
234
-Project-only presets are stored next to that config:
235
-
121
```text
237
-/a0/usr/projects/<project_name>/.a0proj/plugins/_model_config/presets.yaml
122
+Create a short README for this project based on its current files.
123
```
124
240
-The project preset YAML is the same plain list used by global model presets:
241
-
242
-```yaml
243
-- name: Research
244
- chat:
245
- provider: openrouter
246
- name: anthropic/claude-sonnet-4.6
247
- api_base: ""
248
- ctx_length: 200000
249
- ctx_history: 0.7
250
- vision: true
251
- utility:
252
- provider: openrouter
253
- name: openai/gpt-5.4-mini
254
- api_base: ""
255
- ctx_length: 128000
256
- ctx_input: 0.7
257
-```
258
-
259
-When you select a preset for a project, Agent Zero copies the preset's chat and utility settings into the project config. It does not keep a live link to the preset, and embedding model settings remain copied from the current effective config.
260
-
261
-### Knowledge Files
262
-
263
-Import project-specific knowledge documents:
264
-1. Use the **Import Knowledge** button in the project interface
265
-2. Files are stored in `.a0proj/knowledge/` organized by memory area
266
-3. The agent can reference this knowledge when the project is active
267
-
268
-### File Structure Injection
269
-
270
-Projects can automatically inject their directory structure into the agent's context:
271
-
272
-**Settings (configurable per project):**
273
-- **Enabled**: Toggle automatic file tree injection
274
-- **Max depth**: How many directory levels to scan (default: 5)
275
-- **Max files**: Maximum files to include (default: 20)
276
-- **Max folders**: Maximum folders to include (default: 20)
277
-- **Max lines**: Maximum lines in the output (default: 250)
278
-- **Gitignore patterns**: Filter out unwanted files
279
-
280
-The default gitignore for projects excludes:
281
-```
282
-.a0proj/
283
-venv/
284
-__pycache__/
285
-node_modules/
286
-.npm/
287
-.git/
125
+```text
126
+Use this project as the home for our weekly research notes.
127
```
128
290
-This feature is incredibly useful for code projects - the agent automatically "sees" your project structure and can navigate it intelligently.
291
-
292
-## Activating a Project
129
+## Git Projects
130
294
-To use a project, you need to activate it for your current chat:
131
+If you paste a Git repository URL while creating the project, Agent Zero clones
132
+that repository into the project workspace.
133
296
-### In a New Chat
297
-1. Activate a project from the Projects modal or dropdown
298
-2. Start a new chat
299
-3. The project is automatically active for that chat
134
+
135
301
-### In an Existing Chat
302
-1. Click the project dropdown in the top-right corner (where it shows current project or "No project")
303
-2. Select the desired project from the list
304
-3. The project activates immediately for this chat
136
+Use Git projects when you want Agent Zero to work on a real codebase with the
137
+right local files, branch state, and project instructions.
138
306
-
139
+For private repositories, use a token when the UI asks for one. Do not paste
140
+tokens into chat messages.
141
308
-> [!NOTE]
309
-> Each chat can have its own active project. You can have multiple chats open with different projects active simultaneously.
142
+## Variables And Secrets
143
311
-### First Interaction After Activation
144
+Projects can store values that only make sense inside that workspace.
145
313
-Once activated, the agent's behavior changes according to the project's configuration:
146
+Use **variables** for non-sensitive settings, such as:
147
315
-
316
-
317
-The agent now:
318
-- Has access to project-specific instructions
319
-- Uses project-isolated memory (if configured)
320
-- Can reference project secrets and variables
321
-- Sees the project file structure (if enabled)
322
-- Operates within the project's working directory
323
-
324
-**Example prompt after activation:**
325
-```
326
-Hi A0. Start first development phase:
327
-- recon
328
-- scope definition
329
-- AGENTS.md generation
148
+```text
149
+REPORT_FORMAT=markdown
150
+DEFAULT_REGION=eu-west
151
```
152
332
-The agent will understand the context based on the project's instructions and work accordingly.
333
-
334
-## Project Directory Structure
153
+Use **secrets** for credentials, such as API keys and passwords. Refer to them by
154
+name in chat:
155
336
-Understanding the project directory structure helps you work effectively:
337
-
338
-```
339
-/a0/usr/projects/<project_name>/
340
-├── .a0proj/ # Project metadata (hidden)
341
-│ ├── project.json # Main configuration
342
-│ ├── variables.env # Non-sensitive variables
343
-│ ├── secrets.env # Sensitive credentials
344
-│ ├── agents.json # Subagent settings
345
-│ ├── instructions/ # Additional instruction files
346
-│ │ ├── 01-setup.md
347
-│ │ ├── 02-workflow.md
348
-│ │ └── ...
349
-│ └── knowledge/ # Project knowledge files
350
-│ ├── main/
351
-│ ├── fragments/
352
-│ └── ...
353
-├── src/ # Your actual project files
354
-├── data/ # Data files
355
-├── docs/ # Documentation
356
-└── ... # Other project content
156
+```text
157
+Use the project GITHUB_TOKEN to check the repository status.
158
```
159
359
-> [!TIP]
360
-> The `.a0proj/` folder is automatically excluded from file structure injection (via gitignore patterns) to keep the agent's context clean.
160
+Keep your own copy of important secrets. Backups may not include every secret.
161
362
-## Advanced Use Cases
162
+## Keep Projects Tidy
163
364
-### Multi-Client Agency Work
164
+A good project stays useful because it stays focused.
165
366
-Use projects to isolate each client:
166
+- Use a clear title.
167
+- Keep instructions short enough to read.
168
+- Store files where the project expects them.
169
+- Keep secrets scoped to the project that needs them.
170
+- Update instructions when your workflow changes.
171
+- Create a new project when the work belongs to a different client, codebase, or topic.
172
368
-```
369
-/usr/projects/client-acme/
370
-/usr/projects/client-globex/
371
-/usr/projects/client-initech/
372
-```
173
+## Common Problems
174
374
-Each with:
375
-- Client-specific instructions and context
376
-- Isolated memory (no data leakage)
377
-- Client API keys and credentials
378
-- Project-specific knowledge bases
175
+**Agent Zero ignores the project.**
176
+Check the top-right project picker. The project name must be visible in the
177
+active chat.
178
380
-### Multi-Language Development
179
+**The project instructions are wrong or stale.**
180
+Open **Projects**, click the edit icon, update the instructions, and save.
181
382
-Create projects for different tech stacks:
182
+**A Git repository did not clone.**
183
+Check the URL, authentication token, and network access. For private repos,
184
+create a fresh token and try again.
185
384
-```
385
-/usr/projects/python-ml-research/
386
-/usr/projects/nodejs-webapp/
387
-/usr/projects/go-microservices/
388
-```
389
-
390
-Each with language-specific:
391
-- Code patterns and best practices
392
-- Framework documentation
393
-- Linting and formatting rules
394
-
395
-### Domain-Specific Work
186
+**Secrets are not being used.**
187
+Make sure the secret is saved in the project and refer to it by exact name.
188
397
-Organize by business domain:
189
+**The project has become too broad.**
190
+Split it. Projects work best when each one has a clear job.
191
399
-```
400
-/usr/projects/finance-automation/
401
-/usr/projects/marketing-analytics/
402
-/usr/projects/hr-automation/
403
-```
192
+## Related
193
405
-Each with domain-specific:
406
-- Terminology and concepts
407
-- Industry standards and regulations
408
-- Specialized tools and APIs
409
-
410
-## Combining Projects with Tasks
411
-
412
-Projects work exceptionally well with Agent Zero's **Tasks & Scheduling** feature:
413
-
414
-1. Create a project for a specific domain (e.g., "Daily Email Reports")
415
-2. Configure project instructions for the recurring task
416
-3. Schedule a task that activates this project
417
-4. The task runs in isolation with project-specific context
418
-
419
-**Example:**
420
-- **Project**: "Daily Sales Summary"
421
-- **Instructions**: "Fetch yesterday's sales data, generate summary report, email to team"
422
-- **Task**: Scheduled daily at 8 AM
423
-- **Result**: Consistent, context-aware automated reporting
424
-
425
-See [Tasks & Scheduling](usage.md#tasks--scheduling) for more details.
426
-
427
-## Best Practices
428
-
429
-### Instruction Writing
430
-- **Be specific**: Don't say "analyze data" - specify format, methods, and output
431
-- **Include paths**: Always mention where files should be read/written
432
-- **Define quality standards**: What constitutes "good" output?
433
-- **Specify error handling**: How should the agent respond to issues?
434
-- **Use markdown formatting**: Clear sections and lists improve readability
435
-
436
-### Memory Management
437
-- Use **own memory** by default for client work
438
-- Use **global memory** only when projects truly need shared knowledge
439
-- Regularly review and clean project memory via the Memory Dashboard
440
-- Clear memory when archiving completed projects
441
-
442
-### Security
443
-- Never commit `.a0proj/secrets.env` to version control
444
-- Use project-scoped secrets instead of global secrets for sensitive work
445
-- Consider separate projects for different security levels
446
-- Backup secrets manually - they may not be included in automatic backups
447
-
448
-### Organization
449
-- Use clear, descriptive project names
450
-- Choose distinct colors for visual identification
451
-- Keep instructions updated as project scope evolves
452
-- Document any manual setup steps in project instructions
453
-
454
-### Performance
455
-- Adjust file structure injection limits based on project size
456
-- Use gitignore patterns to exclude large build artifacts
457
-- Consider disabling file structure injection for very large codebases
458
-- Monitor memory growth and clean periodically
459
-
460
-## Troubleshooting
461
-
462
-### Project Not Loading Instructions
463
-**Problem**: Agent doesn't seem to follow project instructions
464
-
465
-**Solutions**:
466
-- Verify project is actually activated (check top-right dropdown)
467
-- Check instructions are saved (edit project and verify content)
468
-- Look for syntax errors in instructions markdown
469
-- Try deactivating and reactivating the project
470
-
471
-### Memory Not Isolated
472
-**Problem**: Agent remembers things from other projects
473
-
474
-**Solutions**:
475
-- Check project memory setting is "own" not "global"
476
-- Deactivate and reactivate the project
477
-- Clear the project's memory directory via Memory Dashboard
478
-- Restart chat context if necessary
479
-
480
-### Git Clone Failures
481
-**Problem**: Repository won't clone
482
-
483
-**Solutions**:
484
-- Verify the Git URL is correct
485
-- For private repos, ensure you provided a valid token
486
-- Check network connectivity
487
-- Try cloning manually via terminal to diagnose issue
488
-- Look for error messages in console/logs
489
-
490
-### Secrets Not Available
491
-**Problem**: Agent can't access project secrets
492
-
493
-**Solutions**:
494
-- Verify secrets are saved in project settings
495
-- Check secret variable names match what you're referencing
496
-- Try referencing by exact name: "use my `API_KEY`"
497
-- Ensure project is activated for current chat
498
-
499
-### File Structure Not Showing
500
-**Problem**: Agent doesn't see project files
501
-
502
-**Solutions**:
503
-- Enable file structure injection in project settings
504
-- Increase max_files/max_folders limits
505
-- Check gitignore patterns aren't too restrictive
506
-- Verify files exist in project directory
507
-
508
-## Next Steps
509
-
510
-Now that you understand projects, explore:
511
-
512
-- [Tasks & Scheduling](usage.md#tasks--scheduling) - Automate project-based work
513
-- [Memory Management](usage.md#memory-management) - Maintain project knowledge
514
-- [Backup & Restore](usage.md#backup--restore) - Preserve project configurations
515
-- [Extensions](../developer/extensions.md) - Extend project capabilities
516
-
517
-> [!TIP]
518
-> Start with a simple project to learn the system, then gradually add complexity. Projects are most powerful when instructions are well-crafted and memory is properly managed.
194
+- [Usage Guide](usage.md)
195
+- [Browser Guide](browser.md)
196
+- [A0 CLI Connector](a0-cli-connector.md)
197
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
docs/guides/self-update.md
+2
-2
@@ -18,7 +18,7 @@ Agent Zero includes a Docker-oriented self-update flow for switching to a specif
18
19
## How it works
20
21
-1. The WebUI writes a YAML request file outside `/a0` so the request survives upgrades and downgrades.
21
+1. The Web UI writes a YAML request file outside `/a0` so the request survives upgrades and downgrades.
22
2. Agent Zero restarts.
23
3. The durable updater in `/exe` reads the YAML request before starting the UI.
24
4. It cleans the root `uv` cache when `uv` is available.
@@ -45,7 +45,7 @@ The updater automatically creates a backup of `a0/usr`.
45
46
## Version selection
47
48
-The WebUI preloads repository version choices for the selected branch into a standard selector.
48
+The Web UI preloads repository version choices for the selected branch into a standard selector.
49
50
Only versions from the current major release line are listed in the selector. If newer major lines are available on the selected branch, the UI shows an attention banner that links to the Docker update guide.
51
docs/guides/skills.md
new
+71
@@ -0,0 +1,71 @@
1
+# Skills
2
+
3
+Skills are focused instructions Agent Zero can load when a task needs them.
4
+
5
+Most of the time, you do not need to think about skills. Ask for the work you
6
+want, and Agent Zero can load a matching skill on demand.
7
+
8
+You can also pin a skill yourself from the chat input when you want it to stay
9
+active for the current conversation.
10
+
11
+## Open The Skills Selector
12
+
13
+1. Open a chat.
14
+2. Click the **+** button in the chat input area.
15
+3. Click **Skills**.
16
+
17
+
18
+
19
+The selector opens with a searchable list of skills.
20
+
21
+
22
+
23
+## Add Or Remove A Skill
24
+
25
+Click a skill to add it. Active skills are shown at the top of the selector.
26
+
27
+
28
+
29
+To remove a skill, use the remove button in **Active skills** or uncheck it in
30
+the list.
31
+
32
+Active skills are added to the **Extras** part of the system prompt. That means
33
+Agent Zero sees them every turn while they are active.
34
+
35
+> [!TIP]
36
+> Keep this list short. Pin the skills you really want present all the time, and
37
+> let Agent Zero load the rest only when it needs them.
38
+
39
+## When To Pin A Skill
40
+
41
+Pin a skill when the current chat should keep following the same special
42
+procedure.
43
+
44
+Good examples:
45
+
46
+- creating an Agent Profile;
47
+- reviewing a plugin;
48
+- following a writing format;
49
+- working with a repeated data-cleaning recipe;
50
+- keeping a project-specific checklist visible during a long chat.
51
+
52
+Do not pin a skill just because it might be useful someday. A lighter prompt is
53
+usually easier for the agent to follow.
54
+
55
+## Skills, Profiles, And Projects
56
+
57
+| Control | What it changes |
58
+| --- | --- |
59
+| **Skills** | Adds a specific procedure to the current prompt extras. |
60
+| **Agent Profiles** | Changes the broader role and behavior of the chat. |
61
+| **Projects** | Adds workspace, files, memory, secrets, and project instructions. |
62
+
63
+If Agent Zero starts following an old procedure you no longer want, open the
64
+Skills selector and remove any active skill that does not belong in the chat.
65
+
66
+## Creating Skills
67
+
68
+This page is about using skills in the Web UI.
69
+
70
+If you want to write or contribute a skill, see
71
+[Contributing Skills](../developer/contributing-skills.md).
docs/guides/troubleshooting.md
+28
-6
@@ -8,7 +8,7 @@ This page addresses frequently asked questions (FAQ) and provides troubleshootin
8
**2. When I input something in the chat, nothing happens. What's wrong?**
9
- Check if you have set up API keys in the Settings page. If not, the application cannot call LLM providers.
10
11
-**3. I get “Invalid model ID.” What does that mean?**
11
+**3. I get "Invalid model ID." What does that mean?**
12
- Verify the **provider** and **model naming**. For example, `openai/gpt-5.3` is correct for OpenRouter, but **incorrect** for the native OpenAI provider, which goes without prefix.
13
14
**4. Does ChatGPT Plus include API access?**
@@ -24,10 +24,30 @@ Refer to the [Choosing your LLMs](../setup/installation.md#installing-and-using-
24
> Some LLM providers offer free usage tiers, for example Groq, Mistral, SambaNova, or CometAPI.
25
26
**7. How can I make Agent Zero retain memory between sessions?**
27
-Use **Settings → Backup & Restore** and avoid mapping the entire `/a0` directory. See [How to update Agent Zero](../setup/installation.md#how-to-update-agent-zero).
27
+Use **Settings -> Backup & Restore** and avoid mapping the entire `/a0` directory. See [How to update Agent Zero](../setup/installation.md#how-to-update-agent-zero).
28
29
**8. My browser tool fails or says Playwright is missing. What now?**
30
-The built-in browser is provided by the `_browser` plugin and the direct `browser` tool. **Docker:** full Playwright Chromium is shipped preinstalled under `/a0/tmp/playwright`. **Local development:** if the binary is missing, `ensure_playwright_binary()` in `plugins/_browser/helpers/playwright.py` runs `playwright install chromium` into `tmp/playwright` on first browser use (you may see UI notifications). To install ahead of time, run `PLAYWRIGHT_BROWSERS_PATH=tmp/playwright playwright install chromium` after `pip install -r requirements.txt`. If you prefer an external browser stack, use MCP alternatives such as Browser OS, Chrome DevTools, or Playwright MCP. See [MCP Setup](mcp-setup.md).
30
+
31
+In normal Docker installs, the Browser already includes what it needs.
32
+
33
+If you are running a local development checkout, Agent Zero can install the
34
+browser the first time it is needed. To install it ahead of time, run this from
35
+the project root after installing Python requirements:
36
+
37
+```bash
38
+PLAYWRIGHT_BROWSERS_PATH=tmp/playwright playwright install chromium
39
+```
40
+
41
+If **Bring Your Own Browser** mode fails:
42
+
43
+- keep A0 CLI connected to the chat;
44
+- run `/browser status` in A0 CLI;
45
+- check that Browser settings still say **Bring Your Own Browser**;
46
+- check **Page content access** if page text or screenshots are blocked.
47
+
48
+See the [Browser Guide](browser.md) for Browser settings and host-browser
49
+behavior. If you need a different external browser tool, see
50
+[MCP Setup](mcp-setup.md).
51
52
**9. My secrets disappeared after a backup restore.**
53
Secrets are stored in `/a0/usr/secrets.env` and are not always included in backup archives. Copy them manually.
@@ -36,7 +56,8 @@ Secrets are stored in `/a0/usr/secrets.env` and are not always included in backu
56
- Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community.
57
58
**11. How do I adjust API rate limits?**
39
-Use the model rate limit fields in Settings (Main Model and Utility Model sections) to set request/input/output limits. These map to the model config limits (for example `limit_requests`, `limit_input`, `limit_output`).
59
+Use the model rate limit fields in Settings, under the Main Model and Utility
60
+Model sections, to set request, input, and output limits.
61
62
**12. My `code_execution_tool` doesn't work, what's wrong?**
63
- Ensure Docker is installed and running.
@@ -44,12 +65,13 @@ Use the model rate limit fields in Settings (Main Model and Utility Model sectio
65
- Verify that the Docker image is updated.
66
67
**13. Can Agent Zero interact with external APIs or services (e.g., WhatsApp)?**
47
-Yes, by creating custom tools or using MCP servers. See [Extensions](../developer/extensions.md) and [MCP Setup](mcp-setup.md).
68
+Yes. Start with [API Integration](api-integration.md) for one-off services or
69
+[MCP Setup](mcp-setup.md) when the service already has MCP support.
70
71
## Troubleshooting
72
73
**Installation**
52
-- **Docker Issues:** If Docker containers fail to start, consult the Docker documentation and verify your Docker installation and configuration. On macOS, ensure you've granted Docker access to your project files in Docker Desktop's settings as described in the [Installation guide](../setup/installation.md#4-install-docker-docker-desktop-application). Verify that the Docker image is updated.
74
+- **Docker Issues:** If Docker containers fail to start, consult the Docker documentation and verify your Docker installation and configuration. On macOS, ensure you've granted Docker access to your project files in Docker Desktop's settings as described in the [Installation guide](../setup/installation.md#step-1-install-docker-desktop). Verify that the Docker image is updated.
75
- **Web UI not reachable:** Ensure at least one host port is mapped to container port `80`. If you used `0:80`, check the assigned port in Docker Desktop.
76
77
**Usage**
docs/guides/usage.md
+270
-973
@@ -1,1128 +1,425 @@
1
# Usage Guide
2
-This guide explores usage and configuration scenarios for Agent Zero. You can consider this as a reference post-installation guide.
2
4
-
3
+This guide is the practical tour of Agent Zero after installation. It explains
4
+what you can do in the Web UI, what to try first, and where to go when you want
5
+the deeper source-linked explanation.
6
6
-## Basic Operations
7
-Agent Zero provides several basic operations through its interface:
8
-
9
-### Restart Framework
10
-The Restart button allows you to quickly restart the Agent Zero container without using the terminal:
11
-
12
-
13
-
14
-* Click the "Restart" button in the sidebar dropdown
15
-* A blue inline confirmation will appear indicating "Confirm"
16
-* Once confirmed, the framework will reinitialize and restart the container
17
-
18
-> [!TIP]
19
-> Use the Restart function when you want to:
20
-> - Reset the framework if you encounter unexpected behavior
21
-> - See changes applied to the framework code
22
-
23
-### Action Buttons
24
-Located beneath the chat input box, Agent Zero provides a set of action buttons for enhanced control and visibility:
25
-
26
-
27
-#### Chat Flow Control
28
-* **Pause/Resume Agent:** Toggle button to pause and resume chat flow
29
- - Click to pause ongoing agent operations
30
- - Changes to "Resume Agent" when paused
31
- - Click again to resume chat flow and command execution
32
-
33
-#### Knowledge and File Management
34
-* **Import Knowledge:** Import external files into the agent's knowledge base
35
- - Supports `.txt`, `.pdf`, `.csv`, `.html`, `.json`, and `.md` formats
36
- - Files are stored in `/a0/knowledge/custom/main`
37
- - Success message confirms successful import
38
- - See [knowledge](../developer/architecture.md#knowledge) for more details
7
+For architecture, backend flow, Web UI internals, plugin lifecycle, and API
8
+details, use [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
9
40
-### File Browser: Manage files in the Agent Zero environment
10
+
11
42
-
43
-
44
- - Upload new files and folders
45
- - Download files (click filename) or folders (as zip archives)
46
- - Rename and Delete files and folders
47
- - Navigate directories using the "Up" button
48
- - Edit files in the File Editor
49
- - See [File Browser](#file-browser) section for detailed features
12
+## Basic Operations
13
51
-#### Debugging and Monitoring
52
-* **Context:** View the complete context window sent to the LLM
53
- - Includes system prompts
54
- - Shows current conversation context
55
- - Displays active instructions and parameters
14
+Agent Zero is built around a chat, a working Linux environment, and a Web UI that
15
+lets you watch and steer the work.
16
57
-
17
+Common places to start:
18
59
-### History:
60
-Access the chat history in JSON format
61
- - View the conversation as processed by the LLM
62
- - Useful for debugging and understanding agent behavior
63
- - Files are stored under `/a0/usr/chats/` inside the container
19
+- **New Chat:** start a clean conversation.
20
+- **Projects:** give a chat its own workspace, files, memory, secrets, and instructions.
21
+- **Memory:** review what Agent Zero has learned or imported.
22
+- **Tasks:** create scheduled, planned, or manual automations.
23
+- **Files:** open the Agent Zero file browser.
24
+- **Settings:** configure models, credentials, preferences, plugins, and backup.
25
+- **Browser:** open the live Browser surface when you want to watch browsing or annotate a page.
26
+- **Desktop:** open the live Linux desktop when you want GUI apps, a terminal window, or LibreOffice Cowork.
27
65
-
28
+
29
67
-* **Nudge:** Restart the agent's last process
68
- - Useful when agents become unresponsive
69
- - Retries the last operation
70
- - Helps recover from stuck states
30
+The chat input also has action buttons for attachments, pausing, nudging, compacting,
31
+and opening helpful views such as context or history.
32
72
-
33
+
34
74
-> [!TIP]
75
-> Use the Context and History buttons to understand how the agent interprets your instructions and debug any unexpected behavior.
35
+Use **Restart** from the sidebar when you need the framework to reload after
36
+settings or code changes.
37
77
-### Plugins and Plugin Hub
78
-Open the **Plugins** dialog from the sidebar quick actions by clicking the plugin icon.
38
+## Plugins And Plugin Hub
39
80
-
40
+Plugins add integrations, tools, panels, and automation helpers.
41
82
-From this view you can manage installed plugins, review plugin details, open plugin settings, and change activation state.
42
+Open **Plugins** from the dashboard or sidebar to see what is installed.
43
84
-#### Open the Plugin Hub
85
-There are two ways to reach the Plugin Hub from the Plugins dialog:
44
+
45
87
-1. Click the **Browse** tab after **Custom** and **Builtin** to switch the current dialog into the Plugin Hub view.
88
-2. Click the **Install** button in the top-right toolbar to open the installer modal, which starts on its own **Browse** tab.
46
+Use the **Browse** tab or **Install** button to open the Plugin Hub.
47
48
49
92
-The Plugin Hub lets you search community plugins, filter by tags, sort the listing, and open a plugin card for more context before installing.
93
-
94
-
95
-
96
-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.
97
-
98
-### File Attachments
99
-Agent Zero supports direct file attachments in the chat interface for seamless file operations:
100
-
101
-#### Attaching Files
102
-* Click the attachment icon (📎) on the left side of the chat input box
103
-* Select one or multiple files to attach
104
-* Preview attached files before sending:
105
- - File names are displayed with their types (HTML, PDF, JPG, etc.)
106
- - Images show thumbnails when available
107
- - Files are listed in the chat input area waiting to be sent
108
-
109
-
110
-
111
-#### Working with Attached Files
112
-* Files can be referenced directly in your messages
113
-* Agent Zero can:
114
- - Process attached files
115
- - Move files to specific directories
116
- - Perform operations on multiple files simultaneously
117
- - Confirm successful file operations with detailed responses
118
-
119
-
120
-
121
-> [!TIP]
122
-> 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.
123
-
124
-## Tool Usage
125
-Agent Zero's power comes from its ability to use [tools](../developer/architecture.md#tools). Here's how to leverage them effectively:
126
-
127
-- **Understand Tools:** Agent Zero includes default tools like knowledge (powered by SearXNG), code execution, and communication. Understand the capabilities of these tools and how to invoke them.
128
-
129
-### Browser Tool Status & MCP Alternatives
130
-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](../setup/dev-setup.md) to pre-install).
131
-
132
-If you need a different browser stack or want external browser tooling, MCP-based browser tools are still a strong option:
133
-
134
-- **Browser OS MCP**
135
-- **Chrome DevTools MCP**
136
-- **Playwright MCP**
137
-
138
-See [MCP Setup](mcp-setup.md) for configuration guidance and recommended servers.
139
-
140
-### Agent-to-Agent (A2A) Communication
141
-
142
-Agent Zero instances can communicate with each other using the A2A protocol. This enables:
143
-
144
-- **Task delegation** to specialized agent instances
145
-- **Distributed workflows** across multiple agents
146
-- **Project-specific collaboration** with isolated contexts
147
-
148
-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.
50
+Before installing a plugin, read its description, README, permissions, and source
51
+link. Treat plugins like any other code you run in your workspace: install the
52
+ones you trust and remove what you do not use.
53
150
-See [A2A Setup](a2a-setup.md) for detailed configuration and use cases.
54
+When you want to make your own first plugin, start with something small and
55
+visible. The [Create a Small Plugin](create-plugin.md) guide walks through a
56
+local Web UI plugin that adds an unread dot to the chat list and then reviews it
57
+with `a0-review-plugin`.
58
152
-## Example of Tools Usage: Web Search and Code Execution
153
-Let's say you want Agent Zero to perform some financial analysis tasks. Here's a possible prompt:
59
+## Skills, Agent Profiles, And Model Presets
60
155
-> 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_engine` and `document_query` tools to find the price and the news, and the `code_execution_tool` to perform the rest of the job.
61
+The small controls around the chat input let you shape the current conversation
62
+without opening the full Settings screen.
63
157
-Agent Zero might then:
64
+### Skills
65
159
-1. Use the `search_engine` and `document_query` tools to query a reliable source for the Bitcoin price and for the news about cryptocurrency as prompted.
160
-2. Extract the price from the search results and save the news, extracting their dates and possible impact on the price.
161
-3. Use the `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.
162
-4. Save the final chart on disk inside the container and provide a link to it with the `response_tool`.
66
+Skills are focused instructions Agent Zero can load when it needs them. You can
67
+also pin a skill manually for the current chat.
68
164
-> [!NOTE]
165
-> The first run of `code_execution_tool` may take a while as it downloads and builds the Agent Zero Docker image. Subsequent runs will be faster.
69
+Click the **+** button in the chat input, then click **Skills**.
70
167
-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.
71
+
72
169
-## Multi-Agent Cooperation
170
-One of Agent Zero's unique features is multi-agent cooperation.
73
+Use the selector to add or remove active skills.
74
172
-* **Creating Sub-Agents:** Agents can create sub-agents to delegate sub-tasks. This helps manage complexity and distribute workload.
173
-* **Communication:** Agents can communicate with each other, sharing information and coordinating actions. The system prompt and message history play a key role in guiding this communication.
174
-* **Hierarchy:** Agent Zero uses a [hierarchical structure](../developer/architecture.md#agent-hierarchy-and-communication), with superior agents delegating tasks to subordinates. This allows for structured problem-solving and efficient resource allocation.
75
+
76
176
-
77
+Active skills are added to the **Extras** part of the system prompt, so keep the
78
+list short and intentional. See the [Skills guide](skills.md).
79
178
-## Projects
179
-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.
180
-
181
-### What Projects Provide
182
-
183
-Each project includes:
184
-
185
-- **Isolated workspace** under `/a0/usr/projects/<project_name>/`
186
-- **Custom instructions** automatically injected into system prompts
187
-- **Dedicated or shared memory** to control context isolation
188
-- **Project-scoped secrets and variables** for secure credential management
189
-- **Git repository integration** for cloning and working with codebases
190
-- **File structure injection** for automatic codebase awareness
191
-- **Custom agent configurations** including subagent settings
192
-- **Knowledge base integration** with project-specific documents
80
+### Agent Profiles
81
194
-### Creating Projects
82
+Agent Profiles change the role, tone, and prompt instructions for the selected
83
+chat.
84
196
-There are two ways to access project management:
85
+
86
198
-1. **Dashboard Access**: Click **Projects** from the Dashboard to open the Projects modal
199
-2. **Quick Access**: Click the project dropdown in the top-right corner (shows "No project" when none is active)
87
+Use the profile menu near the chat input to switch the current chat. Use
88
+**Settings -> Agent Config** when you want to change the default for new chats.
89
201
-
90
+The same menu includes **Create new Agent Profile**. It places a ready-to-send
91
+message in the input so Agent Zero can guide you through creating a new profile.
92
203
-#### Empty Projects
93
+
94
205
-Create a new empty project workspace:
206
-1. Click **"Create project"**
207
-2. Enter a **title** (human-readable name)
208
-3. Choose a **color tag** for visual identification
209
-4. Click **"Create and continue"**
95
+See the [Agent Profiles guide](agent-profiles.md).
96
211
-#### Git-Based Projects
97
+### Model Presets
98
213
-Clone a repository directly into your project workspace:
214
-1. Enter a **Git repository URL** (public or private)
215
-2. Optionally provide an authentication token for private repos
216
-3. Agent Zero clones the repository and sets up the project structure
99
+Model Presets are named shortcuts for model choices. Use them for setups like
100
+`Best`, `Balanced`, `Fast Cheap`, or a model name you can spot quickly.
101
218
-
102
+
103
220
-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.
104
+Click **Edit presets** when you want to add or rename presets.
105
222
-
106
+
107
224
-> [!NOTE]
225
-> If the cloned repository already contains a `.a0proj/` configuration folder, Agent Zero merges the existing configuration with your specified preferences.
108
+See the [Model Presets guide](model-presets.md).
109
227
-### Project Configuration
110
+## File Attachments
111
229
-
112
+Attach files when the agent should read, summarize, transform, or organize them.
113
231
-#### Description and Instructions
114
+
115
233
-- **Description**: Helps you and the agent understand the project's purpose and context
234
-- **Instructions**: Critical field that gets injected into the agent's system prompt when the project is active
116
+You can attach one file or several files, then describe what should happen:
117
236
-> [!IMPORTANT]
237
-> Well-written instructions are key to effective project-specific behavior. Be specific about:
238
-> - The agent's role and expertise for this project
239
-> - Directory paths and file locations
240
-> - Expected workflows and procedures
241
-> - Quality standards and validation rules
242
-> - Output formats and requirements
243
-
244
-**Example instructions:**
245
-```markdown
246
-## Your Role
247
-You are an expert Financial Data Analyst working with Excel automation.
248
-
249
-## Operational Context
250
-- Work directory: `/usr/projects/excel-finance/`
251
-- Input data: `/usr/projects/excel-finance/data/incoming/`
252
-- Reports output: `/usr/projects/excel-finance/reports/`
253
-
254
-## Core Responsibilities
255
-1. Scan for new Excel/CSV files in incoming directory
256
-2. Validate and clean data (check for missing values, duplicates)
257
-3. Consolidate data from multiple sources
258
-4. Generate executive reports with visualizations
259
-5. Flag compliance issues and anomalies
118
+```text
119
+Read these PDFs and create a short comparison table.
120
```
121
262
-#### Memory Isolation
263
-
264
-Choose how project memory is managed:
265
-
266
-- **Own memory** (recommended): Project has isolated memory under `vector_db/projects/<project_name>/`
267
- - Prevents context bleed between projects
268
- - Ideal for client work, sensitive projects, or distinct domains
269
-
270
-- **Global memory**: Project shares the default memory pool
271
- - Useful when projects need shared knowledge
272
- - Better for closely related projects
273
-
274
-#### Variables and Secrets
275
-
276
-Projects support scoped configuration:
277
-
278
-- **Variables** (non-sensitive): Stored in `.a0proj/variables.env`
279
- ```bash
280
- API_BASE_URL=https://api.example.com
281
- OUTPUT_FORMAT=json
282
- ```
283
-
284
-- **Secrets** (sensitive): Stored in `.a0proj/secrets.env`
285
- ```bash
286
- API_KEY=sk-abc123xyz...
287
- DATABASE_PASSWORD=super_secret_pwd
288
- ```
289
-
290
-Reference these in your prompts: "Use my `API_KEY` to authenticate with the service"
291
-
292
-> [!WARNING]
293
-> Secrets may not be included in backup archives. Keep a separate manual copy of critical credentials.
294
-
295
-#### File Structure Injection
296
-
297
-Projects can automatically inject their directory structure into the agent's context. This is configurable per project:
298
-
299
-- **Max depth**: Directory levels to scan (default: 5)
300
-- **Max files/folders**: Limits for context size
301
-- **Gitignore patterns**: Filter out build artifacts, dependencies, etc.
302
-
303
-The default ignores: `.a0proj/`, `venv/`, `__pycache__/`, `node_modules/`, `.git/`
304
-
305
-This feature helps the agent understand your codebase structure without manual explanation.
306
-
307
-### Activating Projects
308
-
309
-To use a project, activate it for your current chat:
310
-
311
-1. Click the project dropdown in the top-right corner
312
-2. Select the desired project from the list
313
-3. The project activates immediately
314
-
315
-
316
-
317
-Each chat can have its own active project. Multiple chats can use different projects simultaneously.
318
-
319
-Once activated, the agent:
320
-- Follows project-specific instructions
321
-- Uses project memory (if isolated)
322
-- Has access to project secrets and variables
323
-- Sees the project file structure (if enabled)
324
-- Works in the project directory by default
325
-
326
-
327
-
328
-### Project Directory Structure
329
-
330
-```
331
-/a0/usr/projects/<project_name>/
332
-├── .a0proj/ # Project metadata (managed by A0)
333
-│ ├── project.json # Main configuration
334
-│ ├── variables.env # Non-sensitive config
335
-│ ├── secrets.env # Sensitive credentials
336
-│ ├── agents.json # Subagent settings
337
-│ ├── instructions/ # Additional instruction files
338
-│ └── knowledge/ # Project knowledge base
339
-├── src/ # Your actual project files
340
-├── data/ # Data files
341
-└── ... # Other project content
122
+```text
123
+Move these files into a clean folder structure and explain what changed.
124
```
125
344
-### Common Use Cases
345
-
346
-**Multi-Client Work**: Create separate projects for each client with isolated memory and credentials
126
+Attached files are visible in the chat input before you send the message, so you
127
+can remove mistakes before Agent Zero starts working.
128
348
-**Multi-Language Development**: Organize by tech stack (Python ML, Node.js webapp, Go microservices)
349
-
350
-**Domain-Specific Tasks**: Separate projects for finance, marketing, HR with domain-specific instructions
351
-
352
-**Automated Workflows**: Combine with [Tasks & Scheduling](#tasks--scheduling) for recurring project-based work
353
-
354
-### Best Practices
355
-
356
-- Use **own memory** by default for client work to prevent context bleed
357
-- Write **specific instructions** - mention paths, formats, and quality standards
358
-- Choose **distinct colors** for easy visual identification when switching
359
-- Keep **secrets separate** from version control - backup manually
360
-- **Adjust file structure limits** based on project size
361
-- **Clean memory periodically** via Memory Dashboard for optimal performance
362
-
363
-> [!TIP]
364
-> For a comprehensive guide to creating and managing projects, including detailed examples and troubleshooting, see the [Projects Tutorial](projects.md).
365
-
366
-See also:
367
-- [Projects in Extensions](../developer/extensions.md#projects) - Technical structure details
368
-- [Tasks & Scheduling](#tasks--scheduling) - Automate project-based work
369
-- [Memory Management](#memory-management) - Maintain project knowledge
370
-
371
-## Tasks & Scheduling
372
-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.
373
-
374
-### What Are Tasks?
375
-
376
-Tasks are autonomous work units that Agent Zero executes in dedicated or shared chat contexts. Each task includes:
377
-
378
-- **Prompt and Instructions**: What the agent should do
379
-- **Execution Schedule**: When to run (cron schedule, specific times, or manual)
380
-- **Project Association**: Optional project context with its instructions and secrets
381
-- **Dedicated Context**: Each task can maintain its own conversation history
382
-- **State Management**: Tracks idle, running, disabled, or error states
383
-- **Result Tracking**: Stores last run time and execution results
384
-
385
-### Task Types
386
-
387
-Agent Zero supports three types of tasks:
388
-
389
-#### Scheduled Tasks
390
-Run on a recurring schedule using cron syntax:
391
-- **Daily reports**: `0 9 * * *` (every day at 9 AM)
392
-- **Hourly checks**: `0 * * * *` (every hour)
393
-- **Weekly summaries**: `0 9 * * 1` (Mondays at 9 AM)
394
-- **Custom intervals**: Full cron flexibility for complex schedules
395
-
396
-#### Planned Tasks
397
-Execute at specific, predetermined times:
398
-- **One-time future execution**: Single date/time
399
-- **Multi-step campaigns**: List of specific execution times
400
-- **Event-driven sequences**: Coordinate with external schedules
401
-
402
-#### Ad-hoc Tasks
403
-Manual execution for on-demand work:
404
-- **Quick batch jobs**: Run when needed
405
-- **Testing workflows**: Verify task configuration
406
-- **One-off operations**: Tasks that don't need scheduling
407
-
408
-### Creating Tasks
409
-
410
-#### From the UI
411
-
412
-Access the Task Scheduler from the sidebar:
413
-
414
-1. Click **Settings** → **Tasks Scheduler**
415
-2. Click **"New Task"** to create a task
416
-
417
-
418
-
419
-The scheduler shows:
420
-- **Task List**: All configured tasks with their state
421
-- **Filter Controls**: By type (scheduled, planned, ad-hoc) and state
422
-- **Quick Actions**: Run, pause, edit, or delete tasks
423
-- **Task Details**: Name, project association, last run, next run time
129
+## Tool Usage
130
425
-#### From Chat
131
+You usually do not need to name tools. Say what you want done and Agent Zero will
132
+choose whether it needs the browser, code execution, files, knowledge, plugins,
133
+or another available capability.
134
427
-Ask the agent to create tasks programmatically:
135
+Good prompts are specific about the desired result:
136
429
-```
430
-Create a scheduled task that checks my email inbox every morning at 8 AM
431
-and summarizes new messages from the last 24 hours.
137
+```text
138
+Research three deployment options for this app. Cite sources and finish with a recommendation.
139
```
140
434
-The agent uses the `scheduler` tool to create tasks based on your natural language description.
435
-
436
-### Task Configuration
437
-
438
-
439
-
440
-When editing a task, you configure:
441
-
442
-#### Task Name
443
-A unique identifier for the task:
444
-- Use descriptive names: "Morning report for incoming Gmail"
445
-- Keep it concise but clear
446
-- Helps identify tasks in logs and notifications
447
-
448
-#### Task Type
449
-Choose the execution model:
450
-- **Scheduled**: Recurring cron-based execution
451
-- **Planned**: Specific date/time list
452
-- **Ad-hoc**: Manual execution only
453
-
454
-> [!NOTE]
455
-> Task type cannot be changed after creation. To switch types, create a new task.
141
+```text
142
+Open the attached CSV, find the main trend, and create a chart I can edit later.
143
+```
144
457
-#### Project Association
458
-Optionally link the task to a project:
145
+```text
146
+Inspect this repository and propose the safest first improvement before changing files.
147
+```
148
460
-**Benefits of project-scoped tasks:**
461
-- Task inherits project instructions automatically
462
-- Access to project-specific secrets and variables
463
-- Uses project's isolated memory (if configured)
464
-- Runs in project's working directory
465
-- Perfect for client-specific or domain-specific automation
149
+When you do want internals, use
150
+[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
151
467
-**Example:**
468
-- Project: "Financial Reports"
469
-- Task: "Daily Portfolio Summary"
470
-- Result: Task automatically uses financial analysis instructions, API keys, and memory from the project
152
+### Browser Tool And Surface
153
472
-#### State Management
473
-Control task execution:
154
+The Browser has two parts:
155
475
-- **Idle**: Ready to run when scheduled (green indicator)
476
-- **Running**: Currently executing (blue indicator)
477
-- **Disabled**: Won't execute even if scheduled (gray indicator)
478
-- **Error**: Last execution failed (red indicator)
156
+- the `browser` tool, which the agent can call directly;
157
+- the visible Browser surface in the Canvas, where you can watch and annotate pages.
158
480
-Toggle state to temporarily disable tasks without deleting them.
159
+
160
482
-#### Execution Plan
483
-For **Scheduled Tasks**, configure the cron schedule:
161
+Ask naturally:
162
485
-**Common patterns:**
163
+```text
164
+Use the Browser tool to compare these pages and take screenshots of the important parts.
165
```
487
-# Every day at 9 AM
488
-0 9 * * *
166
490
-# Every hour
491
-0 * * * *
167
+```text
168
+Open my local app in the Browser. I will annotate the page, then you can fix the issues.
169
+```
170
493
-# Every Monday at 10 AM
494
-0 10 * * 1
171
+For screenshots, history, annotations, Docker browser mode, host-browser mode
172
+through A0 CLI, privacy controls, and Chrome extensions, see the
173
+[Browser Guide](browser.md).
174
496
-# Every 15 minutes
497
-*/15 * * * *
175
+External browser MCP tools are still useful for specialized setups. See
176
+[MCP Setup](mcp-setup.md).
177
499
-# First day of month at midnight
500
-0 0 1 * *
501
-```
178
+### Desktop Surface
179
503
-**Timezone aware**: Tasks respect your configured timezone setting
180
+The Desktop surface opens Agent Zero's own Linux desktop in the Canvas.
181
+Use it when you want the agent to work visually with GUI apps, open a terminal,
182
+or cowork with you in LibreOffice.
183
505
-For **Planned Tasks**, add specific execution times:
506
-- Click "Add Execution Time"
507
-- Pick date and time
508
-- Tasks execute in order
509
-- Completed executions move to "Done" list
184
+
185
511
-### Task Execution
186
+The **New** menu can create Markdown, Writer, Spreadsheet, and Presentation
187
+files. Writer, Calc, and Impress run inside the Desktop, so you can edit by hand
188
+while Agent Zero creates, updates, saves, and verifies the same files.
189
513
-#### Dedicated vs. Shared Context
190
+For the screenshot walkthrough and prompt examples, see the
191
+[Desktop Guide](desktop.md).
192
515
-**Dedicated Context** (recommended):
516
-- Each task has its own isolated chat history
517
-- Prevents context pollution between tasks
518
-- Better for independent, recurring workflows
519
-- Default for UI-created tasks
193
+### Agent-To-Agent Communication
194
521
-**Shared Context**:
522
-- Task shares a chat context (useful for agent-created tasks)
523
-- Can build on previous task executions
524
-- Useful for sequential, related operations
195
+Agent Zero instances can communicate through A2A when you want multiple
196
+instances to collaborate.
197
526
-#### Execution Flow
198
+Use A2A when you have a clear reason to split work across Agent Zero instances,
199
+such as a specialist server, a remote machine, or a project-specific agent. See
200
+[A2A Setup](a2a-setup.md).
201
528
-When a task runs:
202
+### Multi-Agent Cooperation
203
530
-1. **Context Preparation**
531
- - Creates or loads the task's chat context
532
- - Activates associated project (if configured)
533
- - Loads project instructions, secrets, and memory
204
+Inside a single Agent Zero instance, the main agent can create subordinate agents
205
+to investigate focused parts of a larger job.
206
535
-2. **Prompt Injection**
536
- - Injects system prompt (if specified)
537
- - Adds task-specific instructions
538
- - Includes any file attachments
207
+
208
540
-3. **Agent Execution**
541
- - Agent receives the prompt as a user message
542
- - Executes using available tools
543
- - Can use project-scoped resources
209
+This is useful for research, code review, comparison work, and tasks where one
210
+agent should gather information while another keeps the main plan moving.
211
545
-4. **Result Handling**
546
- - Stores execution result and timestamp
547
- - Updates task state (idle or error)
548
- - Sends notifications (if configured)
549
- - For Planned Tasks: moves execution to "Done" list
212
+## Projects
213
551
-#### Monitoring Execution
214
+Projects tell Agent Zero what world it is working in. Use one when a chat needs
215
+its own files, instructions, memory, secrets, or model settings.
216
553
-**Real-time monitoring:**
554
-- Running tasks show "Running" state in scheduler
555
-- View task's chat context to see agent progress
556
-- Stop tasks mid-execution if needed
217
+
218
558
-**Execution history:**
559
-- **Last Run**: Timestamp of most recent execution
560
-- **Next Run**: Scheduled time for next execution
561
-- **Last Result**: Output or error from last run
219
+The simple flow:
220
563
-### Common Use Cases
221
+1. Open **Projects** from the dashboard.
222
+2. Click **Create project**.
223
+3. Give it a clear title.
224
+4. Add a short description.
225
+5. Write practical instructions.
226
+6. Save it.
227
+7. Open a chat and choose the project from the top-right project picker.
228
565
-#### Daily Reports
566
-```
567
-Task: "Morning Inbox Summary"
568
-Type: Scheduled (0 9 * * *)
569
-Project: "Email Automation"
570
-Prompt: "Check my Gmail inbox for new messages from the last 24 hours.
571
-Summarize important emails by category and highlight any urgent items."
572
-```
229
+
230
574
-#### Recurring Monitoring
575
-```
576
-Task: "Server Health Check"
577
-Type: Scheduled (*/30 * * * *)
578
-Project: "DevOps Monitoring"
579
-Prompt: "Check server status, CPU usage, and disk space.
580
-Alert me if any metric exceeds threshold."
581
-```
231
+Good project instructions tell Agent Zero what should be different in that
232
+workspace:
233
583
-#### Batch Processing
584
-```
585
-Task: "Weekly Data Export"
586
-Type: Scheduled (0 2 * * 0)
587
-Project: "Analytics"
588
-Prompt: "Export last week's analytics data to CSV.
589
-Upload to cloud storage and send summary report."
590
-```
591
-
592
-#### Campaign Automation
593
-```
594
-Task: "Product Launch Sequence"
595
-Type: Planned
596
-Executions:
597
- - 2026-03-01 09:00 - Send launch announcement
598
- - 2026-03-03 14:00 - Send feature highlights
599
- - 2026-03-07 10:00 - Send customer testimonials
600
-Project: "Marketing Campaigns"
234
+```markdown
235
+When this project is active:
236
+- Explain steps in plain language before technical detail.
237
+- Prefer screenshots, checklists, and concrete examples.
238
+- Keep generated files inside this project unless I ask otherwise.
239
+- Ask before using credentials, private data, or external accounts.
240
```
241
603
-### Integration with Projects
604
-
605
-Tasks and Projects are designed to work together:
242
+Use projects for client work, code repositories, research topics, recurring
243
+reports, and any workflow where context matters.
244
607
-**Pattern: Project-Scoped Automation**
245
+See the [Projects guide](projects.md) for the full screenshot walkthrough.
246
609
-1. Create a project with domain-specific instructions
610
- ```
611
- Project: "Customer Support"
612
- Instructions: "You are a customer support analyst.
613
- Monitor ticket queue, categorize by urgency, draft responses."
614
- ```
247
+## Tasks And Scheduling
248
616
-2. Create a recurring task for that project
617
- ```
618
- Task: "Ticket Queue Monitor"
619
- Schedule: Every 2 hours
620
- Project: "Customer Support"
621
- Prompt: "Check new tickets and categorize them."
622
- ```
249
+Tasks let Agent Zero run work later, repeatedly, or on demand.
250
624
-3. Task automatically uses:
625
- - Project instructions (support analyst role)
626
- - Project secrets (support system API keys)
627
- - Project memory (previous ticket patterns)
628
- - Project file structure (template responses)
251
+Use tasks for:
252
630
-**Benefits:**
631
-- Consistent behavior across task executions
632
-- No need to repeat instructions in each task
633
-- Easy to update behavior (edit project instructions once)
634
-- Clean separation of concerns (project = context, task = action)
253
+- morning or weekly reports;
254
+- monitoring a source and summarizing changes;
255
+- recurring cleanup or export jobs;
256
+- project-specific checks;
257
+- manual batch jobs you want to run again.
258
636
-### Notifications
259
+Open **Tasks** from the dashboard or sidebar.
260
638
-Tasks can trigger notifications on completion or failure:
261
+
262
640
-- Configure notification preferences in Settings
641
-- Set up notification channels (email, Slack, webhook)
642
-- Tasks automatically send status updates
643
-- Critical for unattended automation
263
+When creating a task, focus on four things:
264
645
-See [Notifications](../developer/notifications.md) for configuration details.
265
+- **Name:** what you will recognize later.
266
+- **Type:** scheduled, planned, or ad-hoc.
267
+- **Project:** optional, but recommended when the task needs specific context or secrets.
268
+- **Prompt:** the actual work Agent Zero should perform.
269
270
+
271
648
-### Multi-Source Aggregation
649
-Tasks can pull from multiple sources:
272
+Example:
273
651
-```
652
-"Aggregate data from:
653
-1. Sales CRM API
654
-2. Marketing analytics dashboard
655
-3. Customer support tickets
656
-Generate unified weekly report."
274
+```text
275
+Name: Weekly docs review
276
+Type: Scheduled
277
+Project: Documentation
278
+Prompt: Check the docs project for stale screenshots, broken links, and confusing sections. Summarize what needs attention.
279
```
280
659
-> [!TIP]
660
-> 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.
281
+Project-scoped tasks inherit project instructions, variables, secrets, files, and
282
+memory. That means you can improve task behavior later by improving the project
283
+instead of repeating every rule in every task.
284
662
-### Next Steps
285
+## Secrets And Variables
286
664
-Explore related features:
287
+Use **Secrets** for sensitive values such as API keys, tokens, passwords, and
288
+credentials.
289
666
-- [Projects](#projects) - Create isolated contexts for tasks
667
-- [Notifications](../developer/notifications.md) - Understand A0's notification system
668
-- [Memory Management](#memory-management) - Understand task memory isolation
669
-- [Secrets & Variables](#secrets--variables) - Secure credentials for tasks
290
+Use **Variables** for non-sensitive settings such as regions, URLs, usernames,
291
+formats, or feature flags.
292
671
-## Secrets & Variables
672
-Use the Settings → **Secrets** and **Variables** fields to store credentials and non-sensitive configuration values.
293
+Refer to them by name in chat:
294
674
-- **Secrets** (sensitive): API keys, passwords, tokens
675
-- **Variables** (non-sensitive): URLs, usernames, flags
676
-
677
-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.
678
-
679
-> [!IMPORTANT]
680
-> Secrets are stored in `/a0/usr/secrets.env`.
295
+```text
296
+Use the project GITHUB_TOKEN to check repository status.
297
+```
298
682
-> [!NOTE]
683
-> Project-scoped secrets and variables (when using Projects) live under `/a0/usr/projects/<project_name>/.a0proj/` (`secrets.env`, `variables.env`).
299
+Do not paste credentials into chat messages or public files. Keep your own copy
300
+of important secrets because backups may not include every secret.
301
685
-## Remote Access via Tunneling
302
+## Remote Access Via Tunneling
303
687
-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.
304
+Tunnels let you reach your local Agent Zero instance from another device or
305
+share it temporarily.
306
689
-### How Tunneling Works
307
+Before creating a tunnel:
308
691
-Agent Zero uses the [Flaredantic](https://pypi.org/project/flaredantic/) library to create secure tunnels. These tunnels:
309
+- set UI authentication;
310
+- understand that anyone with the tunnel URL can try to open your instance;
311
+- stop the tunnel when you no longer need it.
312
693
-- Are secure (HTTPS)
694
-- Don't require any configuration
695
-- Generate unique URLs for each session
696
-- Can be regenerated on demand
313
+Open **Settings -> External Services -> Flare Tunnel** to create or stop a tunnel.
314
698
-### Creating a Tunnel
315
+## Voice Interface
316
700
-1. Open **Settings** in the sidebar
701
-2. Navigate to the **External Services** tab
702
-3. Click on **Flare Tunnel** in the navigation menu
703
-4. Click the **Create Tunnel** button to generate a new tunnel
704
-5. Once created, the tunnel URL will be displayed and can be copied to share with others
705
-6. The tunnel URL remains active until you stop the tunnel or close Agent Zero
317
+Agent Zero supports text-to-speech and speech-to-text.
318
707
-### Security Considerations
319
+Use speech when you want to listen while doing something else, dictate a prompt,
320
+or make the interface more accessible.
321
709
-When sharing your Agent Zero instance via a tunnel:
322
+
323
711
-- Anyone with the URL can access your Agent Zero instance
712
-- No additional authentication is added beyond what your Agent Zero instance already has
713
-- **Always set up authentication before creating a tunnel** (see below)
714
-- The tunnel exposes only your Agent Zero instance, not your entire system
324
+Speech-to-text settings live in Settings and include model size, language code,
325
+silence threshold, and recording behavior.
326
716
-> [!IMPORTANT]
717
-> When attempting to create a tunnel without authentication configured, Agent Zero will display a security warning.
327
+
328
719
-### Adding Authentication for Tunnels
329
+## Mathematical Expressions
330
721
-To secure your tunneled Agent Zero instance, configure authentication in Settings:
331
+Agent Zero can render mathematical notation with KaTeX.
332
723
-1. Open **Settings** in the Agent Zero UI
724
-2. Navigate to the **Authentication** section
725
-3. Enter your desired username in the **UI Login** field
726
-4. Enter a strong password in the **UI Password** field
727
-5. Click **Save** to apply the changes
333
+
334
729
-Alternatively, you can set environment variables:
335
+Ask for the format you want:
336
731
-```bash
732
-AUTH_LOGIN=your_username
733
-AUTH_PASSWORD=your_password
337
+```text
338
+Solve this step by step and show the final equations in KaTeX.
339
```
340
736
-This will require users to enter these credentials when accessing your tunneled Agent Zero instance.
737
-
738
-### Troubleshooting Tunnels
341
+## File Browser
342
740
-If you encounter issues with the tunnel feature:
343
+The File Browser lets you inspect and manage files inside the Agent Zero
344
+environment.
345
742
-1. Check your internet connection
743
-2. Try regenerating the tunnel URL
744
-3. Restart Agent Zero
745
-4. Check the console logs for any error messages
346
+
347
747
-> [!TIP]
748
-> Combine tunneling with authentication for secure remote access to your Agent Zero instance from any device, including mobile phones and tablets.
348
+Use it to:
349
750
-## Voice Interface
751
-Agent Zero provides both Text-to-Speech (TTS) and Speech-to-Text (STT) capabilities for natural voice interaction:
350
+- upload files;
351
+- download generated work;
352
+- create folders;
353
+- rename or delete files;
354
+- open editable text files;
355
+- inspect the project or `/a0/usr` workspace.
356
753
-### Text-to-Speech
754
-Enable voice responses from agents:
755
-* Toggle the "Speech" switch in the Preferences section of the sidebar
756
-* Agents will use your system's built-in voice synthesizer to speak their messages
757
-* Click the "Stop Speech" button above the input area to immediately stop any ongoing speech
758
-* You can also click the speech button when hovering over messages to speak individual messages or their parts
357
+For file-based work, prefer `/a0/usr` or a project workspace. Avoid storing
358
+important work only in temporary directories.
359
760
-
360
+## Memory Management
361
762
-- The interface allows users to stop speech at any time if a response is too lengthy or if they wish to intervene during the conversation.
362
+Memory is where Agent Zero keeps useful remembered information from conversations
363
+and imported knowledge. It is powerful, but it is not magic. Long-term AI memory
364
+still needs curation; this is not fully solved even by the largest AI labs and
365
+companies.
366
764
-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.
367
+Open **Memory** when you want to search, review, edit, copy, or remove stored
368
+entries.
369
370
+
371
767
-> [!TIP]
768
-> The Text-to-Speech feature is great for:
769
-> - Multitasking while receiving agent responses
770
-> - Accessibility purposes
771
-> - Creating a more interactive experience
372
+The controls let you choose a memory directory, filter by area, set a result
373
+limit, search, adjust match threshold, and clear filtered results.
374
773
-### Speech-to-Text
774
-Send voice messages to agents using OpenAI's Whisper model (does not require OpenAI API key!):
375
+
376
776
-1. Click the microphone button in the input area to start recording
777
-2. The button color indicates the current status:
778
- - Grey: Inactive
779
- - Red: Listening
780
- - Green: Recording
781
- - Teal: Waiting
782
- - Cyan (pulsing): Processing
377
+Use memory deliberately:
378
784
-Users can adjust settings such as silence threshold and message duration before sending to optimize their interaction experience.
379
+- keep durable facts and useful patterns;
380
+- remove old test data;
381
+- edit memories that became inaccurate;
382
+- use project memory for project-specific context;
383
+- create a backup before large cleanup.
384
786
-Configure STT settings in the Settings page:
787
-* **Model Size:** Choose between Base (74M, English) or other models
788
- - Note: Only Large and Turbo models support multiple languages
789
-* **Language Code:** Set your preferred language (e.g., 'en', 'fr', 'it', 'cz')
790
-* **Silence Detection:**
791
- - Threshold: Adjust sensitivity (lower values are more sensitive)
792
- - Duration: Set how long silence should last before ending recording
793
- - Timeout: Set maximum waiting time before closing the microphone
385
+If Agent Zero does something unexpected, repeats a wrong behavior, or seems to
386
+remember the wrong thing, Memory is one of the first places to look. A stale or
387
+incorrect memory can poison the processing instead of helping it.
388
795
-
389
+Click a memory row to inspect its full content and metadata. From the detail
390
+view you can copy, edit, or delete the entry.
391
797
-> [!IMPORTANT]
798
-> All STT and TTS functionalities operate locally within the Docker container,
799
-> ensuring that no data is transmitted to external servers or OpenAI APIs. This
800
-> enhances user privacy while maintaining functionality.
392
+
393
802
-## Mathematical Expressions
803
-* **Complex Mathematics:** Supports full KaTeX syntax for:
804
- - Fractions, exponents, and roots
805
- - Matrices and arrays
806
- - Greek letters and mathematical symbols
807
- - Integrals, summations, and limits
808
- - Mathematical alignments and equations
394
+For a practical cleanup checklist, see the [Memory Guide](memory.md).
395
810
-
811
-
812
-> [!TIP]
813
-> When asking the agent to solve mathematical problems, it will automatically respond using KaTeX formatting for clear and professional-looking mathematical expressions.
814
-
815
-### File Browser
816
-Agent Zero provides a powerful file browser interface for managing your workspace:
817
-
818
-#### Interface Overview
819
-- **Navigation Bar**: Shows current directory path with "Up" button for parent directory
820
-- **File List**: Displays files and directories with key information:
821
- - Name (sortable)
822
- - Size in bytes
823
- - Last modified timestamp
824
-- **Action Icons**: Each file/directory has:
825
- - menu for edit and rename actions
826
- - Download button
827
- - Delete button (with confirmation)
828
-
829
-
830
-
831
-#### Features
832
-- **Directory Navigation**:
833
- - Click directories to enter them
834
- - Use "Up" button to move to parent directory
835
- - Current path always visible for context
836
-
837
-> [!NOTE]
838
-> 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).
839
->
840
-- **File Operations**:
841
- - Create new files and directories
842
- - Delete existing files and directories
843
- - Download files to your local system
844
- - Upload files from your local system
845
-- **File Information**:
846
- - Visual indicators for file types (folders, code files, documents)
847
- - Size information in human-readable format
848
- - Last modification timestamps
849
-- **Bulk Operations**:
850
- - Upload multiple files simultaneously
851
-- **File and Directory Editing**:
852
- - Limited to 100MB files
853
- - Binary files cannot be edited
854
-
855
-> [!TIP]
856
-> 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.
396
+## Backup And Restore
397
858
-## Memory Management
859
-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.
398
+Backups protect your chats, projects, knowledge, memory, settings, skills, and
399
+workspace files.
400
861
-### Accessing the Memory Dashboard
862
-Open the Memory Dashboard from the sidebar to manage your agent's memory:
401
+Create a backup before:
402
864
-1. Click the **Memory** button in the sidebar
865
-2. The dashboard displays all memory entries with their metadata and preview
866
-3. Memory entries are organized by directory (e.g., "default") and area (e.g., "All Areas", "main")
403
+- major updates;
404
+- plugin experiments;
405
+- bulk memory cleanup;
406
+- moving to a new machine;
407
+- deleting or reorganizing important project files.
408
868
-
409
+Open **Settings -> Backup & Restore** to create or restore a backup.
410
870
-### Dashboard Features
411
+Secrets are sensitive and may not always be included in backup archives. Keep a
412
+separate secure copy of credentials you depend on.
413
872
-#### Filtering and Organization
873
-The dashboard provides several ways to organize and filter memory entries:
414
+## Next Steps
415
875
-* **Memory Directory**: Select which memory directory to view (default or project-specific)
876
-* **Area Filter**: Filter memories by area to focus on specific contexts
877
-* **Limit Control**: Adjust the number of results displayed (default: 1000)
878
-* **Statistics Bar**: View counts at a glance:
879
- - Total: All memory entries in the directory
880
- - Filtered: Entries matching current filters
881
- - Knowledge: Entries from knowledge sources
882
- - Conversation: Entries from chat interactions
883
-
884
-#### Search Functionality
885
-Find specific memories using the powerful search feature:
886
-
887
-* **Search Bar**: Enter keywords to search memory content
888
-* **Threshold Slider**: Adjust search sensitivity (0.00 - 1.00)
889
- - Lower values return more results with looser matching
890
- - Higher values return fewer, more precise matches
891
- - Default threshold: 0.60
892
-* **Real-time Search**: Results update as you type
893
-
894
-> [!TIP]
895
-> 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.
896
-
897
-#### Memory Entry Information
898
-Each memory entry displays key information:
899
-
900
-* **Tags**: Visual indicators showing the memory type (MAIN, Knowledge, etc.)
901
-* **Timestamp**: When the memory was created (format: MM/DD HH:MM)
902
-* **Preview**: First few lines of the memory content
903
-* **Action Icons**: Quick access to view details, edit, or delete
904
-
905
-### Viewing and Editing Memories
906
-Click any memory entry to open the detailed view with full editing capabilities:
907
-
908
-
909
-
910
-#### Memory Details View
911
-The details panel provides comprehensive information about each memory:
912
-
913
-* **Memory Content**: Full text of the stored memory
914
- - Syntax highlighting for structured content
915
- - Editable text area for modifications
916
-* **Metadata Panel**: Complete memory information
917
- - Unique ID
918
- - Area classification
919
- - Source type (e.g., "Knowledge")
920
- - Timestamp (creation date and time)
921
- - Source file (if applicable)
922
-
923
-#### Editing Memories
924
-Modify memory entries directly from the details view:
925
-
926
-1. Click on any memory entry to open the details panel
927
-2. Edit the memory content in the text area
928
-3. Click the **Save** button (checkmark icon) to apply changes
929
-4. Click the **Cancel** button (X icon) to discard changes
930
-
931
-> [!NOTE]
932
-> Edited memories are immediately updated in the vector database and will affect how the agent recalls and uses this information in future interactions.
933
-
934
-#### Deleting Memories
935
-Remove unwanted or outdated memory entries:
936
-
937
-1. Open the memory details view
938
-2. Click the **Delete** button (trash icon) in the action bar
939
-3. Confirm the deletion when prompted
940
-4. The memory is permanently removed from the vector database
941
-
942
-Alternatively, delete directly from the main dashboard:
943
-* Click the delete icon on any memory entry in the list
944
-* Confirm the deletion
945
-
946
-> [!WARNING]
947
-> Deleted memories cannot be recovered. Use caution when removing entries, especially those from knowledge sources or important conversations.
948
-
949
-#### Clearing Memories
950
-For bulk cleanup operations:
951
-
952
-* Click the **Clear** button in the dashboard header to remove all filtered memories
953
-* This is useful when you need to reset a specific area or start fresh with a memory directory
954
-* Always review your filters before clearing to avoid unintended deletions
955
-
956
-### Memory Types and Sources
957
-
958
-#### Knowledge Memories
959
-Memories derived from uploaded knowledge files:
960
-* Marked with "Knowledge" tag
961
-* Include source file information
962
-* Created when importing documents via Import Knowledge button
963
-* Stored persistently unless manually deleted
964
-
965
-#### Conversation Memories
966
-Memories from chat interactions:
967
-* Marked with conversation indicators
968
-* Created automatically as the agent learns from interactions
969
-* Include contextual information about when and why they were created
970
-* Help the agent maintain continuity across sessions
971
-
972
-### Best Practices with Memory
973
-
974
-#### Regular Maintenance
975
-* **Review Periodically**: Check your memory entries monthly to remove outdated information
976
-* **Organize by Area**: Use areas to categorize memories by project or topic
977
-* **Clean Up Test Data**: Remove experimental or test memories that aren't needed
978
-* **Monitor Growth**: Keep an eye on total memory count to maintain performance
979
-
980
-#### Search Optimization
981
-* **Use Specific Keywords**: More specific terms yield better results
982
-* **Adjust Threshold**: Fine-tune the threshold based on your needs
983
-* **Filter First**: Use area and directory filters before searching for better results
984
-* **Iterate Searches**: Try different search terms if initial results aren't helpful
985
-
986
-#### Content Quality
987
-* **Keep Relevant**: Remove memories that are no longer useful or accurate
988
-* **Update Information**: Edit memories when information becomes outdated
989
-* **Add Context**: When editing, ensure memories remain clear and useful
990
-* **Avoid Duplicates**: Remove redundant memories that store the same information
991
-
992
-#### Project Integration
993
-When using Projects (see [Projects](#projects)):
994
-* Each project maintains its own memory directory
995
-* Memories are isolated between projects to prevent context bleed
996
-* Use project-specific memory directories for focused work
997
-* Clear project memories when archiving completed projects
998
-
999
-> [!TIP]
1000
-> 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.
1001
-
1002
-> [!IMPORTANT]
1003
-> Memory management directly affects agent behavior and recall. Regularly maintaining your memory database ensures optimal agent performance and relevant context retention.
1004
-
1005
-## Backup & Restore
1006
-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.
1007
-
1008
-### Creating Backups
1009
-Access the backup functionality through the Settings interface:
1010
-
1011
-1. Click the **Settings** button in the sidebar
1012
-2. Navigate to the **Backup & Restore** tab
1013
-3. Click **Create Backup** to start the backup process
1014
-
1015
-#### What Gets Backed Up
1016
-By default, Agent Zero backs up your most important data:
1017
-
1018
-* **Knowledge Base**: Your custom knowledge files and documents
1019
-* **Memory System**: Agent memories and learned information
1020
-* **Chat History**: All your conversations and interactions
1021
-* **Configuration Files**: Settings, API keys, and system preferences
1022
-* **Custom Skills**: Any skills you've added or modified (SKILL.md format)
1023
-* **Uploaded Files**: Documents and files you've worked with
1024
-
1025
-> [!NOTE]
1026
-> Chat history is stored at `/a0/usr/chats/` inside the container.
1027
-
1028
-#### Customizing Backup Content
1029
-Before creating a backup, you can customize what to include:
1030
-
1031
-* **Edit Patterns**: Use the built-in editor to specify exactly which files and folders to backup
1032
-* **Include Hidden Files**: Choose whether to include system and configuration files
1033
-* **Preview Files**: See exactly what will be included before creating the backup
1034
-* **Organized View**: Files are grouped by directory for easy review
1035
-
1036
-> [!TIP]
1037
-> The backup system uses pattern matching, so you can include or exclude specific file types. For example, you can backup all `.py` files but exclude temporary `.tmp` files.
1038
-
1039
-#### Creating Your Backup
1040
-1. Review the file preview to ensure you're backing up what you need
1041
-2. Give your backup a descriptive name
1042
-3. Click **Create Backup** to generate the archive
1043
-4. The backup file will download automatically as a ZIP archive
1044
-
1045
-> [!NOTE]
1046
-> Backup creation may take a few minutes depending on the amount of data. You'll see progress updates during the process.
1047
-> Secrets stored in `/a0/usr/secrets.env` are not always included in backup archives. Keep a manual copy if you rely on secrets.
1048
-
1049
-### Restoring from Backup
1050
-The restore process allows you to recover your Agent Zero setup from a previous backup:
1051
-
1052
-#### Starting a Restore
1053
-1. Navigate to **Settings** → **Backup & Restore** tab
1054
-2. Click **Restore from Backup**
1055
-3. Upload your backup ZIP file
1056
-
1057
-#### Reviewing Before Restore
1058
-After uploading, you can review and customize the restore:
1059
-
1060
-* **Inspect Metadata**: View information about when and where the backup was created
1061
-* **Edit Restore Patterns**: Choose exactly which files to restore
1062
-* **Preview Changes**: See which files will be restored, overwritten, or skipped
1063
-* **Cross-System Compatibility**: Paths are automatically adjusted when restoring on different systems
1064
-
1065
-#### Restore Options
1066
-Configure how the restore should handle existing files:
1067
-
1068
-* **Overwrite**: Replace existing files with backup versions
1069
-* **Skip**: Keep existing files, only restore missing ones
1070
-* **Backup Existing**: Create backup copies of existing files before overwriting
1071
-
1072
-#### Clean Before Restore
1073
-Optionally clean up existing files before restoring:
1074
-
1075
-* **Smart Cleanup**: Remove files that match backup patterns before restoring
1076
-* **Preview Cleanup**: See which files would be deleted before confirming
1077
-* **Safe Operation**: Only affects files that match your specified patterns
1078
-
1079
-### Best Practices
1080
-
1081
-#### When to Create Backups
1082
-* **Before Major Changes**: Always backup before significant modifications
1083
-* **Regular Schedule**: Create weekly or monthly backups of your work
1084
-* **Before System Updates**: Backup before updating Agent Zero or system components
1085
-* **Project Milestones**: Save backups when completing important work
1086
-
1087
-#### Backup Management
1088
-* **Descriptive Names**: Use clear names like "project-completion-2024-01"
1089
-* **External Storage**: Keep backup files in a safe location outside Agent Zero
1090
-* **Multiple Versions**: Maintain several backup versions for different time periods
1091
-* **Test Restores**: Occasionally test restoring backups to ensure they work
1092
-
1093
-#### Security Considerations
1094
-* **Secrets**: Backups do **not** reliably include `/a0/usr/secrets.env`. Copy it manually when migrating.
1095
-* **Secure Storage**: Store backup files securely and don't share them
1096
-* **Clean Systems**: When restoring on new systems, verify all configurations
1097
-
1098
-### Common Use Cases
1099
-
1100
-#### System Migration
1101
-Moving Agent Zero to a new server or computer:
1102
-1. Create a complete backup on the original system
1103
-2. Install Agent Zero on the new system
1104
-3. Restore the backup to migrate all your data and settings
1105
-
1106
-#### Project Archival
1107
-Preserving completed projects:
1108
-1. Create project-specific backup patterns
1109
-2. Include only relevant files and conversations
1110
-3. Store the backup as a project archive
1111
-
1112
-#### Development Snapshots
1113
-Saving work-in-progress states:
1114
-1. Create frequent backups during development
1115
-2. Use descriptive names to track progress
1116
-3. Restore previous versions if something goes wrong
1117
-
1118
-#### Team Collaboration
1119
-Sharing Agent Zero configurations:
1120
-1. Create backups with shared configurations and tools
1121
-2. Team members can restore to get consistent setups
1122
-3. Include documentation and project files
1123
-
1124
-> [!IMPORTANT]
1125
-> 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.
1126
-
1127
-> [!TIP]
1128
-> 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.
416
+- [Quick Start](../quickstart.md)
417
+- [Projects guide](projects.md)
418
+- [Browser guide](browser.md)
419
+- [A0 CLI Connector](a0-cli-connector.md)
420
+- [Skills guide](skills.md)
421
+- [Agent Profiles guide](agent-profiles.md)
422
+- [Model Presets guide](model-presets.md)
423
+- [MCP Setup](mcp-setup.md)
424
+- [Troubleshooting](troubleshooting.md)
425
+- [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero)
docs/quickstart.md
+72
-28
@@ -1,5 +1,7 @@
1
# Quick Start
2
-This guide provides a quick introduction to using Agent Zero. We'll cover the recommended install path and running your first Skill.
2
+
3
+This guide gets you from install to a first useful chat. Keep it simple: start
4
+Agent Zero, add a model or API key, open the Web UI, and give it a concrete job.
5
6
## Installation (recommended)
7
@@ -18,7 +20,7 @@ irm https://ps.agent-zero.ai | iex
20
Follow the CLI prompts for port and authentication, complete onboarding, then open the Web UI URL from the terminal.
21
22
> [!TIP]
21
-> To update later, open **Settings UI → Update tab → Open Self Update** (see [How to Update](setup/installation.md#how-to-update-agent-zero)). Backups are automatically managed internally.
23
+> To update later, open **Settings UI -> Update tab -> Open Self Update** (see [How to Update](setup/installation.md#how-to-update-agent-zero)). Backups are automatically managed internally.
24
25
> [!NOTE]
26
> For manual Docker Desktop setup, volume mapping, and platform-specific detail, see the [Installation Guide](setup/installation.md#manual-installation-advanced).
@@ -27,16 +29,16 @@ Follow the CLI prompts for port and authentication, complete onboarding, then op
29
30
If you want Agent Zero to work on the actual files on your computer, this is the important part.
31
30
-Agent Zero stays in Docker for safety. The A0 CLI installs and runs on your host machine. That host-side CLI is what lets Agent Zero work on the real files on your real computer.
32
+Agent Zero stays in Docker for safety. The A0 CLI installs and runs on your host machine. It is not another CLI agent; it is the connector that lets your running Agent Zero instance work on the real files on your real computer.
33
34
**macOS / Linux:**
35
```bash
34
-curl -LsSf https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.sh | sh
36
+curl -LsSf https://cli.agent-zero.ai/install.sh | sh
37
```
38
39
**Windows (PowerShell):**
40
```powershell
39
-irm https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.ps1 | iex
41
+irm https://cli.agent-zero.ai/install.ps1 | iex
42
```
43
44
Run those on the host machine, not inside the Agent Zero container.
@@ -47,13 +49,15 @@ Then launch:
49
a0
50
```
51
50
-Once `a0` connects, open or create a chat there. That is the path that lets Agent Zero stay in Docker while still working on real local files on your machine.
52
+Once `a0` connects, open or create a chat there. The reasoning still belongs to Agent Zero; the CLI is the host bridge that lets it work on real local files on your machine.
53
52
-For the full setup flow, manual fallback install paths, remote-host tips, and a copy-ready brief for another agent, see the [A0 CLI Connector guide](guides/a0-cli-connector.md).
54
+For the full setup flow, host picker screenshots, command palette guidance, Browser mode commands, manual fallback install paths, remote-host tips, and a copy-ready brief for another agent, see the [A0 CLI Connector guide](guides/a0-cli-connector.md).
55
56
### Open the Web UI and configure your API key
57
56
-Open your browser and navigate to `http://localhost:<PORT>`. The Web UI will show the onboarding banner. Click Start Onboarding to set your AI models and API key.
58
+Open your browser and navigate to `http://localhost:<PORT>`. The Web UI will
59
+show the onboarding banner. Click **Start Onboarding** to set your models and
60
+API key.
61
62
63
@@ -68,18 +72,25 @@ Click **Add your API key** to open Settings and configure:
72
73
### Start your first chat
74
71
-Once configured, you'll see the Agent Zero dashboard with access to:
75
+Once configured, you will see the Agent Zero dashboard.
76
+
77
+
78
+
79
+Click **New Chat** and start with a specific request.
80
73
-- **Projects** - organize your work into projects
74
-- **Memory** - open the memory dashboard
75
-- **Scheduler** - create and manage planned tasks
76
-- **Files** - open the File Browser
77
-- **Settings** - configure models and preferences
78
-- **System Stats** - monitor resource usage
81
+Good first prompts:
82
+
83
+```text
84
+Create a short plan for organizing my project notes.
85
+```
86
80
-Click **New Chat** to start creating with Agent Zero!
87
+```text
88
+Use the Browser to research three options for this tool and summarize the tradeoffs.
89
+```
90
82
-
91
+```text
92
+Help me create a project for this repository and write good instructions for it.
93
+```
94
95
> [!TIP]
96
> The Web UI provides a comprehensive chat actions dropdown with options for managing conversations, including creating new chats, resetting, saving/loading, and many more advanced features. Chats are saved in JSON format in the `/usr/chats` directory.
@@ -89,11 +100,14 @@ Click **New Chat** to start creating with Agent Zero!
100
---
101
102
## Example Interaction
92
-Let's ask Agent Zero to use one of the built-in skills. Here's how:
103
94
-1. Type "Activate your brainstorming skill" in the chat input field and press Enter or click the send button.
95
-2. Agent Zero will process your request. You'll see its thoughts and tool calls in the UI.
96
-3. The agent will acknowledge the skill activation and ask you for a follow-up on the brainstorming request.
104
+Try a small request first so you can see how Agent Zero thinks, uses tools, and
105
+reports progress.
106
+
107
+1. Type a concrete request in the chat input and press Enter.
108
+2. Watch the streamed response and any tool calls.
109
+3. Redirect the agent if it starts moving in the wrong direction.
110
+4. Ask for the final result in the format you want.
111
112
Here's an example of what you might see in the Web UI at step 3:
113
@@ -102,17 +116,47 @@ Here's an example of what you might see in the Web UI at step 3:
116
## Next Steps
117
Now that you've run a simple task, you can experiment with more complex requests. Try asking Agent Zero to:
118
105
-* Connect to your email
106
-* Execute shell commands
107
-* Develop skills
108
-* Explore web development tasks
109
-* Develop A0 itself
119
+- Create a project for a focused workspace.
120
+- Use the built-in Browser to research, screenshot, or annotate a page.
121
+- Open the Desktop when you want Linux GUI apps or LibreOffice Cowork.
122
+- Review Memory when Agent Zero seems to keep the wrong assumption.
123
+- Connect A0 CLI when Agent Zero should work on host-machine files.
124
+- Use **+ -> Skills** when you want to pin or remove a skill in the current chat.
125
+- Switch Agent Profiles from the menu near the chat input when you want a different working style.
126
+- Use the first model dropdown when you want to choose or edit Model Presets.
127
+- Attach files and ask for a summary, edit, or conversion.
128
+- Create a scheduled task for recurring work.
129
+- Explore plugins when you need installed integrations or custom UI features.
130
+
131
+### [Open A0 Browser Guide](guides/browser.md)
132
+
133
+Explains the built-in Browser, live Browser Canvas, screenshots, annotations, host-browser mode through A0 CLI, and Chrome extensions.
134
+
135
+### [Open A0 Desktop Guide](guides/desktop.md)
136
+
137
+Shows the right-side Canvas Linux desktop, the New menu for Markdown/Writer/Spreadsheet/Presentation files, and LibreOffice Cowork.
138
+
139
+### [Open A0 Memory Guide](guides/memory.md)
140
+
141
+Explains how to search, edit, delete, export, and curate memories before stale context starts steering the agent.
142
+
143
+### [Open A0 Skills Guide](guides/skills.md)
144
+
145
+Shows the chat input **+** menu, the Skills selector, and how active skills are added to prompt extras.
146
+
147
+### [Open A0 Agent Profiles Guide](guides/agent-profiles.md)
148
+
149
+Shows how to switch profiles in a chat and start the guided profile-creation flow.
150
+
151
+### [Open A0 Model Presets Guide](guides/model-presets.md)
152
+
153
+Explains presets as simple named shortcuts for model setups.
154
155
### [Open A0 Usage Guide](guides/usage.md)
156
113
-Provides more in-depth information on tools, projects, tasks, and backup/restore.
157
+Provides more in-depth information on chat controls, tools, projects, tasks, and backup/restore.
158
115
-## 🎓 Video Tutorials
159
+## Video Tutorials
160
- [MCP Server Setup](https://youtu.be/pM5f4Vz3_IQ)
161
- [Projects & Workspaces](https://youtu.be/RrTDp_v9V1c)
162
- [Memory Management](https://youtu.be/sizjAq2-d9s)
docs/res/usage/a0-cli/a0-cli-browser-host-mode.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-browser-host-mode.png differ
docs/res/usage/a0-cli/a0-cli-browser-privacy.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-browser-privacy.png differ
docs/res/usage/a0-cli/a0-cli-browser-status.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-browser-status.png differ
docs/res/usage/a0-cli/a0-cli-command-browser.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-command-browser.png differ
docs/res/usage/a0-cli/a0-cli-command-palette.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-command-palette.png differ
docs/res/usage/a0-cli/a0-cli-host-picker.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-host-picker.png differ
docs/res/usage/a0-cli/a0-cli-start.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-start.png differ
docs/res/usage/browser/browser-annotation-comment.png
Binary files /dev/null and b/docs/res/usage/browser/browser-annotation-comment.png differ
docs/res/usage/browser/browser-canvas-example.png
Binary files /dev/null and b/docs/res/usage/browser/browser-canvas-example.png differ
docs/res/usage/browser/browser-canvas-wide.png
Binary files /dev/null and b/docs/res/usage/browser/browser-canvas-wide.png differ
docs/res/usage/browser/browser-plugin-settings.png
Binary files /dev/null and b/docs/res/usage/browser/browser-plugin-settings.png differ
docs/res/usage/browser/browser-tool-history-expanded.png
Binary files /dev/null and b/docs/res/usage/browser/browser-tool-history-expanded.png differ
docs/res/usage/browser/browser-toolbar-settings.png
Binary files /dev/null and b/docs/res/usage/browser/browser-toolbar-settings.png differ
docs/res/usage/browser/host-browser-remote-debugging-allow.png
Binary files /dev/null and b/docs/res/usage/browser/host-browser-remote-debugging-allow.png differ
docs/res/usage/browser/host-browser-remote-debugging-setting.png
Binary files /dev/null and b/docs/res/usage/browser/host-browser-remote-debugging-setting.png differ
docs/res/usage/webui/agent-profile-create-prompt.png
Binary files /dev/null and b/docs/res/usage/webui/agent-profile-create-prompt.png differ
docs/res/usage/webui/agent-profile-selector.png
Binary files /dev/null and b/docs/res/usage/webui/agent-profile-selector.png differ
docs/res/usage/webui/chat-more-actions-skills.png
Binary files /dev/null and b/docs/res/usage/webui/chat-more-actions-skills.png differ
docs/res/usage/webui/dashboard.png
Binary files /dev/null and b/docs/res/usage/webui/dashboard.png differ
docs/res/usage/webui/desktop-canvas.png
Binary files /dev/null and b/docs/res/usage/webui/desktop-canvas.png differ
docs/res/usage/webui/desktop-new-menu.png
Binary files /dev/null and b/docs/res/usage/webui/desktop-new-menu.png differ
docs/res/usage/webui/desktop-writer.png
Binary files /dev/null and b/docs/res/usage/webui/desktop-writer.png differ
docs/res/usage/webui/memory-dashboard-controls.png
Binary files /dev/null and b/docs/res/usage/webui/memory-dashboard-controls.png differ
docs/res/usage/webui/model-preset-selector.png
Binary files /dev/null and b/docs/res/usage/webui/model-preset-selector.png differ
docs/res/usage/webui/model-presets-add.png
Binary files /dev/null and b/docs/res/usage/webui/model-presets-add.png differ
docs/res/usage/webui/model-presets-editor.png
Binary files /dev/null and b/docs/res/usage/webui/model-presets-editor.png differ
docs/res/usage/webui/project-active-chat.png
Binary files /dev/null and b/docs/res/usage/webui/project-active-chat.png differ
docs/res/usage/webui/project-create-filled.png
Binary files /dev/null and b/docs/res/usage/webui/project-create-filled.png differ
docs/res/usage/webui/project-instructions-filled.png
Binary files /dev/null and b/docs/res/usage/webui/project-instructions-filled.png differ
docs/res/usage/webui/project-picker.png
Binary files /dev/null and b/docs/res/usage/webui/project-picker.png differ
docs/res/usage/webui/projects-empty.png
Binary files /dev/null and b/docs/res/usage/webui/projects-empty.png differ
docs/res/usage/webui/projects-list-created.png
Binary files /dev/null and b/docs/res/usage/webui/projects-list-created.png differ
docs/res/usage/webui/skills-selector-checked.png
Binary files /dev/null and b/docs/res/usage/webui/skills-selector-checked.png differ
docs/res/usage/webui/skills-selector.png
Binary files /dev/null and b/docs/res/usage/webui/skills-selector.png differ
docs/res/usage/webui/unread-dot-chat-list.png
Binary files /dev/null and b/docs/res/usage/webui/unread-dot-chat-list.png differ
docs/setup/dev-setup.md
+36
-23
@@ -2,7 +2,7 @@
2
This guide will show you how to setup a local development environment for Agent Zero in a VS Code compatible IDE, including proper debugger.
3
4
5
-[](https://www.youtube.com/watch?v=KE39P4qBjDk)
5
+[](https://www.youtube.com/watch?v=KE39P4qBjDk)
6
7
8
@@ -43,7 +43,7 @@ This guide will show you how to setup a local development environment for Agent
43
1. Open your IDE and open the project folder using `File > Open Folder` and select your folder, in my case `~/Desktop/agent-zero`.
44
2. You will probably be prompted to trust the directory, confirm that.
45
3. You should now have the project open in your IDE
46
-
46
+
47
48
# Step 3: Prepare your IDE:
49
1. Notice the prompt in lower right corner of the screenshot above to install recommended extensions, this comes from the `.vscode/extensions.json` file. It contains Python language support, debugger and error helper, install them by confirming the popup or manually in Extensions tab of your IDE. These are the extensions mentioned:
@@ -54,22 +54,35 @@ ms-python.python
54
```
55
56
Now when you select one of the python files in the project, you should see proper Python syntax highlighting and error detection. It should immediately show some errors, because we did not yet install dependencies.
57
-
57
+
58
59
-2. Prepare the python environment to run Agent Zero in. (⚠️ This step assumes you have some Python runtime installed.) By clicking the python version in lower right corner (3.13.1 in my example), you should get a list of available environments. You can click the `+ Create Virtual Environment` button. You might be prompted to select the environment manager if you have multiple installed. I have venv and Conda, I will select Conda here. I'm also prompted for desired python version, I will select 3.12, that is known to work well.
60
-
61
-
59
+2. Prepare the python environment to run Agent Zero in. This step assumes you have some Python runtime installed. By clicking the python version in lower right corner (3.13.1 in my example), you should get a list of available environments. You can click the `+ Create Virtual Environment` button. You might be prompted to select the environment manager if you have multiple installed. I have venv and Conda, I will select Conda here. I'm also prompted for desired python version, I will select 3.12, that is known to work well.
60
+
61
+
62
63
- Your new environment should be automatically activated. If not, select it in the lower right corner. You might need to open a new terminal in VS Code to reflect the changes with `Terminal > New Terminal` or clicking the `+` button in the terminal tab. Your terminal prompt should now start with your environment name/path, in my case `(/Users/frdel/Desktop/agent-zero/.conda)` This shows the environment is active in the terminal.
64
65
-
65
+
66
+
67
+3. Install dependencies. Run these commands from the project root:
68
67
-3. Install dependencies. Run these two commands in the terminal:
69
```bash
70
pip install -r requirements.txt
70
-PLAYWRIGHT_BROWSERS_PATH=tmp/playwright playwright install chromium
71
+PLAYWRIGHT_BROWSERS_PATH=./tmp/playwright playwright install chromium
72
```
72
-The first command installs Python dependencies. The second installs full Playwright Chromium into `tmp/playwright` ahead of time (same path in Docker: `/a0/tmp/playwright`). If you skip the second command, **local development** still downloads Chromium on first browser use through `ensure_playwright_binary()` in `plugins/_browser/helpers/playwright.py`. Pre-installing avoids that wait. **Docker** images ship Chromium preinstalled; runtime install is for local dev when the binary is missing.
73
+
74
+The first command installs Python dependencies.
75
+
76
+The second command installs full Playwright Chromium into `./tmp/playwright`,
77
+relative to the project root. Docker images use the absolute path
78
+`/a0/tmp/playwright` and ship Chromium preinstalled.
79
+
80
+If you skip the second command, local development can still download Chromium on
81
+first Browser use through `ensure_playwright_binary()` in
82
+`plugins/_browser/helpers/playwright.py`. Pre-installing avoids that wait.
83
+
84
+See the [Browser Guide](../guides/browser.md) for the Browser surface,
85
+screenshots, annotations, and host-browser mode.
86
Errors in the code editor caused by missing packages should now be gone. If not, try reloading the window.
87
88
@@ -79,31 +92,31 @@ It will not be able to do code execution and few other features requiring the Do
92
93
1. The project is pre-configured for debugging. Go to Debugging tab, select "run_ui.py" and click the green play button (or press F5 by default). The configuration can be found at `.vscode/launch.json`.
94
82
-
95
+
96
97
The framework will run at the default port 5000. If you open `http://localhost:5000` in your browser and see `ERR_EMPTY_RESPONSE`, don't panic, you may need to select another port like I did for some reason. If you need to change the default port, you can add `"--port=5555"` to the args in the `.vscode/launch.json` file or you can create a `.env` file in the root directory and set the `WEB_UI_PORT` variable to the desired port.
98
99
You can also set the bind host via `"--host=0.0.0.0"` (or `WEB_UI_HOST=0.0.0.0`).
100
101
It may take a while the first time. You should see output like the screenshot below. The RFC error is ok for now as we did not yet connect our local development to another instance in docker.
89
-
102
+
103
104
105
After inserting my API key in settings, my Agent Zero instance works. I can send a simple message and get a response.
93
-⚠️ Some tools like code execution will not work yet as they need to be connected to a Dockerized instance.
106
+Some tools like code execution will not work yet because they need to be connected to a Dockerized instance.
107
95
-
108
+
109
110
111
## Debugging
112
- You can try out the debugger already by placing a breakpoint somewhere in the python code.
113
- Let's open `python/api/message.py` for example and place a breakpoint at the beginning of the `communicate` function by clicking on the left of the row number. A red dot should appear showing a breakpoint is set.
114
102
-
115
+
116
117
- Now when I send a message in the UI, the debugger will pause the execution at the breakpoint and allow me to inspect all the runtime variables and run the code step by step, even modify the variables or jump to another locations in the code. No more print statements needed!
118
106
-
119
+
120
121
122
## Step 5: Run another instance of Agent Zero in Docker
@@ -114,8 +127,8 @@ After inserting my API key in settings, my Agent Zero instance works. I can send
127
If you want, you can also map the `/a0` folder to our local project folder as well, this way we can update our local instance and the docker instance at the same time.
128
This is how it looks in my example: port `80` is mapped to `8880` on the host and `22` to `8822`, `/a0` folder mapped to `/Users/frdel/Desktop/agent-zero`:
129
117
-
118
-
130
+
131
+
132
133
134
## Step 6: Configure SSH and RFC connection
@@ -129,10 +142,10 @@ This is how it looks in my example: port `80` is mapped to `8880` on the host an
142
5. Click save and test by asking your agent to do something in the terminal, like "Get current OS version". It should be able to communicate with the dockerized instance via RFC and SSH and execute the command there, responding with something like "Kali GNU/Linux Rolling".
143
144
My Dockerized instance:
132
-
145
+
146
147
My VS Code instance:
135
-
148
+
149
150
## RFC Notes (Host IDE + Docker Execution)
151
Agent Zero runs code inside the container by default. If you are running the framework locally in your IDE but want tools (like code execution) to run in Docker, configure RFC in **Settings -> Development** and point it to a running Agent Zero container. This routes execution through SSH/RFC to the container while keeping the UI and agent loop on your host.
@@ -151,9 +164,9 @@ You're now ready to contribute to Agent Zero, create custom extensions, or modif
164
165
166
## Next steps
154
-- See [extensions](../developer/extensions.md) for instructions on how to create custom extensions.
155
-- See [websocket infrastructure](websocket-infrastructure.md) for real-time handler patterns, client APIs, and troubleshooting tips.
156
-- See [contribution](../guides/contribution.md) for instructions on how to contribute to the framework.
167
+- See [Create a Small Plugin](../guides/create-plugin.md) before building a new plugin.
168
+- Use [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero) for architecture and source-linked internals.
169
+- See [Contributing to Agent Zero](../guides/contribution.md) for contribution basics.
170
171
## Configuration via Environment Variables
172
docs/setup/installation.md
+20
-16
@@ -26,7 +26,7 @@ docker run -p 80:80 agent0ai/agent-zero
26
Once the install completes, open the URL shown in your terminal to access the Web UI. Follow the prompts in the CLI to set your port and authentication, complete onboarding, add your API key, then continue to [Step 3: Configure Agent Zero](#step-3-configure-agent-zero).
27
28
> [!TIP]
29
-> Prefer a terminal-native workflow too? Install the optional [A0 CLI Connector](../guides/a0-cli-connector.md) from GitHub, then run `a0` to connect to this Agent Zero instance from your terminal.
29
+> Need Agent Zero to reach host-machine files, shell, or a host browser? Install the optional [A0 CLI Connector](../guides/a0-cli-connector.md), then run `a0` to connect your terminal to this Agent Zero instance.
30
31
---
32
@@ -36,7 +36,7 @@ Once the install completes, open the URL shown in your terminal to access the We
36
37
Use the built-in updater in the Web UI:
38
39
-1. Open **Settings UI → Update** tab
39
+1. Open **Settings UI -> Update** tab
40
2. Open **Self Update**
41
3. Wait for the update checker to see if you have the latest version or if there's an available update.
42
@@ -46,10 +46,10 @@ For technical details of the updater, see [Self Update](../guides/self-update.md
46
47
### Updating from Pre-v0.9.8
48
49
-If you are upgrading from an older version of Agent Zero (v0.9.8 or earlier) to v1.1 or newer, the architecture has fundamentally changed. You cannot use the in-app Self Update. Instead, follow these steps to migrate your data:
49
+If you are upgrading from Agent Zero v0.9.8 or earlier to v1.1 or newer, use the migration path below. Older installs were laid out differently, so the in-app Self Update is not the right tool for that jump.
50
51
1. **Backup your existing `usr/` directory** (which contains your settings, projects, memory, and custom plugins).
52
-2. **Run the new install script** to set up the new Docker-based architecture:
52
+2. **Run the new install script** to set up the current Docker-based install:
53
- macOS / Linux: `curl -fsSL https://bash.agent-zero.ai | bash`
54
- Windows (PowerShell): `irm https://ps.agent-zero.ai | iex`
55
3. **Migrate your data:** After the new installation completes, copy the contents of your backed-up `usr/` directory into the new `/a0/usr/` directory created by the script.
@@ -62,7 +62,7 @@ If you are upgrading from an older version of Agent Zero (v0.9.8 or earlier) to
62
1. Keep the current container running
63
2. `docker pull agent0ai/agent-zero:latest`
64
3. Start a **new** container on a different host port, for example: `docker run -d -p 50081:80 --name agent-zero-new agent0ai/agent-zero`
65
-4. On the **old** instance: **Settings → Backup & Restore → Create Backup**
65
+4. On the **old** instance: **Settings -> Backup & Restore -> Create Backup**
66
5. On the **new** instance: **Restore** the backup
67
6. Verify chats and data, then remove the old container
68
@@ -135,7 +135,7 @@ Once installed, launch Docker Desktop from your Start menu or desktop shortcut.
135
136
<img src="../res/setup/image-11.png" alt="docker installed" height="100"/>
137
138
-✅ **Docker is now installed!**
138
+**Docker is now installed.**
139
140
Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
141
@@ -168,11 +168,11 @@ Open Docker Desktop from your Applications folder.
168
**1.4. Configure Docker Socket**
169
170
> [!NOTE]
171
-> **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) → Settings → Advanced, enable "Allow the default Docker socket to be used (requires password)."
171
+> **Important macOS Configuration:** In Docker Desktop's preferences (Docker menu) -> Settings -> Advanced, enable "Allow the default Docker socket to be used (requires password)."
172
173
174
175
-✅ **Docker is now installed!**
175
+**Docker is now installed.**
176
177
Continue to [Step 2: Run Agent Zero](#step-2-run-agent-zero)
178
@@ -211,7 +211,7 @@ docker login
211
212
If you installed Docker Desktop, launch it from your applications menu.
213
214
-✅ **Docker is now installed!**
214
+**Docker is now installed.**
215
216
> [!TIP]
217
> **Deploying on a VPS/Server?** For production deployments with reverse proxy, SSL, and domain configuration, see the [VPS Deployment Guide](vps-deployment.md).
@@ -308,14 +308,18 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
308
309
### Agent Configuration
310
311
-- **Agent Profile:** Select the agent profile (e.g., `agent0`, `hacker`, `researcher`). Profiles can override prompts, tools, and extensions.
311
+- **Agent Profile:** Select the default profile for new chats, such as `agent0`,
312
+ `hacker`, or `researcher`.
313
- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
314
- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
315
315
-See the [Agent Profiles guide](../guides/agent-profiles.md) for profile file locations, `agent.yaml`, prompt overrides, and profile-specific Main/Utility model configuration.
316
+See the [Agent Profiles guide](../guides/agent-profiles.md) for the chat menu,
317
+profile switching, and guided profile creation.
318
319
> [!NOTE]
318
-> Since v0.9.7, custom prompts belong in `/a0/agents/<agent_name>/prompts/` rather than a shared `/prompts` folder. See the [Extensions guide](../developer/extensions.md#prompts) for details.
320
+> Since v0.9.7, custom prompts belong inside a specific agent profile rather
321
+> than a shared `/prompts` folder. Most users should create profiles from the
322
+> chat profile menu.
323
324
> [!NOTE]
325
> The Hacker profile is included in the main image. After launch, choose the **hacker** agent profile in Settings to make it the default for new chats, or switch the selected chat from the composer profile selector. The "hacker" branch is deprecated.
@@ -371,7 +375,7 @@ Configure API keys for various service providers directly within the Web UI. Cli
375
> **OpenAI API vs Plus subscription:** A ChatGPT Plus subscription does not include API credits. You must provide a separate API key for OpenAI usage in Agent Zero.
376
377
> [!TIP]
374
-> For OpenAI-compatible providers (e.g., custom gateways or Z.AI/GLM), add the API key under **External Services → Other OpenAI-compatible API keys**, then select **OpenAI Compatible** as the provider in model settings.
378
+> For OpenAI-compatible providers (e.g., custom gateways or Z.AI/GLM), add the API key under **External Services -> Other OpenAI-compatible API keys**, then select **OpenAI Compatible** as the provider in model settings.
379
380
> [!CAUTION]
381
> **GitHub Copilot Provider:** When using the GitHub Copilot provider, after selecting the model and entering your first prompt, the OAuth login procedure will begin. You'll find the authentication code and link in the output logs. Complete the authentication process by following the provided link and entering the code, then you may continue using Agent Zero.
@@ -416,7 +420,7 @@ The Settings page is the control center for selecting the Large Language Models
420
3. Click "Save" to apply the changes.
421
422
> [!NOTE]
419
-> The built-in browser does not have a separate model slot. The main agent decides when to call the direct `browser` tool.
423
+> The built-in Browser does not have a separate default model slot. The main agent decides when to call the direct `browser` tool. Browser settings can optionally choose a Browser LLM preset for Browser-owned helper operations.
424
425
### Important Considerations
426
@@ -442,7 +446,7 @@ Use the naming format required by your selected provider:
446
#### Utility Model Guidance
447
448
- Utility models handle summarization and memory extraction.
445
-- Very small models (≈4B) usually fail at reliable context extraction.
449
+- Very small models (about 4B) usually fail at reliable context extraction.
450
- Aim for ~70B class models or strong cloud "flash/mini" models for better results.
451
452
#### Reasoning/Thinking Models
@@ -560,7 +564,7 @@ The Tunnel feature allows secure access to your Agent Zero instance from anywher
564
5. Share this URL to access Agent Zero from any device
565
566
> [!IMPORTANT]
563
-> **Security:** Always set a username and password in Settings → Authentication before creating a tunnel to secure your instance on the internet.
567
+> **Security:** Always set a username and password in Settings -> Authentication before creating a tunnel to secure your instance on the internet.
568
569
For complete details on tunnel configuration and security considerations, see the [Remote Access via Tunneling](../guides/usage.md#remote-access-via-tunneling) section in the Usage Guide.
570
docs/setup/vps-deployment.md
+3
-3
@@ -15,10 +15,10 @@
15
4. [Apache Reverse Proxy Configuration](#apache-reverse-proxy-configuration)
16
5. [SSL/TLS Configuration](#ssltls-configuration)
17
6. [Authentication Setup](#authentication-setup)
18
-7. [Domain & DNS Setup](#domain--dns-setup)
19
-8. [Verification & Testing](#verification--testing)
18
+7. [Domain & DNS Setup](#domain-dns-setup)
19
+8. [Verification & Testing](#verification-testing)
20
9. [Troubleshooting](#troubleshooting)
21
-10. [Maintenance & Updates](#maintenance--updates)
21
+10. [Maintenance & Updates](#maintenance-updates)
22
11. [Quick Reference](#quick-reference)
23
24
---
knowledge/main/about/architecture.md
+1
-1
@@ -58,7 +58,7 @@ Plugin tools can be added in `plugins/<plugin>/tools/` or `usr/plugins/<plugin>/
58
59
## Extension and Plugin System
60
61
-The plugin system (`python/helpers/plugins.py`) discovers plugins from `plugins/` and `usr/plugins/`. Each plugin has a `plugin.yaml` manifest declaring name, version, and settings. Plugins can contribute: API handlers, tools, WebUI components, extensions, and hooks. User plugins in `usr/plugins/` are never overwritten by framework updates. The agent has skills to create, manage, debug, review and contribute plugins to the Plugin Index repository (https://github.com/agent0ai/a0-plugins)
61
+The plugin system (`python/helpers/plugins.py`) discovers plugins from `plugins/` and `usr/plugins/`. Each plugin has a `plugin.yaml` manifest declaring name, version, and settings. Plugins can contribute: API handlers, tools, Web UI components, extensions, and hooks. User plugins in `usr/plugins/` are never overwritten by framework updates. The agent has skills to create, manage, debug, review and contribute plugins to the Plugin Index repository (https://github.com/agent0ai/a0-plugins)
62
63
## Frontend Architecture
64
knowledge/main/about/capabilities.md
+2
-2
@@ -76,7 +76,7 @@ An external REST API is available for programmatic task submission. Agent-to-Age
76
- **No persistent state between chats** unless explicitly memorized or saved to files.
77
- **Context window**: long conversations are summarized automatically, which can lose detail.
78
- **Memory recall is approximate**: similarity search may miss relevant memories or surface irrelevant ones.
79
-- **No GUI interaction** outside built-in browser tooling or configured computer-use integrations.
80
-- **Container boundary**: the agent cannot affect systems outside the Docker container unless network access or volume mounts are configured.
79
+- **No GUI interaction** outside built-in Browser tooling, A0 CLI host-browser mode, or configured computer-use integrations.
80
+- **Container boundary**: the agent cannot affect systems outside the Docker container unless one of these bridges is available: network access, volume mounts, A0 CLI access, or A0 CLI host-browser mode.
81
- **Model capability ceiling**: tool usage quality and reasoning depth are bounded by the underlying LLM. Small models may struggle with complex multi-step tool use.
82
- **No real-time data** beyond web search. The agent's own knowledge cutoff is the underlying model's training cutoff.
knowledge/main/about/configuration.md
+9
-1
@@ -10,7 +10,15 @@ Agent Zero uses three configurable LLM roles:
10
| `utility_llm` | Secondary model for internal framework tasks: memory summarization, query generation, history compression, memory recall filtering |
11
| `embedding_llm` | Produces vector embeddings for memory and knowledge indexing |
12
13
-The utility model handles high-volume, lower-stakes operations and can be a cheaper/faster model than the chat model. Browser automation is exposed as the direct `browser` tool; the main agent decides when to call it. Changing the embedding model invalidates the existing vector index - the entire knowledge base is re-indexed automatically.
13
+The utility model handles high-volume, lower-stakes operations and can be cheaper or faster than the chat model.
14
+
15
+Browser automation is exposed through the direct `browser` tool. The main agent decides when to call it.
16
+
17
+The Browser defaults to Docker Playwright Chromium. It can optionally use A0 CLI Bring Your Own Browser mode for a host Chrome-family browser.
18
+
19
+Browser-owned helper operations can use a Browser LLM preset when configured.
20
+
21
+Changing the embedding model invalidates the existing vector index. The knowledge base is re-indexed automatically.
22
23
## Model Providers
24