| 1 | # Agent Profiles and the Agent Editor |
| 2 | |
| 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 | |
| 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 | |
| 11 | ## Open the Agent Editor |
| 12 | |
| 13 | The profile menu is beside the chat input. |
| 14 | |
| 15 |  |
| 16 | |
| 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 | |
| 22 | Changing the selected profile affects only that chat. To choose the profile for |
| 23 | future Global chats, open **Settings -> Agent Config**. |
| 24 | |
| 25 | ## Create or edit a profile in Easy mode |
| 26 | |
| 27 | Open **Manage agents**, select **Create agent**, and complete the form: |
| 28 | |
| 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 | |
| 40 |  |
| 41 | |
| 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 | |
| 46 | ### Choose capability access |
| 47 | |
| 48 | Easy mode has separate default switches and expandable lists for **Tools**, |
| 49 | **MCPs**, and **Skills**. |
| 50 | |
| 51 |  |
| 52 | |
| 53 | Each item has three states: |
| 54 | |
| 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 |
| 146 | /profile |
| 147 | /profile Developer |
| 148 | /profile "Source Scout" "Verify every important claim and cite the source." |
| 149 | /permissions |
| 150 | ``` |
| 151 | |
| 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 | |
| 161 |  |
| 162 | |
| 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 | | --- | --- | |
| 178 | | Global | `/a0/usr/agents/<profile-id>/` | |
| 179 | | Project | `/a0/usr/projects/<project>/.a0proj/agents/<profile-id>/` | |
| 180 | |
| 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 | |
| 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 | |
| 197 | Authored profile definitions use YAML. A missing key inherits; an explicitly |
| 198 | empty value clears that field. |
| 199 | |
| 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 | |
| 206 | ### Prompt overrides: Markdown |
| 207 | |
| 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 |
| 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 | |
| 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 | |
| 302 | For source-linked internals, use |
| 303 | [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero). |