Skip to content

Agent Zero AI framework

docs: update documentation about agent profiles creation flow

Alessandrob4687015e28e
diff --git a/docs/README.md b/docs/README.md
index 055d92e2c..c89e83e53 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,6 +16,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
- **[Usage Guide](guides/usage.md):** Comprehensive guide to Agent Zero's features and capabilities.
- **[A0 CLI Connector](guides/a0-cli-connector.md):** Terminal-first companion workflow for Agent Zero.
+- **[Agent Profiles](guides/agent-profiles.md):** Create and select specialized profiles, prompt overrides, and profile-specific model config.
- **[Projects Tutorial](guides/projects.md):** Learn to create isolated workspaces with dedicated context and memory.
- **[API Integration](guides/api-integration.md):** Add external APIs without writing code.
- **[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
- [Memory Management](guides/usage.md#memory-management)
- [Backup & Restore](guides/usage.md#backup--restore)
- [A0 CLI Connector](guides/a0-cli-connector.md)
+ - [Agent Profiles](guides/agent-profiles.md)
- [Projects Tutorial](guides/projects.md)
- [API Integration](guides/api-integration.md)
- [MCP Setup](guides/mcp-setup.md)
diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md
index ae206a63c..b8ba0c484 100644
--- a/docs/developer/architecture.md
+++ b/docs/developer/architecture.md
@@ -224,6 +224,8 @@ The `prompts` directory contains various Markdown files that control agent behav
3. Agent Zero merges these overrides with the default prompts automatically
4. Select the **Agent Profile** in Settings to activate the overrides
+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.
+
#### Prompt Inheritance with `{{include original}}`
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:
diff --git a/docs/developer/extensions.md b/docs/developer/extensions.md
index 953ae1fc3..ddc3bfa8f 100644
--- a/docs/developer/extensions.md
+++ b/docs/developer/extensions.md
@@ -290,21 +290,26 @@ Agent Zero supports creating specialized subagents with customized behavior. The
### Creating a Subagent
-1. Create a directory in `/agents/{agent_profile}/`
+1. Create a directory in `/usr/agents/{agent_profile}/` for user-created profiles, or `/agents/{agent_profile}/` only for built-in framework profiles.
2. Override or extend default components by mirroring the structure in the root directories:
- - `/agents/{agent_profile}/extensions/` - for custom extensions
- - `/agents/{agent_profile}/tools/` - for custom tools
- - `/agents/{agent_profile}/prompts/` - for custom prompts
- - `/agents/{agent_profile}/settings.json` - for agent-specific configuration overrides
+ - `/usr/agents/{agent_profile}/agent.yaml` - required profile metadata
+ - `/usr/agents/{agent_profile}/extensions/` - custom extensions
+ - `/usr/agents/{agent_profile}/tools/` - custom tools
+ - `/usr/agents/{agent_profile}/prompts/` - custom prompts
-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.
+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:
-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.
+```text
+/a0/usr/agents/{agent_profile}/plugins/_model_config/config.json
+```
+
+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.
### Example Subagent Structure
```
-/agents/_example/
+/usr/agents/my-profile/
+├── agent.yaml
├── extensions/
│ └── agent_init/
│ └── _10_example_extension.py
@@ -313,14 +318,16 @@ This allows power users to, for example, change the AI model, context window siz
├── tools/
│ ├── example_tool.py
│ └── response.py
-└── settings.json
+└── plugins/
+ └── _model_config/
+ └── config.json
```
In this example:
- `_10_example_extension.py` is an extension that renames the agent when initialized
- `response.py` overrides the default response tool with custom behavior
- `example_tool.py` is a new tool specific to this agent
-- `settings.json` overrides any global settings for this specific agent (only for the fields defined in this file)
+- `plugins/_model_config/config.json` optionally gives this profile its own Main, Utility, and Embedding model settings
## Projects
diff --git a/docs/guides/agent-profiles.md b/docs/guides/agent-profiles.md
new file mode 100644
index 000000000..60ad2dc66
--- /dev/null
+++ b/docs/guides/agent-profiles.md
@@ -0,0 +1,148 @@
+# Agent Profiles
+
+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.
+
+You can select the active profile from **Settings > Agent Config** or from the chat composer profile selector.
+
+## Where Profiles Live
+
+| Location | Purpose |
+|---|---|
+| `/a0/agents/<profile>/` | Built-in framework profiles. Do not edit these for custom work. |
+| `/a0/usr/agents/<profile>/` | User-created profiles. This is the normal place for custom profiles and survives updates. |
+| `/a0/usr/plugins/<plugin>/agents/<profile>/` | Plugin-distributed profiles tied to plugin functionality. |
+| `/a0/usr/projects/<project>/.a0proj/agents/<profile>/` | Project-scoped profiles available only inside one project. |
+
+## Required Profile Definition
+
+Every profile needs an `agent.yaml` file:
+
+```yaml
+title: Data Analyst
+description: Agent specialized in data analysis, visualization, and statistical modeling.
+context: Use this agent for data analysis tasks, creating visualizations, statistical
+ analysis, and working with datasets in Python.
+```
+
+`agent.yaml` intentionally has only these fields:
+
+| Field | Purpose |
+|---|---|
+| `title` | Display name shown in the UI |
+| `description` | One-line summary of the specialization |
+| `context` | Instructions telling a superior agent when to delegate to this profile |
+
+Do not put model settings, temperature, or tool allow-lists in `agent.yaml`.
+
+## Prompt Overrides
+
+Profiles inherit the root prompt files from `/a0/prompts`. To customize a profile, copy only the prompt files you need into:
+
+```text
+/a0/usr/agents/<profile>/prompts/
+```
+
+The most common override is:
+
+```text
+prompts/agent.system.main.specifics.md
+```
+
+This file is intentionally empty by default and is the safest place to add role, expertise, workflow, and style instructions.
+
+Useful root prompt levers:
+
+| File | Use it for |
+|---|---|
+| `agent.system.main.specifics.md` | Role, expertise, persona, workflow, and behavioral specialization. |
+| `agent.system.main.communication.md` | Changing the response contract, such as replacing the default `thoughts`, `headline`, `tool_name`, `tool_args` JSON shape. |
+| `agent.system.main.solving.md` | Changing the problem-solving loop, autonomy level, delegation policy, or verification standard. |
+| `agent.system.main.environment.md` | Describing a different runtime or domain environment. |
+| `agent.system.main.role.md` | Replacing the base Agent Zero role. Use rarely; prefer `specifics.md` when possible. |
+| `agent.system.tool.<name>.md` | Documenting a profile-specific tool or overriding a tool prompt. |
+
+Only override what you actually want to change. Copying unchanged prompt files makes profiles harder to maintain when the framework updates.
+
+## Profile-Specific Models
+
+Main and Utility model settings are not part of `agent.yaml`. They are handled by the always-enabled `_model_config` plugin.
+
+To give one profile its own Main or Utility model, create a companion config file:
+
+| Profile scope | Model config path |
+|---|---|
+| User profile | `/a0/usr/agents/<profile>/plugins/_model_config/config.json` |
+| Plugin-distributed profile | `/a0/usr/plugins/<plugin>/agents/<profile>/plugins/_model_config/config.json` |
+| Project-scoped profile | `/a0/usr/projects/<project>/.a0proj/agents/<profile>/plugins/_model_config/config.json` |
+
+Example complete config:
+
+```json
+{
+ "allow_chat_override": true,
+ "chat_model": {
+ "provider": "openrouter",
+ "name": "anthropic/claude-sonnet-4.6",
+ "api_base": "",
+ "ctx_length": 200000,
+ "ctx_history": 0.7,
+ "vision": true,
+ "rl_requests": 0,
+ "rl_input": 0,
+ "rl_output": 0,
+ "kwargs": {}
+ },
+ "utility_model": {
+ "provider": "openrouter",
+ "name": "openai/gpt-5.4-mini",
+ "api_base": "",
+ "ctx_length": 128000,
+ "ctx_input": 0.7,
+ "rl_requests": 0,
+ "rl_input": 0,
+ "rl_output": 0,
+ "kwargs": {}
+ },
+ "embedding_model": {
+ "provider": "huggingface",
+ "name": "sentence-transformers/all-MiniLM-L6-v2",
+ "api_base": "",
+ "rl_requests": 0,
+ "rl_input": 0,
+ "kwargs": {}
+ }
+}
+```
+
+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.
+
+Do not store API keys in this file. API keys are managed globally through Settings and secrets.
+
+## Tools and Extensions
+
+Profiles can also add or override tools and extensions:
+
+```text
+/a0/usr/agents/<profile>/tools/<tool_name>.py
+/a0/usr/agents/<profile>/extensions/<hook_point>/_NN_name.py
+```
+
+If you add a tool, also add a matching prompt file:
+
+```text
+/a0/usr/agents/<profile>/prompts/agent.system.tool.<tool_name>.md
+```
+
+## Quick Example
+
+```text
+/a0/usr/agents/data-analyst/
++-- agent.yaml
++-- prompts/
+| +-- agent.system.main.specifics.md
++-- plugins/
+ +-- _model_config/
+ +-- config.json
+```
+
+The `plugins/_model_config/config.json` file is optional. Use it only when this profile needs different models from the global or project settings.
diff --git a/docs/setup/installation.md b/docs/setup/installation.md
index 6ab094483..1e6d029a8 100644
--- a/docs/setup/installation.md
+++ b/docs/setup/installation.md
@@ -312,6 +312,8 @@ Agent Zero provides a comprehensive settings interface to customize various aspe
- **Memory Subdirectory:** Select the subdirectory for agent memory storage, allowing separation between different instances.
- **Knowledge Subdirectory:** Specify the location of custom knowledge files to enhance the agent's understanding.
+See the [Agent Profiles guide](../guides/agent-profiles.md) for profile file locations, `agent.yaml`, prompt overrides, and profile-specific Main/Utility model configuration.
+
> [!NOTE]
> 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.
diff --git a/skills/a0-development/SKILL.md b/skills/a0-development/SKILL.md
index 869ed7c3d..188567ee6 100644
--- a/skills/a0-development/SKILL.md
+++ b/skills/a0-development/SKILL.md
@@ -491,7 +491,7 @@ context: Use this agent for software development tasks, including writing code,
| `context` | Instructions for when to delegate to this profile |
> [!NOTE]
-> 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.
+> 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.
### Where Profiles Live
@@ -843,4 +843,4 @@ For contribution guidelines, see `/a0/docs/contribution.md`. For plugin contribu
| `/a0/helpers/plugins.py` | Plugin system manager |
| `/a0/helpers/print_style.py` | Console output formatting |
| `/a0/agents/_example/` | Reference example profile with tool + extension |
-| `/a0/prompts/agent.system.main.md` | Main system prompt entry point |
\ No newline at end of file
+| `/a0/prompts/agent.system.main.md` | Main system prompt entry point |