Writing Effective Prompts

How to write the preamble (system prompt) for your single prompt agent

Overview

The preamble is the system prompt that defines your agent’s identity, behavior, and task. Everything the agent does during a call is guided by this prompt.

Recommended Structure

A well-structured preamble typically covers these sections:

1. Identity & Role

Define who the agent is and what it represents.

You are Alex, a customer support specialist at Acme Corp.
You help customers with product inquiries, order tracking, and technical support.

2. Personality & Tone

Set the conversation style.

Speak in a warm, friendly, and patient manner. Keep responses concise.

3. Response Guidelines

Specify how the agent should format and structure its responses.

- Keep responses under 30 seconds of speech
- Ask one question at a time
- Confirm understanding before proceeding
- If you don't know something, say so honestly

4. Task & Goals

Define what the agent should accomplish, ideally as numbered steps.

Your primary task is to schedule appointments.

Process:
1. Greet the caller
2. Collect: full name, phone number, preferred date and time
3. Check availability using the check_availability tool
4. Confirm the appointment details
5. Provide a confirmation number

5. Guardrails

Set clear boundaries for what the agent should not do.

Do NOT:
- Make promises you cannot keep
- Discuss competitor products
- Process payments or collect card details
- Continue if the user is abusive

6. Edge Case Handling

Prepare for difficult scenarios.

If asked something outside your knowledge:
- Be honest: "I don't have that information available"
- Offer alternatives: "I can transfer you to someone who can help"

Using Variables

You can reference system variables and custom variables in your prompt using {{variable_name}} syntax.

System variables (always available):

Variable	Description
{{agent_name}}	Name of the current agent
{{agent_id}}	Unique identifier for the agent
{{agent_number}}	Agent’s phone number
{{current_time}}	Current time (HH:MM)
{{current_date}}	Current date (YYYY-MM-DD)
{{current_datetime}}	Date and time in ISO format
{{current_day}}	Day of the month (1–31)
{{current_month}}	Month (1–12)
{{current_year}}	Year (YYYY)
{{current_weekday}}	Day of the week
{{current_timestamp}}	Timestamp in milliseconds
{{call_id}}	Unique call identifier
{{call_type}}	Type of call
{{call_start_time}}	When the call began
{{direction}}	inbound or outbound
{{user_number}}	Caller’s phone number
{{user_number_area_code}}	Caller’s area code

For dynamic business-specific data (e.g., working hours, customer info), use custom variables passed as params when initiating the call. See Variable System for details.

Jinja2 Templates

Beyond simple substitution, prompts support full Jinja2 template syntax — conditionals, filters, and expressions are all available.

{% if direction == "outbound" %}
Hi {{customer_name}}, this is {{agent_name}} from Acme Corporation.
{% else %}
Thank you for calling Acme Corporation. I'm {{agent_name}}.
{% endif %}

Welcome{% if customer_name %}, {{customer_name}}{% endif %}!
Your balance is {{balance | default("unavailable")}}.

Templates are processed server-side before the prompt reaches the LLM. See the Jinja2 Template Designer Documentation for the full syntax reference.

Example:

You are {{agent_name}}.
Today is {{current_date}} and the time is {{current_time}}.
The caller's number is {{user_number}}.
Working hours: {{working_hours}}

Tool Integration

When your agent uses tools, include clear instructions for when and how to use them:

To check product availability:
1. Ask for the product name or SKU
2. Use the check_inventory tool
3. Based on results:
   - In stock: "We have that available. Would you like to place an order?"
   - Out of stock: "That's currently out of stock."
   - Discontinued: "That product has been discontinued. Can I suggest an alternative?"

Common Mistakes

Too vague:

You are a helpful assistant. Answer questions.

Better:

You are a customer support specialist for Acme Corp. Help customers
with product questions, order tracking, and returns. Use the knowledge
base for product details.

---

Conflicting instructions:

Be extremely brief. Provide detailed, comprehensive answers with lots of context.

Better:

Give concise answers (2–3 sentences). If the customer wants more detail,
offer to elaborate: "Would you like me to explain that further?"

Next Steps

Voice Settings

Configure voice and language options

Call Behavior

Set up response timing and interaction controls

Intelligence Features

Enable smart features like gender detection and smart call end

Knowledge Base

Add reference materials for your agent