Instructions, Goals and Scheduled Prompts

The Agent Instructions field is the agent. Everything else on the form — voice, timing, tools — decides how it sounds and what it can reach; the instructions decide what it does. This article covers what goes in that field, the placeholders that fill themselves in at call time, what Goals is actually for, and how to schedule text that applies only for a week.

Everything here is on the Setup tab (Instructions & Greeting), the Schedule tab, and the Tools tab's Optional Prompt Components card.

What you'll need

Your instructions are not the whole prompt

What the model receives on a call is assembled in a fixed order, and your field is one layer of it:

flowchart TB
    A["Platform rules<br/>(KarmaFlow, every voice agent)"] --> B["Your workspace's<br/>prompt components"]
    B --> C["<b>Agent Instructions</b><br/>(this field)"]
    C --> D["Workspace append components<br/>+ transfer cascade + knowledge rules"]
    D --> E["Final platform gate<br/>(checked last, every turn)"]

Two consequences worth knowing before you write:

Your workspace's own components — shared text you want on several agents rather than copy-pasted into each — are created by a tenant admin at Settings (the gear icon) → Agents & AI → Prompt Components, and switched on per agent under Tools → Optional Prompt Components. System components are always included and are not listed there.

Write the instructions

  1. Open the agent and stay on the Setup tab.
  2. In Instructions & Greeting, type into Agent Instructions. The field counts characters and gives a rough token estimate underneath — useful, because a long prompt costs time before the first word is spoken.
  3. Cover, roughly in this order:
    • Who the agent is — name, the business it represents, its role.
    • Why this call is happening — and, for outbound, that the caller did not ask for it.
    • What it should do first, and what a finished call looks like.
    • Facts it needs that are not in your knowledge base — hours, pricing bands, service area, policies.
    • Boundaries — what it must not promise, quote, or discuss, and what should go to a human instead.
    • When to transfer, in the same words you used for your forwarding conditions (see Transfers, Forwarding and the Duty Roster).

Two shortcuts sit in the card header:

Voice-specific advice

Placeholders that fill in at call time

Write {{key}} anywhere in your instructions or greeting and it is replaced before the call starts. Always available:

Placeholder Filled with
{{first_name}} The resolved contact's first name — empty if the caller is unknown
{{last_name}} The resolved contact's last name
{{caller_number}} The number at the other end of the call

Also available, depending on how the call started:

The Available Replacement Variables box under the field lists four more that the platform fills:

Placeholder Filled with
{{call_transcript}} The full phone-call transcript
{{chat_transcript}} A complete chat session history
{{orchestration_id}} The orchestration or campaign id behind the call
{{limited_time_prompts}} Whichever scheduled prompts are active right now

A placeholder nobody provides is left on the page as written. If a caller is unknown, {{first_name}} resolves to an empty string — so write Hi {{first_name}} and an unknown caller hears "Hi". Guard it in the instructions ("if you do not have their name, do not guess it") rather than relying on the greeting.

Goals

Goals sits directly under the instructions and does something different from everything around it: it is not sent to the model. It is the list the performance dashboard scores completed calls against, which is where goal-attainment numbers on the agent's performance page come from.

Write one outcome per line, each one observable in a transcript:

Book a demo call
Collect the caller's email
Resolve without escalation

If you also want the agent to pursue a goal, say so in the instructions as well. Putting it only in Goals measures without asking.

The Static Greeting

Static Greeting is spoken verbatim as the agent's first turn — no paraphrase, no variation. It only plays when Who Speaks First? (Voice tab → Conversation Behavior) is set to AI Initiates; the default is User Initiates, which waits for the caller to speak. Full detail in Voices, Greetings and Pronunciation.

Scheduled prompts (the Schedule tab)

Use a scheduled prompt for anything with an end date: a promotion, a holiday closure, a product recall script, "we are moving offices on the 14th". It saves you editing the main instructions twice and remembering to undo it.

How it works: the text is injected at {{limited_time_prompts}} while its window is open, and when nothing is active the placeholder is removed entirely.

  1. Put {{limited_time_prompts}} somewhere in Agent Instructions — ideally where a temporary note makes sense in context. Nothing on this tab reaches the model until you do, and the tab shows an amber warning while the placeholder is missing. Copy placeholder puts it on your clipboard.
  2. Open the Schedule tab and click Add.
  3. Fill in the dialog:
    • Name (optional) — how the row is labelled, e.g. "Memorial Day weekend special".
    • Content (required) — the text to inject. Character and token counts are shown.
    • Start (required) and End. Tick No end (open-ended) to leave it running until you disable it.
    • Enabled — a disabled row never injects, whatever its dates say.
  4. Save. The row appears under Active, Scheduled or Past depending on its window, with the counts in the tab labels.

Times are shown and stored in your workspace's timezone, and the row tells you how long until it starts or ends.

Several prompts can be active at once, and they all inject. Keep them short and non-contradictory — two active prompts arguing about the same policy is the failure mode here.

Troubleshooting

Next steps