Agent Zero · main guide

Persona and rules

Agent Zero calls this setup an agent profile, which is a profile or prompt folder. A profile sets the name and tone, the standing rules, and which tools that chat may use. The shared advice that applies to every agent is on Persona and rules.

What Agent Zero calls it

The profile menu sits beside the chat input, and Manage agents is where you create one. Edit opens a profile you already have, and the Agent Editor writes only your override. A global profile is saved under /a0/usr/agents/<profile-id>/ on the mapped data folder. A project profile is saved under /a0/usr/projects/<project>/.a0proj/agents/<profile-id>/ in that same folder. With Launcher's default workspace, /a0/usr is ~/agent-zero/<instance>/usr on your computer (or the a0_usr volume from the direct Docker command).

The Instructions box is where the persona and the standing rules both go. The editor stores that text in prompts/agent.system.main.specifics.md inside the custom profile under /a0/usr.

Set a persona

  1. Open the profile menu beside the chat input, click Manage agents, then click Create agent. Choose Global so the new profile can be used in every chat.

What you should see a form with a name, a model preset, and a box for instructions.

  1. Type a name, and in the instructions say how the agent should talk to you. A calm tone and short answers are a solid start, so leave the tool switches as they are. Click Create agent when the name and the tone are filled in.

What you should see a fresh chat opens, and the profile menu shows the name you typed.

Set rules

  1. Open the profile menu and click Edit on that profile, then add the standing rules in the same box. Ask it to keep new files in the workspace, to ask you before it deletes a file, and to say when it is not sure. Click Save & test when those rules are in the instructions.

What you should see a fresh test chat opens, and the older chat keeps the history it already had.

  1. Ask one question that should show the rules, such as what it will do before it deletes a workspace file.

What you should see the reply uses the tone you set, and it says it will ask before a deletion.

A profile for one project, a subordinate, or a phone chat

A project can have its own profile, separate from the global one you just made. Open Manage agents, click Create agent, and choose the project instead of Global. Write the instructions for that work only, then click Create agent.

What you should see the profile is available in that project, and a chat with no project does not have to use it.

You can also put standing rules on the project itself when you create it. Open Projects from the dashboard, click Create project, give it a title, and write practical instructions. Those instructions apply to the chats and tasks that use that project.

What you should see a chat with that project active follows the project instructions you typed.

The main agent can hand part of a job to a subordinate that uses another profile. In Manage agents, the availability toggle shows or hides a profile for selection and delegation. Leave the toggle on for a profile you want a subordinate to use.

What you should see a hidden profile is not offered when the main agent hands work to a subordinate.

To switch profiles in the chat you have open, click the profile name in the menu and pick another. That change affects only the open chat, and your other chats keep their own profiles. For future global chats, open Settings → Agent Settings → Agent Config (written Settings → Agent → Agent Config in the docs) and set Default agent profile.

What you should see the open chat shows the profile you just picked, and a different chat still shows its own.

Neither Telegram nor WhatsApp uses a separate persona file, and both can switch profiles with /agent once your account or number is on the allow list. In Telegram, /agent switches the profile when the run is idle and /status names it, while WhatsApp Integration also has an agent_instructions box for extra instructions.

What you should see /status in Telegram, or /agent in WhatsApp, shows the profile you picked for that phone chat.

What not to edit

Leave the built-in prompt files under /a0/prompts alone, because an update can replace the prompts folder that ships with Agent Zero. Those files include the text the agent needs in order to use its tools. Do not edit the bundled profiles under /a0/agents, and do not copy the whole prompt tree into your profile.

Use Create agent or Edit, which saves the override in your profile folder under /a0/usr. The editor leaves the built-in files unchanged when it writes that override. Reset to default on one prompt file removes only your override for that file.

How to undo

  1. Back up first with Settings → Check for updates → Backup & Restore → Create Backup, or with Backup /a0/usr on the instance menu in Launcher.

What you should see a backup zip on your computer, saved before you change the profile.

  1. Open Manage agents, and on a built-in profile you changed, click Reset to default. That removes your overrides and leaves the bundled original in place. On a profile you created, click the delete icon and click Delete agent to confirm.

What you should see the built-in profile is back to its original instructions, or your custom profile is gone from the menu.

Profile instructions.

Sources

Checked 14 November 2026.

Next

Next: Persona and rules.

Checked 14 November 2026 · prices, limits, and versions change