Skip to main content
The Agent Handbook is a collection of ready-to-use prompt presets that improve how your agent communicates. Each preset encodes a specific best practice — toggle it on and the behavior is added automatically, no prompt writing needed.
New agents created in the dashboard have Conversational Tone and AI Disclosure When Asked enabled by default. Agents created directly through the API have no handbook presets enabled unless handbook_config is provided.

How It Works

The Agent Handbook organizes presets into three categories:
  • Personality & Tone — Shape how the agent sounds and feels in conversation
  • Accuracy & Format — Improve how the agent handles names, numbers, and data (voice agents only)
  • Trust & Safety — Control transparency and scope of responses
Toggle any preset on or off from the Agent Handbook panel. Each preset adds a small number of tokens to every interaction, shown as an estimate on the preset. Expand View prompt on any preset to read its wording, edit it, or reset it to the Retell default — see Customize a preset’s prompt. To open the handbook, select Agent Handbook in your agent editor. For a conversation flow, open Global settings → Agent settings first.
Conversation flow editor with Global settings selected, Agent settings expanded, and the Agent Handbook button highlighted below the model selector.

In a conversation flow, the Agent Handbook button sits below the model selector.

Full Personality & Tone panel with switches for Conversational Tone, Customer Support Tone, Natural Filler Words, and High Empathy, plus Cancel and Save buttons.

Conversational Tone and Customer Support Tone each have their own switch.

Presets

Personality & Tone

Conversational Tone and Customer Support Tone are independent toggles, not a single either/or choice. Turn on whichever fits your agent, or neither.
Available for: Voice and Chat agents | Default: Enabled for new dashboard-created agentsGives the agent casual, natural phrasing without robotic assistant language. It keeps turns short, asks one question at a time, avoids unnecessary repetition, and gives direct recommendations instead of answering with “it depends.” It also instructs the agent to express numbers and times in natural spoken form.When to use: Best for sales, front desk, scheduling, customer success, and other interactions where the agent should sound direct and natural. See Conversational Mode for side-by-side examples.Example: “Morning’s pretty open — nine or ten thirty. Afternoon works too if that’s easier.”
Available for: Voice and Chat agents | Default: DisabledGives the agent a clear and polite customer-support style. Responses follow an Acknowledgment → Statement → Next Step structure, limit filler acknowledgments, and avoid robotic phrases such as “Certainly!” or “Absolutely!”When to use: Best for support agents, troubleshooting, service requests, and other interactions where a courteous representative style is appropriate.Example: “Thanks for checking. Can you try that one more time?”
Available for: Voice agents only | Default: DisabledAdds occasional filler words like “um”, “uh”, and “you know” to make the agent sound more human and conversational. Fillers are used sparingly — roughly once every 2–3 sentences.When to use: Great for sales, customer success, or casual conversations. Avoid for formal or regulated contexts such as medical or legal interactions.Example: “So yeah, let me just pull that up for you real quick.”
Available for: Voice and Chat agents | Default: DisabledGuides the agent to use empathetic language when the situation calls for it — acknowledging concerns, making people feel heard, and reassuring them before moving to a solution.When to use: Useful for support agents, complaint handling, or any scenario where someone may be frustrated or emotional.Example: “I’m sorry you’re dealing with this. Let’s get it sorted.”

Accuracy & Format

All presets in this category are available for voice agents only. They are not applied to chat agents.
Default: DisabledThe agent repeats back critical details such as names, phone numbers, email addresses, addresses, dates, and IDs, then asks for confirmation before using them. Names and emails may be spelled out when their pronunciation is not sufficiently clear.When to use: Enable for appointment booking, data collection, or any workflow where accurate information capture is critical.Example: “To confirm, your phone number is four one five, five five five, zero one nine nine. Is that correct?”
Default: DisabledWhen spelling is needed, the agent uses the NATO phonetic alphabet — A as in Alfa, B as in Bravo, and so on — with pauses for clarity.When to use: Useful for confirming email addresses, reference numbers, account IDs, or names over the phone.Example: “That’s B as in Bravo, seven, K as in Kilo, two — correct?”
Default: DisabledFormats numbers, dates, money, phone numbers, addresses, codes, IDs, names, and email addresses into natural spoken form. For example, “$758.08” becomes “seven hundred fifty-eight dollars and eight cents,” and phone numbers are read digit by digit in groups.When to use: Enable when your agent frequently reads structured data such as prices, dates, contact information, addresses, or account identifiers.Example: “Your total is seventy dollars and eighty-four cents.”
Default: DisabledHandles common speech-recognition variations of names gracefully. If someone confirms their name but the transcription is slightly different — for example, “Brandon” versus “Brendon” — the agent can treat it as a match and continue naturally.When to use: Enable when your agent looks up names in a database or CRM and needs tolerance for transcription variations.Example: The agent asks “Are you Brandon?” and the caller says “Yes, this is Brendon” — the agent continues without flagging the difference.

Trust & Safety

Available for: Voice and Chat agents | Default: Enabled for new dashboard-created agentsWhen someone asks whether they’re speaking to a human or an AI, the agent clearly acknowledges that it’s a virtual assistant.When to use: Recommended for transparency and compliance. Only disable it if your use case has a specific reason to use different disclosure instructions.Example: “Yes — I’m an AI assistant here to help.”
Available for: Voice and Chat agents | Default: DisabledRestricts the agent to answering questions using information available in its prompt or knowledge base. If it doesn’t know, it says so instead of guessing.When to use: Enable for any agent where factual accuracy is critical, such as healthcare, finance, or legal use cases.Example: “I don’t have that information, but I can connect you to someone who can help.”

Customize a preset’s prompt

Every preset ships with a Retell-written prompt, and you can replace it with your own wording from the dashboard. Expand View prompt on any enabled preset to see its text, edit it in place, and save with the panel’s Save button. A Customized tag marks each preset you’ve edited, and the count of customized presets appears next to the Agent Handbook button.
  • A custom prompt can be up to 10,000 characters. The character count shows under the text box, and Save is blocked until you’re within the limit.
  • Select Reset to default to drop your wording and go back to the Retell default text.
  • A preset must be on before you can edit its prompt. Turning a preset off keeps your saved wording for the next time you turn it on.
Custom prompts replace only that preset’s text — they don’t change which presets are on. For instructions unrelated to a preset, write them directly in your agent’s prompt (see the general prompting principles).

Token Cost Summary

Token counts are approximate. The token cost of all enabled presets is added to every interaction. Agents created directly through the API have no default handbook configuration.

FAQ

Yes, from the dashboard or the API. In the Agent Handbook panel, expand View prompt on a preset to edit its wording — see Customize a preset’s prompt.Through the API, set a custom_prompt on any preset inside an agent’s handbook_config to replace its built-in text with your own, up to 10,000 characters:
Setting custom_prompt both enables the preset and uses your wording. Omit it or pass null to use the Retell-provided prompt. An empty string enables the handbook but intentionally injects no prompt text.You can retrieve the Retell-provided prompts through the handbook presets API to use as a starting point. For instructions unrelated to a preset, write them directly in your agent’s prompt. See the general prompting principles.
Yes. Conversational Tone and Customer Support Tone are independent, as are all other handbook presets. You can enable either one, both, or neither.Because both presets affect the agent’s speaking style, review their prompts before combining them and customize any overlapping instructions if necessary.
Handbook presets work alongside your custom prompt. If your prompt gives instructions that overlap with a preset — for example, your own empathy guidelines — you may want to disable or customize the overlapping preset to avoid inconsistent behavior.
Five presets — Natural Filler Words, Echo Verification, NATO Phonetic Alphabet, Speech Normalization, and Smart Matching — are designed specifically for voice interactions and are not applied to chat agents.