Document Agent Editor workflows and policies
Replace the legacy guided-profile instructions with screenshot-led Easy and Advanced editor workflows, project availability, and A0 CLI creation. Document sparse YAML, Markdown, and JSON overrides for identity, prompts, Tool and MCP policy, Skills visibility, and model presets. Refresh adjacent guides and remove obsolete screenshots.
Alessandro committed
Aug 12, 2026 at 07:15 UTC
ba64b57e3b5aa97916102e4aebad4bedaee31b8b
21 files changed
+330
-73
docs/README.md
+1
-1
@@ -30,7 +30,7 @@ docs focus on practical setup, screenshots, and user workflows.
30
- **[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.
31
- **[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.
32
- **[Skills Guide](guides/skills.md):** Open the Skills selector, add active skills, and remove prompt protocol entries you no longer need.
33
-- **[Agent Profiles](guides/agent-profiles.md):** Switch the current chat profile or create a new guided profile from the chat input.
33
+- **[Agent Profiles](guides/agent-profiles.md):** Create and manage profiles in Easy or Advanced mode, set project availability, and control Tool, MCP, and Skill access.
34
- **[Model Presets](guides/model-presets.md):** Create simple named shortcuts for model setups.
35
- **[Memory Guide](guides/memory.md):** Search, edit, delete, and curate memories so useful context does not become stale noise.
36
- **[Projects Tutorial](guides/projects.md):** Learn to create isolated workspaces with dedicated context and memory.
docs/guides/a0-cli-connector.md
+33
-1
@@ -107,7 +107,8 @@ available from `Ctrl+P`.
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. |
110
+| `/profile` | Open the profile menu; add a name to select, or a quoted name and instructions to create. |
111
+| `/permissions` | Edit Tool, MCP, and Skill access for the current profile. |
112
| `/compact` | Compact the current chat after confirmation. |
113
| `/pause` | Pause the active run. |
114
| `/resume` | Resume a paused run. |
@@ -121,6 +122,37 @@ available from `Ctrl+P`.
122
| `/help` | Print the available command list in the shell. |
123
| `/quit` | Disconnect and exit the CLI. |
124
125
+### Agent profiles and permissions
126
+
127
+Open the compact profile menu:
128
+
129
+```text
130
+/profile
131
+```
132
+
133
+
134
+
135
+Select an existing profile by its unquoted name or ID, or create one directly:
136
+
137
+```text
138
+/profile Developer
139
+/profile "Source Scout" "Verify every important claim and cite the source."
140
+```
141
+
142
+Quick creation opens a fresh chat with the new profile selected.
143
+
144
+
145
+
146
+Use `/permissions` to edit the current profile's Tools, MCPs, and Skills.
147
+Entries move through **Default**, **On**, and **Off**; the Tools, MCPs, and
148
+Skills tabs each expose their own category default.
149
+
150
+
151
+
152
+Profile editing follows the current chat scope. A project chat writes project
153
+overrides; a chat with no project writes Global overrides. For the complete Web
154
+UI and file-format guide, see [Agent Profiles](agent-profiles.md).
155
+
156
## Host Browser
157
158
Use this when you want Agent Zero to browse with a browser on your computer.
docs/guides/agent-profiles.md
+267
-58
@@ -1,94 +1,303 @@
1
-# Agent Profiles
1
+# Agent Profiles and the Agent Editor
2
3
-Agent Profiles change the voice, habits, and prompt instructions driving the
4
-current chat.
3
+Agent Profiles give a chat a repeatable role, set of instructions, model preset,
4
+and capability policy. Use one when you want Agent Zero to work consistently as
5
+a developer, researcher, reviewer, writer, or another specialist.
6
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.
7
+The Agent Editor is deterministic: it does not call a model to interpret your
8
+changes. It writes only the profile overrides shown in its Review page and
9
+leaves the bundled profiles under `/a0/agents` unchanged.
10
10
-For architecture and source-linked internals, use
11
-[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
11
+## Open the Agent Editor
12
13
-## Switch Profile In A Chat
13
+The profile menu is beside the chat input.
14
15
-The profile menu lives in the status bar near the chat input.
15
+
16
17
-
17
+- Select a profile name to use it in the current chat.
18
+- Select **Edit** on a row to open that profile in Easy mode.
19
+- Select **Manage agents** to create, duplicate, reset, delete, or change the
20
+ availability of profiles.
21
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.
22
+Changing the selected profile affects only that chat. To choose the profile for
23
+future Global chats, open **Settings -> Agent Config**.
24
24
-The change applies to the selected chat. Other chats can keep their own profile.
25
+## Create or edit a profile in Easy mode
26
26
-> [!TIP]
27
-> Use **Settings -> Agent Config** when you want to change the default profile
28
-> for new chats.
27
+Open **Manage agents**, select **Create agent**, and complete the form:
28
30
-## Create A New Agent Profile
29
+1. Choose **Global** to make the profile available everywhere, or choose a
30
+ project to keep the profile and its overrides in that project.
31
+2. Enter the agent name. Agent Zero creates a stable profile ID from the name.
32
+3. Optionally choose a color or image.
33
+4. Select a model preset, or keep the current preset.
34
+5. Write direct instructions: what the agent should do, how it should reason,
35
+ and how it should communicate.
36
+6. Review the capability defaults and any individual Tool, MCP, or Skill
37
+ decisions.
38
+7. Select **Create agent** or **Save changes**.
39
32
-The same menu includes **Create new Agent Profile**.
40
+
41
34
-
42
+Creating a profile opens a fresh chat with the new profile selected. Editing an
43
+existing profile also offers **Save & test**, which saves and opens a fresh chat
44
+for testing without changing the old chat's history.
45
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.
46
+### Choose capability access
47
39
-The flow is intentionally conversational:
48
+Easy mode has separate default switches and expandable lists for **Tools**,
49
+**MCPs**, and **Skills**.
50
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.
51
+
52
46
-Good answers are practical:
53
+Each item has three states:
54
48
-```text
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
-```
55
+| State | Meaning |
56
+| --- | --- |
57
+| **On** | Always allow this item for the profile. |
58
+| **Default (on/off)** | Follow the category's **Allow ... by default** switch. |
59
+| **Off** | Block this item for the profile. |
60
+
61
+Changing a category default affects current and future items that remain on
62
+**Default**. Explicit **On** and **Off** decisions stay pinned. Tools and MCPs
63
+have separate defaults even though their decisions are stored by the same Tool
64
+Access policy owner. Skills use their own visibility policy.
65
+
66
+> [!NOTE]
67
+> Skill access controls discovery and new loading. It does not remove skill
68
+> text that is already part of a chat's saved history.
69
+
70
+## Manage existing profiles and project availability
71
+
72
+**Manage agents** shows the active profile and every profile available to the
73
+selected scope. Use the **Project** selector before making a change.
74
+
75
+
76
+
77
+The row actions have distinct effects:
78
+
79
+| Action | Effect |
80
+| --- | --- |
81
+| Availability toggle | Show or hide the profile for selection and delegation in the selected scope. |
82
+| **Duplicate** | Create an independent copy with a new ID. |
83
+| **Reset to default** | Remove overrides from the selected scope; bundled originals remain. |
84
+| Edit icon | Open the profile in the selected scope. |
85
+| Delete icon | Permanently delete a custom profile after confirmation. |
86
+
87
+To stop a profile from being selected or delegated to in one project:
88
+
89
+1. Open **Manage agents**.
90
+2. Choose the project.
91
+3. Turn that profile's availability toggle off.
92
+
93
+The Global profile is not deleted or changed. Agent Zero keeps at least one
94
+profile available in every scope; if a chat uses a profile that becomes
95
+unavailable, it is reconciled to an available profile.
96
+
97
+## Advanced mode
98
+
99
+Select **Advanced** when you need more than the Easy form. The left navigation
100
+separates six concerns:
101
+
102
+1. **Identity** — title, description, profile ID, delegation guidance, image,
103
+ and model preset.
104
+2. **Prompt files** — edit individual inherited or customized Markdown prompt
105
+ files in the ACE editor.
106
+3. **Tools** — search local and plugin tools and set their access policy.
107
+4. **MCPs** — set access independently for tools discovered from MCP servers.
108
+5. **Skills** — control which installed skills the profile can discover and
109
+ load.
110
+6. **Review** — inspect the exact files that will be created, updated, or
111
+ deleted before saving.
112
+
113
+### Edit prompt files
114
+
115
+Choose a prompt file on the left. The editor shows its effective source and the
116
+sparse customization path. **Reset to default** removes only your override for
117
+that file.
118
+
119
+
120
+
121
+### Review explicit capability decisions
122
+
123
+Advanced Tools, MCPs, and Skills use the same **On / Default / Off** semantics
124
+as Easy mode, with search and origin filtering. Advanced mode can also show a
125
+retained decision for an item that is not currently available, so you can clear
126
+or change stale configuration.
127
+
128
+
129
+
130
+### Review before saving
131
+
132
+Review is the source of truth for the save. If a file is not listed, the editor
133
+will not write or delete it.
134
+
135
+
136
+
137
+For a built-in profile, **Remove my changes** deletes only the selected scope's
138
+overrides. Full deletion is offered only for custom profiles.
139
+
140
+## Use profiles from A0 CLI
141
+
142
+The [A0 CLI Connector](a0-cli-connector.md) exposes the same profile and
143
+permission owners.
144
145
```text
54
-I want a cautious finance analyst profile. It should separate facts from
55
-assumptions, prefer spreadsheets, and never present estimates as certainty.
146
+/profile
147
+/profile Developer
148
+/profile "Source Scout" "Verify every important claim and cite the source."
149
+/permissions
150
```
151
58
-## Profile, Skill, Project, Or Model Preset?
152
+- `/profile` opens the profile menu. Choose **Create profile** or **Edit current
153
+ profile** for a compact two-step editor.
154
+- `/profile Developer` selects an existing profile by name or ID.
155
+- `/profile "<name>" "<instructions>"` creates a profile in the current chat's
156
+ Global or project scope, then opens a fresh chat with it selected.
157
+- `/permissions` edits Tools, MCPs, and Skills for the current profile. Each row
158
+ cycles through **Default**, **On**, and **Off**; Tools and MCPs have independent
159
+ defaults.
160
60
-These controls are related, but they solve different problems.
161
+
162
62
-| Use this | When you want to change |
163
+
164
+
165
+
166
+
167
+The CLI derives scope from the current chat. It intentionally has no separate
168
+scope selector: a project chat edits that project, while a chat with no project
169
+edits Global.
170
+
171
+## Power-user file overrides
172
+
173
+Prefer the Agent Editor because it validates changes and shows the exact save
174
+plan. If you manage files directly, use the same sparse layout and formats.
175
+
176
+| Scope | Writable profile root |
177
| --- | --- |
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. |
178
+| Global | `/a0/usr/agents/<profile-id>/` |
179
+| Project | `/a0/usr/projects/<project>/.a0proj/agents/<profile-id>/` |
180
69
-For small local models that narrate instead of calling tools, use the bundled
70
-**Tiny Local** profile or the project-scoped Prompt Include recipe in
71
-[Local Model Tool Use](local-model-tool-use.md).
181
+Never edit the bundled `/a0/agents/<profile-id>` files for a customization.
182
+Create only the files and keys you need to override.
183
73
-Example:
184
+```text
185
+<profile-root>/
186
+├── agent.yaml
187
+├── prompts/
188
+│ └── agent.system.main.specifics.md
189
+└── plugins/
190
+ ├── _model_config/config.json
191
+ ├── _tool_access/config.json
192
+ └── _skills/config.json
193
+```
194
+
195
+### Identity definition: YAML
196
75
-- use a **Project** for a client repository;
76
-- use an **Agent Profile** for "careful code reviewer";
77
-- pin a **Skill** for a repeated workflow;
78
-- choose a **Model Preset** for speed, cost, or maximum capability.
197
+Authored profile definitions use YAML. A missing key inherits; an explicitly
198
+empty value clears that field.
199
80
-## Small Advanced Note
200
+```yaml
201
+title: Source Scout
202
+description: Researches technical claims and returns concise evidence.
203
+context: Use this agent for source discovery and claim verification.
204
+```
205
82
-Most users should create profiles through the menu above.
206
+### Prompt overrides: Markdown
207
84
-If you edit files directly, custom profiles normally live in:
208
+Place a Markdown file under `prompts/` with the same filename as the prompt you
209
+want to replace. Do not copy the whole prompt tree. For example:
210
211
```text
87
-/a0/usr/agents/<profile-name>/
212
+prompts/agent.system.main.specifics.md
213
+```
214
+
215
+The Agent Editor's Prompt files page is the easiest way to discover available
216
+filenames and the exact customization path. See the
217
+[Prompts guide](https://www.agent-zero.ai/p/docs/prompts/) for the
218
+prompt-loading model.
219
+
220
+### Tool and MCP policy: JSON
221
+
222
+Runtime and editor-written configuration uses JSON. Tools and MCPs share
223
+`plugins/_tool_access/config.json`, but have independent defaults:
224
+
225
+```json
226
+{
227
+ "mode": "custom",
228
+ "default": "allow",
229
+ "mcp_default": "block",
230
+ "allowed": [
231
+ "local:call_subordinate",
232
+ "mcp:deep_wiki:ask_question"
233
+ ],
234
+ "blocked": [
235
+ "plugin:_code_execution:code_execution_tool"
236
+ ]
237
+}
238
+```
239
+
240
+Canonical IDs use these forms:
241
+
242
+| Source | ID form | Example |
243
+| --- | --- | --- |
244
+| Core/local tool | `local:<tool>` | `local:call_subordinate` |
245
+| Plugin tool | `plugin:<plugin-id>:<tool>` | `plugin:_code_execution:code_execution_tool` |
246
+| MCP tool | `mcp:<server>:<tool>` | `mcp:deep_wiki:ask_question` |
247
+
248
+An ID in `allowed` is **On**; an ID in `blocked` is **Off**; an ID in neither
249
+list follows `default` or `mcp_default`. Runtime-required response handling is
250
+not offered as a configurable tool.
251
+
252
+MCP server definitions themselves still belong in **Settings -> MCP**. The
253
+profile policy decides which discovered MCP tools the agent may use; it does
254
+not create or connect an MCP server. See [MCP Setup](mcp-setup.md).
255
+
256
+### Skill visibility policy: JSON
257
+
258
+Skills use `plugins/_skills/config.json`. Keep the policy inside
259
+`visibility_policy` so unrelated Skills settings remain intact:
260
+
261
+```json
262
+{
263
+ "visibility_policy": {
264
+ "mode": "custom",
265
+ "default": "allow",
266
+ "allowed": ["Research"],
267
+ "blocked": ["Deploy production"]
268
+ }
269
+}
270
+```
271
+
272
+The entries are skill names or paths recognized by the Skills catalog. See the
273
+[Skills guide](skills.md) for writing and installing skill definitions.
274
+
275
+### Model preset selection: JSON
276
+
277
+To pin a profile to an existing preset, use
278
+`plugins/_model_config/config.json`:
279
+
280
+```json
281
+{
282
+ "model_preset": "Codex"
283
+}
284
```
285
90
-Custom prompts belong inside that profile's `prompts/` folder. Keep direct file
91
-edits small and documented so updates remain easy to understand later.
286
+Use **Edit Presets** in the UI to author presets; profile configuration should
287
+only select one. See [Model Presets](model-presets.md).
288
+
289
+## Profile, Skill, Project, or model preset?
290
+
291
+| Use this | When you want to change |
292
+| --- | --- |
293
+| **Agent Profile** | The agent's role, instructions, model choice, and allowed capabilities. |
294
+| **Skill** | A specific procedure the agent can discover or keep active in a chat. |
295
+| **Project** | Files, workspace, memory, instructions, secrets, and scoped overrides. |
296
+| **Model Preset** | The model configuration used by a chat or profile. |
297
+
298
+For small local models that narrate instead of calling tools, use the bundled
299
+**Tiny Local** profile or the project-scoped Prompt Include recipe in
300
+[Local Model Tool Use](local-model-tool-use.md).
301
93
-For deeper file layout and prompt-loading details, use
302
+For source-linked internals, use
303
[DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero).
docs/guides/mcp-setup.md
+4
-1
@@ -73,7 +73,10 @@ After applying the config, look for the status below the editor.
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.
76
+After the connection works, Agent Zero discovers the MCP tools. The active
77
+Agent Profile's MCP policy still decides which discovered tools it may use. Use
78
+**Edit agent -> MCPs** to keep the category default or set an individual tool
79
+to **On** or **Off**. See [Agent Profiles](agent-profiles.md#choose-capability-access).
80
81
You can still ask naturally:
82
docs/guides/projects.md
+4
@@ -102,6 +102,10 @@ workspace for that chat.
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
105
+Projects can also own Agent Profile overrides and availability. In **Manage
106
+agents**, select a project before editing or turning a profile off; the Global
107
+profile remains unchanged. See [Agent Profiles](agent-profiles.md).
108
+
109
## What Changes After Activation
110
111
When a project is active, Agent Zero can use:
docs/guides/skills.md
+4
@@ -63,6 +63,10 @@ usually easier for the agent to follow.
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
+The Agent Editor can also set a profile-wide Skills visibility policy. That
67
+policy controls discovery and new loading; it does not erase skill text already
68
+stored in a chat's history. See [Agent Profiles](agent-profiles.md#choose-capability-access).
69
+
70
## Creating Skills
71
72
This page is about using skills in the Web UI.
docs/guides/usage.md
+6
-5
@@ -84,13 +84,14 @@ chat.
84
85
86
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.
87
+Use the profile menu near the chat input to switch the current chat or edit a
88
+profile. Select **Manage agents** to create, duplicate, reset, delete, or change
89
+profile availability for Global or one project.
90
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.
91
+
92
93
-
93
+Use **Settings -> Agent Config** when you want to change the default profile for
94
+new Global chats.
95
96
See the [Agent Profiles guide](agent-profiles.md).
97
docs/quickstart.md
+2
-1
@@ -152,7 +152,8 @@ Shows the chat input **+** menu, the Skills selector, and how active skills are
152
153
### [Open A0 Agent Profiles Guide](guides/agent-profiles.md)
154
155
-Shows how to switch profiles in a chat and start the guided profile-creation flow.
155
+Shows how to switch profiles, create one in Easy mode, edit prompts in Advanced
156
+mode, and set Tool, MCP, Skill, and project-availability policies.
157
158
### [Open A0 Model Presets Guide](guides/model-presets.md)
159
docs/res/usage/a0-cli/a0-cli-permissions.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-permissions.png differ
docs/res/usage/a0-cli/a0-cli-profile-created.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-profile-created.png differ
docs/res/usage/a0-cli/a0-cli-profile-menu.png
Binary files /dev/null and b/docs/res/usage/a0-cli/a0-cli-profile-menu.png differ
docs/res/usage/webui/agent-editor-advanced-prompts.png
Binary files /dev/null and b/docs/res/usage/webui/agent-editor-advanced-prompts.png differ
docs/res/usage/webui/agent-editor-advanced-tools.png
Binary files /dev/null and b/docs/res/usage/webui/agent-editor-advanced-tools.png differ
docs/res/usage/webui/agent-editor-easy-permissions.png
Binary files /dev/null and b/docs/res/usage/webui/agent-editor-easy-permissions.png differ
docs/res/usage/webui/agent-editor-easy.png
Binary files /dev/null and b/docs/res/usage/webui/agent-editor-easy.png differ
docs/res/usage/webui/agent-editor-review.png
Binary files /dev/null and b/docs/res/usage/webui/agent-editor-review.png differ
docs/res/usage/webui/agent-profile-create-prompt.png
Binary files a/docs/res/usage/webui/agent-profile-create-prompt.png and /dev/null differ
docs/res/usage/webui/agent-profile-manager.png
Binary files /dev/null and b/docs/res/usage/webui/agent-profile-manager.png differ
docs/res/usage/webui/agent-profile-selector.png
Binary files a/docs/res/usage/webui/agent-profile-selector.png and b/docs/res/usage/webui/agent-profile-selector.png differ
docs/setup/installation.md
+5
-4
@@ -417,13 +417,14 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
417
- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
418
- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
419
420
-See the [Agent Profiles guide](../guides/agent-profiles.md) for the chat menu,
421
-profile switching, and guided profile creation.
420
+See the [Agent Profiles guide](../guides/agent-profiles.md) for profile
421
+switching, the Easy and Advanced editors, capability policy, and project
422
+availability.
423
424
> [!NOTE]
425
> Since v0.9.7, custom prompts belong inside a specific agent profile rather
425
-> than a shared `/prompts` folder. Most users should create profiles from the
426
-> chat profile menu.
426
+> than a shared `/prompts` folder. Most users should use **Manage agents** and
427
+> the Agent Editor instead of editing files directly.
428
429
> [!NOTE]
430
> 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.
plugins/_tool_access/README.md
+4
-2
@@ -3,8 +3,10 @@
3
Tool Access is the always-enabled runtime owner for Agent Editor tool policy.
4
Policies use the standard plugin precedence: active project profile, active
5
project, user profile, bundled/plugin profile, then the default. Sparse project
6
-policy lives under `.a0proj/plugins/_tool_access/config.json`; profile policy
7
-lives under `usr/agents/<profile>/plugins/_tool_access/config.json`.
6
+policy lives under `.a0proj/plugins/_tool_access/config.json`; Global profile
7
+policy lives under `usr/agents/<profile>/plugins/_tool_access/config.json`, and
8
+project-profile policy lives under
9
+`usr/projects/<project>/.a0proj/agents/<profile>/plugins/_tool_access/config.json`.
10
The Plugins screen exposes these scoped files through its existing
11
configuration list; policy choices remain owned by Agent Editor.
12