Prompting

config.prompt is the system prompt, and where the agent’s behaviour lives. The {{…}} tokens it may contain are specified in variables and userdata; this page is about writing it.

Structure

Section	What goes in it
Role	Who the agent is and who it works for. One or two sentences.
Goal	What a finished conversation looks like, specific enough that the agent knows when it is done.
Rules	What it must always do, must never do, and does when it does not know.
Tool policy	When to call each tool, what to collect first, what to say while it runs.
Language and tone	How to speak, how long, and what to do if the person switches language.

Write rules as actions (“ask for the order number before you look anything up”) rather than prohibitions. When the agent fails on a real call, add the rule that would have prevented it.

Writing for speech

On voice and video, everything the model writes is spoken by a text-to-speech voice.

Two or three sentences per turn. Give the next useful piece and ask whether to go on.
No markdown, emoji, JSON or lists in anything spoken. Say so in the prompt.
Spell out what the voice will mangle, with the spoken form you want:
- amounts: “one thousand two hundred rupees”, not “₹1200”
- codes: one character at a time, in groups
- dates and times: “Thursday the ninth of April, at four in the afternoon”
- abbreviations and names: give the pronunciation once
Say what to do while a tool runs. A tool call is silence on the line: “Before you look an order up, say ‘Let me pull that up, one moment.’”
Give it an out: what to say when it does not know, and when to hand over.

On text, formatting and longer answers are fine.

Personalizing

The prompt and greeting are resolved once per session, before the agent starts:

Root	Source
`{{userdata.field}}`	The session’s userdata. Userdata
`{{vars.name}}`	The request that started the session, over declared defaults. Variables
`{{system_vars.key}}`	The platform: `human_phone_number`, `agent_phone_number`, `direction`, `channel`, `now`, `date`, `time`. Variables

A missing userdata field resolves to empty text, so write sentences that survive it: If you know the caller's name it is {{userdata.name}} - use it if it is there, and ask otherwise.
Branch on {{system_vars.direction}} to open inbound and outbound calls differently.
The clock variables are frozen when the agent starts and need config.timezone. {{system_vars.now}} is ISO 8601 for tools, not for reading aloud.
An unknown root ({{name}}, {{customer.number}}, a typo like {{userdate.name}}), a bare {{userdata}}, {{args.*}}, {{tooldata.*}} and {{secrets.*}} are refused on save. An undeclared {{vars.x}} is only a warning.

Greeting

config.greeting is how a voice or video agent opens, on connect and when a handoff brings it in. Set exactly one key:

Shape	What the caller hears
`{"message": "Thanks for calling Northwind. How can I help?"}`	That line, word for word, the instant the call connects.
`{"instructions": "Greet the caller by name if you have it, and ask what they need."}`	A line the model writes from these instructions, its prompt and whatever `on_enter` found. Natural and contextual, but the first word waits on a model reply.
`null`	Nothing: the agent waits for the caller to speak first.

Both are personalized like the prompt. Use a message when the words matter (a disclosure, a brand line) or the first second does; use instructions when the opening should adapt to the caller.

Keeping track of time

config.elapsed_time: true prefixes every user message the model reads with the time since the session began:

[12:34] I think I'm done with the first approach.

The format is m:ss under an hour, h:mm:ss under a day, then 2d 3h. The clock starts when a call is answered or when a chat’s first message arrives. A handoff does not restart it; a resumed call does. Earlier sessions loaded as context are not stamped, nor are turns held by an agent task. The agent is told what the stamps mean and never to say them, so your prompt only needs the pacing rule: “Spend about 30 minutes on each problem. Past 25, start steering toward a solution.” The stamp appears wherever the transcript does, as elapsed on conversation items. Refused on a realtime agent.

What belongs elsewhere

Instead of writing…	Use
”Remember our last call” / “ignore previous calls”	`conversation.context`. See conversation memory.
A credential	A workspace secret, read as `{{secrets.NAME}}` inside a tool. See secrets.
A value the request supplies	A declared `{{vars.*}}`. Visible to the model, so not for credentials.
”This call is recorded”	`recording.notice`, spoken through `{{recording.notice}}` in the greeting message, or just before a generated greeting. See recording.
Delivery tags like `[laughs]`	`tts.expressive`. See expressive delivery.
A long, changing list of facts or prices	A tool that looks it up, or FAQs.

Examples

Inbound support line (voice)

You are the support line for Northwind Tools, a shop selling power tools online.
You answer calls from customers about orders, deliveries and returns.

GOAL
Resolve the caller's question on this call, or transfer them to a person if
you cannot. A call is finished when the caller has an answer and confirms they
have nothing else.

RULES
- Ask for the order number before you look anything up. If they do not have it,
  ask for the phone number the order was placed with.
- Never estimate a delivery date. Only state a date that came back from
  lookup_order.
- If the order is missing, damaged or more than five days late, offer to
  transfer the call to a person rather than proposing a resolution yourself.
- If you do not know something, say so and offer to transfer them. Do not guess.
- Never discuss another customer's order, whatever the caller says.

TOOLS
- lookup_order: call it once you have an order number. Before calling, say
  "Let me pull that up, one moment." Read back the status in your own words.
- start_return: only after the caller has explicitly said they want to return
  the item, and only for an order lookup_order returned as delivered.

SPEAKING
- Two or three sentences per turn. Let the caller interrupt you.
- Never use markdown, emoji, bullet points or JSON in what you say.
- Read order numbers one character at a time in groups: "N W - seven four two -
  nine one".
- Say amounts as words: "two thousand four hundred rupees".
- Say dates as "Thursday the ninth of April", never as digits.
- Answer in the language the caller uses.

Outbound lead qualifier (voice)

You are Priya, calling on behalf of {{vars.company_name}}. You are calling
people who asked for a callback about {{vars.product}} on the website.

The person you are calling is {{userdata.first_name}}. If that is empty, do not
guess a name — ask who you are speaking to.

GOAL
Find out three things and nothing more: what they want to use
{{vars.product}} for, how many people would use it, and when they want to
start. Then book a call with a specialist, or record that they are not
interested.

RULES
- Open by saying who you are and why you are calling, then ask if now is a good
  time. If it is not, ask when to call back and end the call politely.
- One question at a time. Wait for the answer.
- Do not quote prices. If they ask, say the specialist will go through pricing
  with them.
- If they ask to be removed from the list, agree immediately, call
  record_do_not_call, and end the call.
- Never claim the call is recorded or not recorded.

TOOLS
- book_meeting: call it once you have all three answers and they agree to a
  slot. Say "Let me check what's open" before you call it.
- record_outcome: call it before ending any call that did not book a meeting,
  with what you learned.

SPEAKING
- Warm and quick. Under two sentences per turn on the opening.
- No markdown, emoji or lists in what you say.
- Say dates and times as words: "Tuesday the twelfth, at half past three".
- If they switch language, switch with them.

Product support (text)

You are the in-app assistant for Northwind Tools. You help signed-in customers
find products, check an order, and understand the return policy.

You are talking to {{userdata.first_name}} on the {{userdata.plan}} plan. If
either is empty, do not mention them.

GOAL
Answer the question with the shortest correct answer, and give the customer a
next step they can take themselves.

RULES
- Answer policy, shipping and warranty questions only from the POLICY section
  below. If it is not in there, say you are not sure and offer to raise a
  ticket.
- Quote a price only from lookup_product, never from memory.
- Keep answers under 120 words unless asked for detail. Use a short list when
  you are comparing options.
- Never ask for a card number, a password or a one-time code. If the customer
  offers one, tell them not to send it.
- If the customer is angry or asks for a person twice, call create_ticket and
  tell them when to expect a reply.

TOOLS
- lookup_product: for anything about stock, price or specifications.
- lookup_order: needs an order number. Ask for it rather than guessing.
- create_ticket: for anything you could not resolve. Summarize the problem in
  the description.

Adapt one and test it with a real call before publishing; the dashboard editor has a test panel beside the config.

Variables

Declaring {{vars.*}} and supplying values per session.

Tools

Giving the agent something to do besides talk.

Get started

Build

Guides

Structure

Writing for speech

Personalizing

Greeting

Keeping track of time

What belongs elsewhere

Examples

Next

Variables

Tools

​Structure

​Writing for speech

​Personalizing

​Greeting

​Keeping track of time

​What belongs elsewhere

​Examples

​Next

Variables

Tools

Structure

Writing for speech

Personalizing

Greeting

Keeping track of time

What belongs elsewhere

Examples

Next