> For the full page index, fetch https://echonova.ai/llms.txt # How the prompt is assembled What the model actually receives at the start of a conversation, which parts you write, which parts the platform appends, and how to write a prompt that survives both. The **Personality** box on the **Persona** tab is the prompt. Every wording rule an agent follows comes from it: its identity, its scope, its tone, what it refuses, and when it hands over. This page shows what the agent receives at the start of a conversation, what is added on text channels, and how to write the part you own so that it holds up on a live call. ## What the agent reads Your **Personality** text is sent word for word. On a voice conversation it is the whole prompt: no preamble, no house rules, no list of the agent's tools or documents is added to it. If an agent behaves in a way you did not ask for on a voice call, the wording that caused it is in your box. Three things travel beside the prompt rather than inside it: | What | How it reaches the agent | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The greeting | Spoken first, from **Greeting message**. It is not part of the prompt, so an instruction written in the greeting does not steer the rest of the conversation | | Knowledge | A list of sources the agent may search, not text pasted into the prompt. Pasting a paragraph from a document into **Personality** does not improve retrieval; it just costs you prompt characters on every turn | | Tools | Each tool carries its own **Description**, which is what the model reads when it decides whether to call it. A built-in tool with no description of its own uses the workspace default. The sentence that makes a tool fire belongs on the tool | ## Give the agent one identity The caller hears the name written in the prompt, so write it there. Say who the agent is, who it works for, and what it is. An identity the model has to invent changes between calls. **Recommended** ```text You are Sara, the support agent for Acme, an online electronics shop in Cairo. ``` **Less effective** ```text You are a helpful assistant for our company. ``` ## Draw the scope, and say what is outside it An agent with no stated scope answers everything, including questions you would rather it passed on. Name the jobs it does, then name the ones it does not and what to do instead. **Recommended** ```text You answer questions about orders, deliveries, returns and account access. Corporate sales, partnerships and press are out of scope: say so and offer to pass the request on. ``` **Less effective** ```text Help the customer with anything they need. ``` ## Say how the agent should speak Length, formality and question count are the levers callers actually notice. A voice call punishes long answers more than a chat does, so say it explicitly. **Recommended** ```text Short sentences, plainly and without hurry. Ask one question at a time. No emoji. ``` **Less effective** ```text Be friendly, professional and engaging. ``` ## Tell it what to do when it does not know Retrieval returning nothing does not stop a model answering. Name the fallback and the agent stops filling gaps on its own. **Recommended** ```text Never invent an order number, a date, a price or a policy. If you do not have it, say you do not have it and offer the next step. ``` **Less effective** ```text Only give accurate information. ``` ## Make it confirm before it acts An agent with tools can change something in your systems. A confirmation line is the difference between a wrong booking and a wrong sentence. **Recommended** ```text Before you change anything on an order, repeat back what you are about to do and wait for a yes. ``` **Less effective** ```text Use the tools when needed. ``` ## Say when to hand over Handing over is a wording decision. Name the triggers, and on the channels that support a handoff the rest happens for you. [Human handoff](/docs/agents/human-handoff) says which channels those are, what your team and the customer see, and what to write on the channels with none. **Recommended** ```text If the customer asks for a person, or asks the same thing a third time, hand the conversation over. ``` **Less effective** ```text Escalate difficult cases. ``` ## Set the language rule yourself The voice fixes the accent and the prompt fixes the words. They are set in two different places and they can disagree: a Fusha prompt read by an Egyptian voice still sounds like Fusha. Each voice in the library carries one dialect, shown on the voice card, such as Egyptian, Emirati, Saudi, Fusha or English. The list of dialects is loaded from the speech catalogue, so it can grow. Pick the voice for the accent, then write the language rule into the prompt, including what to do when the caller switches language mid-call. **Recommended** ```text Reply in Egyptian Arabic. If the customer writes or speaks in English, reply in English until they switch back. ``` **Less effective** ```text Speak Arabic. ``` Two things that do not belong in the prompt: - **Diacritization.** It is a switch on a Fusha voice, not an instruction. Asking the model to add diacritics spends tokens and changes nothing. See [Voices and language](/docs/agents/voice-and-language). - **Accent switching.** To serve several dialects, give the agent a voice per dialect and turn on [dialect detection](/docs/agents/system-tool-dialect-detection). Both the prompt box and the greeting box accept Arabic and lay it out right to left as you type. ## What is added on text channels On a text conversation, up to three blocks are added after your text, each separated from it by a blank line. Voice conversations get none of them. ### The channel note A Zendesk, Zoho Desk or Intercom conversation gets this note: ```text You are answering a customer support ticket (email-like, formal tone, no emoji). If you cannot help, the customer explicitly asks for a human, or they are getting frustrated, end your reply with the exact marker [[HANDOFF]] on its own line. ``` A Genesys chat conversation gets this one: ```text You are chatting with a customer in a live support conversation. Keep replies short and conversational. If you cannot help, or the customer asks for a human, end your reply with the exact marker [[HANDOFF]] on its own line. ``` Both name the same marker, `[[HANDOFF]]`. A reply that contains it is treated as a request to hand the conversation to a person: every occurrence of the marker is stripped and only the remaining text is sent, so the customer never sees it and it is not kept on the stored message. A reply that is nothing but the marker sends no message at all. Write your prompt so that it agrees with the note. A prompt that says the agent must always answer, or must never end a conversation, stops the handoff firing on these channels. ### The ticket subject On a helpdesk conversation whose ticket has a subject, one more line is added: ```text Ticket subject: Order 41822 never arrived ``` It is added to the instructions rather than to the message, so the agent treats it as context and not as something the customer just said. ### The conversation replay The prompt is sent once, at the start of a conversation. When a text conversation has to start again, the recent history is replayed into the prompt so the agent does not begin from nothing: ```text Conversation so far: Customer: where is my order You: Can you give me the order number? Customer: 41822 ``` The replay holds the last 20 turns, labelled `Customer:` for the contact and `You:` for the agent. The message the agent is about to answer is not replayed, so it never sees the same question twice. > [!NOTE] > If a text turn fails outright, the customer receives the fixed line > "Sorry, I can't respond right now. Please try again shortly." Nothing you > write in the prompt changes that text. ## What to leave out - **Secrets.** Keys, passwords, connection strings and personal records. - **Reference content.** Price lists, policies and catalogues belong in [knowledge](/docs/agents/knowledge-overview), where they are pulled in when they match the question instead of being read on every turn. - **Channel-by-channel instructions.** One agent serves every channel it is connected to, and they all get the same prompt. - **Anything over the limit.** The box stops at 8000 characters, and every character is read on every turn of every conversation. > [!WARNING] > Never put credentials or customer records in the **Personality** box. The > prompt text is sent to the agent at the start of every conversation, and for a > voice call it is kept with that conversation's record. Put credentials in > [Secrets](/docs/agents/secrets), and data the agent needs during a call behind > a [tool](/docs/agents/tools-overview). ## Worked example When you create an agent from a template or from scratch, the portal composes a starter prompt. With the name Acme Support and the customer service capability, it is exactly this: ```text You are Acme Support, a voice agent who speaks with people over the phone. You handle customer service: questions about orders, accounts and policies. Speak in short sentences, plainly and without hurry. Ask one question at a time, and confirm anything you are about to act on. Never invent a fact, a number or a policy. When you do not know, say so and offer the next step. ``` It is a usable shape and a thin brief: it never names the business, never says what is out of scope, and never says what happens when the caller wants a person. The rewrite applies every principle above: ```text You are Sara, the support agent for Acme, an online electronics shop in Cairo. Scope You answer questions about orders, deliveries, returns and account access. Anything about corporate sales, partnerships or press is out of scope: say so and offer to pass it on. How to speak Reply in Egyptian Arabic unless the customer writes in English, then reply in English. Short sentences. One question at a time. No emoji. Rules Never invent an order number, a date, a price or a policy. If you do not have it, say you do not have it. Before you change anything on an order, repeat back what you are about to do and wait for a yes. If the customer asks for a person, or asks the same thing a third time, hand the conversation over. ``` | What changed | What it buys | | ------------------------------------------- | --------------------------------------------------------------------- | | A name and an employer | The caller hears a real identity, and the model stops improvising one | | An explicit scope with an out of scope rule | Questions outside the job get a clean answer instead of a guess | | A language rule | The reply language stops depending on the caller's first word | | A confirmation rule | Tool calls become reviewable by the caller before they happen | | A handoff rule | The `[[HANDOFF]]` marker fires on the channels that support it | ## Checklist before you save - The agent's name is written in the prompt, not only in the **Name** field. - The business and the scope are named, and there is a rule for questions outside it. - There is a sentence about length and about asking one question at a time. - There is a rule for what to do when the agent does not know. - Every tool the agent can call has a confirmation rule, if it changes anything. - There is a handoff trigger, and it does not contradict the channel note. - The reply language is stated, including what to do when the caller switches. - No credentials, no customer records, no price lists. - The text is under 8000 characters, and every line still earns its place. ## When a change takes effect A saved prompt is used by the next conversation. A conversation already running keeps the wording it started with: a voice call until the caller hangs up, and a text conversation until it starts again. To test a change, save it, then start a new conversation from [the playground](/docs/agents/test-your-agent). Re-asking inside a conversation that is already open will not pick it up. ## FAQ ### Does the agent see its documents or its tools in the prompt? No. Knowledge is searched during the conversation, and each tool carries its own description. Neither is pasted into your text. ### Can I write a different prompt per channel? No. One agent has one prompt, and every channel it is connected to gets it. Run a second agent if a channel needs different wording. ### Where do I put the handoff instruction? In the prompt, as a trigger: when to hand over. On helpdesk and Genesys channels the `[[HANDOFF]]` marker is added to the prompt for you, and the marker is stripped from what the customer sees. See [Human handoff](/docs/agents/human-handoff). ### Does a longer prompt cost more? Yes. The prompt is read on every turn of every conversation, so its characters are part of what each turn costs. See [What a turn costs](/docs/agents/what-a-turn-costs). ### Why does the agent still answer questions I told it to refuse? The wording is the only rule there is, so make it specific: name the topic, name the refusal sentence, and name what to offer instead. Then test it in the playground. ### Should reference material go in the prompt or in knowledge? Knowledge, for anything longer than a couple of lines or anything that changes. Keep the prompt for rules that are true on every turn. ## Related - [Write the persona](/docs/agents/persona): the box this page is about - [Choose a model and reasoning effort](/docs/agents/model-and-reasoning): what reads your prompt - [Voices and language](/docs/agents/voice-and-language): the accent behind the words - [How knowledge works](/docs/agents/knowledge-overview): where reference material belongs - [Human handoff](/docs/agents/human-handoff): what the handover trigger does on each channel - [Channels overview](/docs/agents/channels-overview): the channels one prompt serves - [Tools overview](/docs/agents/tools-overview): where a tool's own wording lives - [End conversation](/docs/agents/system-tool-end-conversation): letting the agent close a call