# 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

- The **`agents:voice:manage`** permission.
- A saved voice agent — see [Create a Voice Agent](/help/voice-agents/creating-campaigns).
  Scheduled prompts in particular need the agent to exist before you can add
  one.

## 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:

```mermaid
flowchart TB
    A["Platform rules<br/>(Karmaflow.ai, 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:

- **You do not have to re-state the basics.** Not inventing facts, not
  reading markup aloud, how to close a call cleanly, how to behave around a
  transfer — the platform layers cover that, on every voice agent, and they
  are enforced after your text, not before it.
- **You cannot instruct your way past them.** An instruction that contradicts
  a platform rule loses. Write what your business needs; leave the guardrails
  alone.

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](/help/voice-agents/transfers-and-escalation)).

Two shortcuts sit in the card header:

- **Support line example** and **Outbound follow-up example** load a
  complete, opinionated starting prompt, already personalised with your
  organisation name. It replaces what is in the field, so it asks first if you
  have typed something.
- **Build with AI** drafts one from a description of the job. Once the field
  has content the same button reads **Optimize with AI** and works on what is
  there instead of replacing it.

### Voice-specific advice

- **Short turns.** A caller cannot skim. Say one thing, then stop.
- **Say the number, don't spell the format.** Instruct it to read prices,
  dates and phone numbers the way a person would say them out loud.
- **Name the single next step** at the end of every branch — "I'll text you
  the link now" beats "let me know if you need anything else".
- **Do not write emotion markup into the instructions.** The platform rules
  forbid the agent emitting delivery tags mid-call, and they are stripped. Tone
  belongs in **Speaking style** on the Voice tab (for OpenAI and Gemini
  voices) or in the **Static Greeting**, which is the one place tags are
  authored deliberately.

## Placeholders that fill in at call time

Write `{{key}}` in your instructions or greeting and the agent gets its value
for this call. 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 |
| `{{current_time}}` | Today's date and time in your workspace time zone |
| `{{limited_time_prompts}}` | Whichever scheduled prompts are active right now |

Also available, depending on how the call started:

- **Outbound calls** carry the trigger's own fields — the form submission or
  journey context that caused the call — as placeholders under their own
  names.
- **Calls through a PBX** carry whatever you mapped on the **Phone System**
  tab, under the placeholder keys you chose there. See
  [Phone System Integration](/help/voice-agents/phone-system-integration).

**Where the value goes depends on the field.**

- **In the instructions**, a placeholder stays exactly as you wrote it. The
  values arrive in one short block at the end of the prompt, after the
  platform's rules, titled *Values for this call*, and the agent reads each
  `{{key}}` as the value given there. Your instructions are then the same
  text on every call, which lets the AI provider reuse them from its cache
  and answer sooner. `{{limited_time_prompts}}` is the one exception: it is
  replaced where you put it.
- **In the Static Greeting** (and the voicemail script), the value is
  replaced in place, because those lines are spoken word for word.

Names match exactly or ignoring case, so `{{First_Name}}` works too. A hyphen
is not read as an underscore: `{{first-name}}` is not filled, and the form
warns you under the instructions box.

**A placeholder nobody provides is left on the page as written.** If a caller
is unknown, `{{first_name}}` has no value: in the instructions the agent is
told it was not provided, and in the greeting it 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](/help/voice-agents/voices-and-speech).

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

- **The agent ignores something I wrote.** Check it does not contradict a
  platform rule (inventing facts, emitting markup, refusing to end a call);
  those win. Otherwise the usual cause is length — a rule buried in a
  2,000-word prompt competes with everything around it. Cut, or move it into
  the section the agent reads at decision time.
- **A scheduled prompt is "Active" but the agent never mentions it.** The
  `{{limited_time_prompts}}` placeholder is missing from the instructions, or
  the row's **Enabled** switch is off.
- **`{{first_name}}` comes out blank.** The caller was not resolved to a
  contact. That is correct behaviour, not a bug — the alternative is the agent
  guessing a name.
- **A placeholder appears literally in the transcript**, braces and all.
  Nothing provided that key on that call. Check the spelling against the
  mapping on the **Phone System** tab, or against the outbound trigger's field
  names.
- **Edits made no difference to a live call.** Instructions are saved to the
  draft. Use **Save & Push Live** — see
  [Testing, Drafts and Going Live](/help/voice-agents/testing-and-promotion).

## Next steps

- [Voices, Greetings and Pronunciation](/help/voice-agents/voices-and-speech)
- [Tools, Knowledge and Memory](/help/voice-agents/tools-and-knowledge)
- [Testing, Drafts and Going Live](/help/voice-agents/testing-and-promotion)
- [Tenant Brain](/help/knowledge/overview) — where facts belong instead of the
  prompt