Instructions

In Leilani, the Instructions field defines how an agent should behave on a call. It shapes the agent's role, tone, language, tool usage, escalation behavior, and overall callflow.

Strong instructions are short, explicit, and operational. Weak instructions are vague, contradictory, or too broad to guide real-time behavior reliably.

Core principles

• prefer short bullets over long paragraphs
• define the agent's job clearly
• state rules directly rather than implying them
• include example phrases where wording matters
• keep tool guidance and instructions aligned
• use a callflow when the conversation should follow a clear sequence
• revise instructions based on observed failure modes, not theory alone

Recommended structure

You do not need every section below, but most production agents benefit from a structure like this:

# Role & Objective
# Personality & Tone
# Language
# Tools
# Instructions / Rules
# Callflow
# Safety & Escalation

Each section should answer one question:

• Role & Objective: who the agent is and what success looks like
• Personality & Tone: how the agent should sound
• Language: what language or languages the agent should use
• Tools: when to use functions, and when not to
• Instructions / Rules: non-negotiable behavior rules
• Callflow: the sequence of the conversation
• Safety & Escalation: when to stop, hand off, or avoid unsupported behavior

Role and objective

This is the anchor for the rest of the prompt. If the role is vague, the rest of the behavior will usually drift.

Good role statements define:

• the type of agent
• the audience it serves
• the job it is responsible for
• the definition of success

Example:

# Role & Objective
- You are the voice assistant for Acme Co.
- Your job is to answer common questions, collect required details, and route callers to the right next step.
- Keep calls efficient, accurate, and easy for the caller to follow.
- Success means the caller leaves the interaction with a clear answer, confirmed action, or appropriate handoff.

Personality and tone

Voice agents should sound deliberate, not theatrical. Keep the tone clear enough to be heard once and understood once.

Useful tone guidance usually covers:

• warmth level
• brevity
• confidence
• formality
• whether the agent should sound conversational or procedural

Example:

# Personality & Tone
- Sound calm, capable, and direct.
- Be warm without sounding overly casual.
- Keep responses concise.
- Avoid filler, repetition, and exaggerated enthusiasm.
- Do not use marketing language on live calls.

Language control

If language handling matters, specify it. Do not assume the agent will consistently infer the correct behavior from context alone.

Use explicit language rules when you need to:

• keep the call in one language
• support multiple languages with clear switching behavior
• separate spoken conversation from internal explanations or confirmations

Example: single-language support

# Language
- Conduct the conversation in English.
- Do not switch languages unless the callflow explicitly allows it.
- If the caller speaks another language, explain that support is currently limited to English.

Example: bilingual behavior

# Language
- Use English by default.
- If the caller clearly prefers Spanish, continue in Spanish for the rest of the call.
- Do not switch back and forth unless the caller asks.

Reducing repetition

Real-time agents can sound robotic when they reuse the same opener, filler phrase, or confirmation pattern over and over.

If that happens, add explicit variety rules:

# Personality & Tone
- Do not repeat the same sentence twice unless the caller asked for repetition.
- Vary short acknowledgements and confirmations.
- Keep required compliance language exact, but vary non-essential phrasing.

This is especially useful for:

• appointment booking
• support triage
• reception and routing
• agents that handle many short, similar calls

Readback, numbers, and pronunciation

Some information should be spoken naturally. Other information should be read back carefully, one character or digit at a time.

Use explicit rules for:

• phone numbers
• verification codes
• account numbers
• order IDs
• street numbers and unit numbers
• names or terms that are commonly mispronounced

Example:

# Instructions / Rules
- When confirming phone numbers, codes, or account identifiers, read each digit separately.
- After a caller corrects a number, confirm it again before proceeding.
- For critical identifiers, do not paraphrase or summarize.

# Reference Pronunciations
- Pronounce "SIP" as "sip".
- Pronounce "VoIP" as "voyp".
- Pronounce "Leilani" as "lay-LAH-nee".

If a value is operationally important, design the instruction for accuracy first and style second.

Unclear audio, silence, and background noise

An agent should not pretend to understand audio it did not actually understand.

Add explicit handling for:

• silence
• partial audio
• background noise
• overlapping speech
• coughs, bumps, or other non-speech sounds

Example:

# Instructions / Rules
- Only respond to clear speech.
- If the caller is inaudible, interrupted, or unclear, ask for clarification instead of guessing.
- If there is silence, wait briefly and then prompt the caller again.
- Do not invent meaning from background noise or partial words.

You can also suppress non-verbal output explicitly:

# Instructions / Rules
- Do not hum, sing, imitate sounds, or produce sound effects.
- Do not include onomatopoeia in spoken responses.

Tool usage in Leilani

If your agent uses functions, the instructions should explain:

• when a function should be called
• when it should not be called
• whether the agent should speak before calling it
• whether confirmation is required first
• how to handle failures or ambiguous inputs

If tools and prompt text disagree, the agent will behave inconsistently.

Tool selection

Define usage rules per function whenever the distinction matters.

Example:

# Tools
## lookup_account(email_or_phone)
Use when: identifying a caller or retrieving account context.
Do not use when: the caller is only asking a general question.

## check_outage(address)
Use when: the caller reports service disruption or degraded quality.
Do not use when: the issue is purely billing or account access.

## transfer_call(queue)
Use when: the call should move to a human team or specialized queue.
Do not use when: the current agent can resolve the request directly.

Tool call preambles

For read-only lookups or background checks, a short preamble often improves the caller experience.

Example:

# Tools
- Before any lookup tool call, say one short line such as "One moment while I check that."
- Keep tool preambles brief and neutral.
- Do not stack multiple preambles in a row.

Confirmation behavior

Not every function should be handled the same way.

A useful pattern is:

• read or lookup tools: proactive
• state-changing tools: confirmation first

Example:

# Tools
- Lookup tools may be called without asking for permission first.
- Actions that change state, send messages, create records, or transfer a call require confirmation unless the callflow says otherwise.

Tool output handling

If a function returns important text, rules, links, or IDs, say so explicitly in the instructions.

Example:

# Tools
- If a function returns caller-facing text marked as final, read it accurately and do not paraphrase it.
- If a function returns structured data, summarize it for speech unless exact wording is required.
- If a function fails, explain the issue clearly and move to the next valid step in the callflow.

Callflow design

Use a callflow when you want the conversation to move through clear stages. This is especially useful for:

• front desk and reception agents
• support triage
• scheduling
• intake and qualification
• identity verification

A good callflow defines:

• the goal of the stage
• what the agent should do in that stage
• what condition must be met before moving on

Example:

# Callflow
## 1. Greeting
Goal: open the call and learn why the caller reached out.
Instructions:
- greet the caller briefly
- identify the business
- ask one direct question about how you can help
Exit when: the caller states their reason for calling

## 2. Discovery
Goal: classify the request.
Instructions:
- determine whether the call is informational, operational, support-related, or requires transfer
- gather only the minimum information needed to proceed
Exit when: the request type and required next step are clear

## 3. Resolve or Route
Goal: complete the task or move the call to the correct destination.
Instructions:
- answer the question, run the needed function, or transfer the call
- confirm the result before closing
Exit when: the caller has a clear answer, confirmed action, or handoff

Use concrete exit criteria. If the prompt says "move on when it feels right," the agent will improvise inconsistently.

Safety and escalation

Every production agent should have explicit escalation rules.

At a minimum, define what to do when:

• the caller asks for a human
• the agent lacks the information required to proceed
• the request falls outside the agent's scope
• the caller is frustrated or distressed
• a policy or compliance boundary applies

Example:

# Safety & Escalation
- If the caller asks for a human, begin the transfer process immediately.
- If the request requires judgment, exception handling, or unsupported actions, escalate rather than improvise.
- If identity verification fails after the allowed attempts, stop the protected workflow and offer the approved fallback.
- Do not claim actions were completed unless the relevant function succeeded.

Common failure modes

If an agent is underperforming, the issue is often traceable to one of these instruction problems:

• the role is too vague
• multiple rules conflict with each other
• the callflow has no exit criteria
• the tool instructions are underspecified
• tone guidance is stronger than operational guidance
• the prompt asks for brevity but also asks for too many behaviors in one turn

A few practical fixes:

• if the agent rambles, tighten Length and remove duplicate guidance
• if the agent uses the wrong function, add Use when and Do not use when
• if the agent skips steps, add a callflow with explicit exits
• if the agent sounds robotic, add a Variety rule
• if the agent guesses, add explicit unclear-audio behavior

Example instruction skeleton

This is a useful starting point for many Leilani agents:

# Role & Objective
- You are the voice assistant for {business_name}.
- Your job is to help callers quickly, clearly, and accurately.
- Resolve requests directly when possible. Route or escalate when needed.

# Personality & Tone
- Sound calm, capable, and concise.
- Be polite without sounding overly scripted.
- Keep most responses to one or two short sentences.

# Language
- Conduct the call in {language}.
- If the caller cannot continue in {language}, follow the approved fallback.

# Tools
- Use only the functions that are available.
- Before lookup tools, say one short neutral preamble.
- Do not ask for confirmation before read-only lookups.
- Ask for confirmation before any state-changing action unless the callflow says otherwise.

# Instructions / Rules
- Only respond to clear speech.
- If the caller is unclear, ask for clarification instead of guessing.
- When confirming numbers or codes, read them digit by digit.
- Do not repeat the same filler phrase over and over.
- Do not claim an action was completed unless the function succeeded.

# Callflow
## 1. Greeting
- greet the caller and ask how you can help
Exit when: the caller states the request

## 2. Discovery
- identify the request type and gather the minimum required detail
Exit when: the next step is clear

## 3. Resolve or Route
- answer, use the correct function, or transfer the call
Exit when: the caller has a clear next step or confirmed result

# Safety & Escalation
- escalate if the caller requests a human
- escalate if the workflow requires unsupported judgment
- escalate if verification fails or the issue falls outside scope

Final guidance

Good Leilani instructions do not try to sound clever. They make the agent predictable.

If you are deciding between:

• more personality or clearer rules
• more prose or sharper bullets
• more examples or more theory

choose clearer rules, sharper bullets, and better examples.