Agent Roles and Instructions

Agent Roles help you reach a useful starting point faster by preparing behavior for a common job, while instructions adapt that job to your business. For example, a sales role can focus on qualification and next steps, while a support role can prioritize diagnosis and escalation to a human. Your saved instructions and business knowledge remain the final source of how an agent should behave.

Navigation: Open a Voice, Email, or Messaging Agent, then select its General tab.

Choose Agent Roles

Choose roles to combine compatible responsibilities without writing every behavior from scratch. Use only roles that belong in the same customer experience; an agent with a focused job is easier to test and improve.

Open Agent Roles and review each role’s description. Select the role that best matches the agent’s main responsibility. When the selector permits several roles, Versafy prepares one combined set of defaults for you to review.

Custom is for an agent whose behavior you want to write from scratch. It cannot be combined with the other roles. You can give a Custom role a team-friendly name.

Change roles on an existing agent

When you change roles, the confirmation dialog gives you a safe choice:

• change only the role labels and keep your current instructions; or
• apply the selected role defaults and replace the settings listed in the warning.

Keep current instructions when they have been carefully customized and still match the new role. Apply defaults when you intentionally want to rebuild from the selected role.

If several roles are selected, review the prepared instructions before saving. Close the preview without saving when the combination does not reflect the job.

Protect Email Agent setup

A role change can change email classification categories. If you choose to apply new role defaults, Email Auto-Reply and CRM category mappings may be turned off or cleared so old category rules are not used accidentally.

After applying a role to an Email Agent:

1. review classification categories;
2. review Auto-Reply mode for every category;
3. rebuild CRM category mappings;
4. test classification and replies;
5. re-enable automatic behavior only when safe.

Reset instructions to role defaults

Use Reset to role default when you want to replace the current section with the selected role’s starting content. The replacement is shown in the form first; it is not final until you save.

Copy any custom wording you need to preserve before resetting. Then review tone, boundaries, escalation rules, and channel-specific behavior.

When someone else saved the instructions first

Two people editing one agent, or one person in two browser tabs, never overwrite each other’s instructions by accident. On a messaging agent’s AI Reply tab, when the instructions changed after you opened them — someone saved them, or a suggestion was applied or undone — Save Prompt does not replace that newer version. A note says These instructions changed while you were editing. Your text is still in the editor. instead, and nothing is lost:

• Show what changed compares the newer version with your text line by line.
• Reload latest replaces your text with the newer version. Copy anything you want to keep first.
• Save mine anyway saves your text over the newer version. The newer version stays in History, so you can bring it back.

A messaging agent’s instructions hold up to 40,000 characters. Instructions saved longer than that before the limit existed can still be shortened and saved.

Restore an earlier version of the instructions

Instructions change over time, and not always by hand: applying a different role replaces the current text with that role’s starting content. History keeps every saved version so you can read what an agent used to say, see exactly what changed, and bring back wording that worked better.

Where to find it:

1. Select History, then pick a version from the list on the left. Each entry shows when it was saved, and for agent instructions, how it was saved.
2. Read the full text on the right, or select Compare with current to see the differences line by line — removed lines in red, current lines in green.
3. Select Restore into editor to load that text back into the instructions field.
4. Review it, then save with the button that editor uses: Save Prompt for messaging and email replies, Save Classification Settings for email classification, Update Agent for a voice agent, Save for tool instructions.

Nothing changes until you save. The restored text is then saved as a new version, so the version you restored from stays in the list.

Good to know:

• How it was saved reads Edited when someone saved the text, Role applied when a role change replaced it, Suggestion you applied when someone applied a suggested instruction change from Conversation Quality, Improved automatically when the agent changed its instructions by itself, Change undone when someone undid one, Taken back automatically when Conversation Quality took back a change that made answers worse, and Taken back: tool turned off when it took back a change naming a tool you switched off. Voice agent instructions are always saved from the agent form, so voice versions read Edited even after a role change.
• Applying a role replaces changes applied from suggestions too, like any other wording. The version that had them stays in History.
• A save that takes out one or two of the changes Conversation Quality made or you applied — by deleting their lines, restoring an earlier version, or pressing Reset to role default and saving — counts like Undo: those changes are not made again. A larger rewrite is simply your new text, and the agent may learn those questions again; so may applying a role, which replaces the changes without saying no to them. See How your agent improves itself.
• History keeps the 50 most recent versions of each set of instructions. Saving the same text again does not add a version.
• Tool instructions are set per agent: you open a tool’s instructions from that agent’s tool list, and each agent keeps its own history for that tool. Open History from the window you are editing in and you will see that agent’s version list.
• Resetting tool instructions to the default does not erase their history. The versions stay in the list, so you can restore the wording you had and save it again.
• Tool instruction versions do not show a How it was saved badge: they are only ever saved by hand, so there is nothing to distinguish.
• Only the instruction text is versioned. Restoring an older email classification prompt does not bring back the classification categories that were in use at the time — check the category list after restoring.
• A voice agent you have not created yet has no History. Its first version is recorded when you create the agent.

Undo a change you applied from a suggestion

When an instruction change you applied from Conversation Quality turns out wrong, you can take back that one change and keep everything saved after it. Restoring an older version would also bring back the wording from before every later edit; undoing the change does not. For example, if you applied a suggestion last week and edited the delivery rules yesterday, undoing the suggestion keeps yesterday’s delivery rules.

1. On the messaging agent’s AI Reply tab, select History.
2. Pick the version marked Suggestion you applied, or Improved automatically for a change the agent made by itself. Under the badge, the entry shows the change’s title.
3. Select Undo this change, then Undo to confirm.

The line the change added is removed, a line it rewrote reads as it did before, and a line it removed comes back where it was. The instructions are saved at once as a new version marked Change undone.

If you edited the line the change touched since, or put a removed line back yourself, it can’t be undone this way: the message says so, and you can edit the line yourself in the instructions field. An undo that would leave the agent without instructions, or push them past 40,000 characters, is not made either. Undo this change is offered until the change is undone or you reword its line yourself, and only to people who can manage the agent. The same change can also be undone from Changes in Conversation Quality.

Unsaved edits in the instructions field stay there after an undo; saving them then shows the note described in When someone else saved the instructions first.

Write effective instructions

Instructions translate your service process into clear behavior: what the agent should achieve, what it must ask, what it may do, and when a person should take over.

Role defaults become more reliable when you add explicit business boundaries:

• what the agent is responsible for;
• what information it must confirm;
• actions it can take;
• situations that require a human;
• promises or topics it must avoid;
• the desired tone and response length.

Keep changeable facts in the Knowledge Base. Keep instructions focused on behavior and decision-making.

Related guides

• Voice Agents
• Email Agents
• Messaging Agents
• Knowledge Base