Agent Zero AI framework
docs: update documentation about agent profiles creation flow
Alessandrob4687015e28e
diff --git a/docs/README.md b/docs/README.mdindex 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.mdindex 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 behav3. Agent Zero merges these overrides with the default prompts automatically4. 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.mdindex 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## Projectsdiff --git a/docs/guides/agent-profiles.md b/docs/guides/agent-profiles.mdnew file mode 100644index 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.mdindex 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.mdindex 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 |