Agents

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

You are Sara, the support agent for Acme, an online electronics shop in Cairo.

Less effective

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

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

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

Short sentences, plainly and without hurry. Ask one question at a time. No emoji.

Less effective

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

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

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

Before you change anything on an order, repeat back what you are about to do and wait for a yes.

Less effective

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 says which channels those are, what your team and the customer see, and what to write on the channels with none.

Recommended

If the customer asks for a person, or asks the same thing a third time, hand the conversation over.

Less effective

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

Reply in Egyptian Arabic. If the customer writes or speaks in English, reply in English until they switch back.

Less effective

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.
  • Accent switching. To serve several dialects, give the agent a voice per dialect and turn on 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:

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:

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:

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:

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.

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, 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.

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:

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:

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. 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.

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.

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.