docs: update documentation about agent profiles creation flow
The new guide explains: - where profiles live - what belongs in agent.yaml - how prompt overrides work - which root /prompts files are useful levers - how profile-specific Main/Utility models are actually configured via _model_config/config.json - why that config must be complete, not partial
Alessandro committed
Apr 21, 2026 at 18:16 UTC
b4687015e28e3c9dc7213d7d6e68c2a20daeb7b5
6 files changed
+173
-12
docs/README.md
+2
@@ -16,6 +16,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
16
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.
20
- **[Projects Tutorial](guides/projects.md):** Learn to create isolated workspaces with dedicated context and memory.
21
- **[API Integration](guides/api-integration.md):** Add external APIs without writing code.
22
- **[MCP Setup](guides/mcp-setup.md):** Configure Model Context Protocol servers.
@@ -95,6 +96,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
96
- [Memory Management](guides/usage.md#memory-management)
97
- [Backup & Restore](guides/usage.md#backup--restore)
98
- [A0 CLI Connector](guides/a0-cli-connector.md)
99
+ - [Agent Profiles](guides/agent-profiles.md)
100
- [Projects Tutorial](guides/projects.md)
101
- [API Integration](guides/api-integration.md)
102
- [MCP Setup](guides/mcp-setup.md)
docs/developer/architecture.md
+2
@@ -224,6 +224,8 @@ The `prompts` directory contains various Markdown files that control agent behav
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
docs/developer/extensions.md
+17
-10
@@ -290,21 +290,26 @@ Agent Zero supports creating specialized subagents with customized behavior. The
290
291
### Creating a Subagent
292
293
-1. Create a directory in `/agents/{agent_profile}/`
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
- - `/agents/{agent_profile}/extensions/` - for custom extensions
296
- - `/agents/{agent_profile}/tools/` - for custom tools
297
- - `/agents/{agent_profile}/prompts/` - for custom prompts
298
- - `/agents/{agent_profile}/settings.json` - for agent-specific configuration overrides
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
-The `settings.json` file for an agent uses the same structure as `usr/settings.json`, but you only need to specify the fields you want to override. Any field omitted from the agent-specific `settings.json` will continue to use the global value.
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
-This allows power users to, for example, change the AI model, context window size, or other settings for a single agent without affecting the rest of the system.
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
```
307
-/agents/_example/
311
+/usr/agents/my-profile/
312
+├── agent.yaml
313
├── extensions/
314
│ └── agent_init/
315
│ └── _10_example_extension.py
@@ -313,14 +318,16 @@ This allows power users to, for example, change the AI model, context window siz
318
├── tools/
319
│ ├── example_tool.py
320
│ └── response.py
316
-└── settings.json
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
323
-- `settings.json` overrides any global settings for this specific agent (only for the fields defined in this file)
330
+- `plugins/_model_config/config.json` optionally gives this profile its own Main, Utility, and Embedding model settings
331
332
## Projects
333
docs/guides/agent-profiles.md
new
+148
@@ -0,0 +1,148 @@
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.
4
+
5
+You can select the active profile from **Settings > Agent Config** or from the chat composer profile selector.
6
+
7
+## Where Profiles Live
8
+
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. |
15
+
16
+## Required Profile Definition
17
+
18
+Every profile needs an `agent.yaml` file:
19
+
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
+```
26
+
27
+`agent.yaml` intentionally has only these fields:
28
+
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 |
34
+
35
+Do not put model settings, temperature, or tool allow-lists in `agent.yaml`.
36
+
37
+## Prompt Overrides
38
+
39
+Profiles inherit the root prompt files from `/a0/prompts`. To customize a profile, copy only the prompt files you need into:
40
+
41
+```text
42
+/a0/usr/agents/<profile>/prompts/
43
+```
44
+
45
+The most common override is:
46
+
47
+```text
48
+prompts/agent.system.main.specifics.md
49
+```
50
+
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
+}
115
+```
116
+
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.
118
+
119
+Do not store API keys in this file. API keys are managed globally through Settings and secrets.
120
+
121
+## Tools and Extensions
122
+
123
+Profiles can also add or override tools and extensions:
124
+
125
+```text
126
+/a0/usr/agents/<profile>/tools/<tool_name>.py
127
+/a0/usr/agents/<profile>/extensions/<hook_point>/_NN_name.py
128
+```
129
+
130
+If you add a tool, also add a matching prompt file:
131
+
132
+```text
133
+/a0/usr/agents/<profile>/prompts/agent.system.tool.<tool_name>.md
134
+```
135
+
136
+## Quick Example
137
+
138
+```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
146
+```
147
+
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.
docs/setup/installation.md
+2
@@ -312,6 +312,8 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
312
- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
313
- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
314
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
+
317
> [!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.
319
skills/a0-development/SKILL.md
+2
-2
@@ -491,7 +491,7 @@ context: Use this agent for software development tasks, including writing code,
491
| `context` | Instructions for when to delegate to this profile |
492
493
> [!NOTE]
494
-> There is **no** per-profile model configuration, temperature, or allowed_tools in the profile YAML. Model configuration is managed by the `_model_config` plugin. Tool availability is controlled by plugin activation.
494
+> There is **no** model configuration, temperature, or allowed_tools in the profile YAML. `agent.yaml` contains only `title`, `description`, and `context`. Profile-specific Main/Utility model settings are managed by the `_model_config` plugin in `usr/agents/<profile>/plugins/_model_config/config.json`. Tool availability is controlled by plugin activation.
495
496
### Where Profiles Live
497
@@ -843,4 +843,4 @@ For contribution guidelines, see `/a0/docs/contribution.md`. For plugin contribu
843
| `/a0/helpers/plugins.py` | Plugin system manager |
844
| `/a0/helpers/print_style.py` | Console output formatting |
845
| `/a0/agents/_example/` | Reference example profile with tool + extension |
846
-| `/a0/prompts/agent.system.main.md` | Main system prompt entry point |
\ No newline at end of file
846
+| `/a0/prompts/agent.system.main.md` | Main system prompt entry point |