Skip to main content
The system prompt is the primary instruction set your agent follows in every conversation. It defines the agent’s persona, the scope of topics it can discuss, how it should behave, and what it should do when it encounters edge cases. A well-written system prompt is the single most impactful configuration change you can make.

​
Anatomy of a system prompt

A strong system prompt covers four areas:
  1. Identity — Who the agent is and what it represents.
  2. Goal — The primary task the agent should accomplish.
  3. Constraints — What the agent should and should not do.
  4. Tone — How the agent should communicate.
system-prompt.txt
You are Aria, a customer support agent for Acme Corp.

Your goal is to help customers resolve issues with their orders, answer questions about products, and escalate to a human agent when needed.

Rules:
- Only discuss topics related to Acme Corp products and orders.
- Never share pricing not listed in the knowledge base.
- If the customer is frustrated, acknowledge their concern before offering a solution.
- If you cannot resolve the issue, use the transfer tool to connect to a human agent.

Tone: Friendly, concise, and professional. Speak in short sentences suited for voice conversation.
Write prompts in the same conversational register you want the agent to use. Because responses are spoken aloud, avoid bullet points and long prose in the prompt — they often leak through into the agent’s speech.

​
Voice-specific writing tips

System prompts for voice agents differ from those for text chatbots. Keep these in mind:
Tell the agent what to do, not what to avoid. “Confirm the customer’s order number before proceeding” is clearer than “Don’t skip order confirmation.”
If your brand name or product has unusual pronunciation, spell it phonetically in the prompt. For example: “Our product is called Qwirl (pronounced ‘kwerl’).”
Voice responses should be short. Add an instruction like: “Keep each response to 2-3 sentences. Ask one follow-up question at a time.”
Agents work best when they know exactly when to stop trying. State the escalation condition clearly: “If you cannot answer after two attempts, transfer the call using the transfer tool.”

​
Using dynamic variables in the prompt

You can inject per-session data into the prompt using {{variable_name}} placeholders. These are resolved at conversation start before the agent processes anything.
prompt-with-variables.txt
You are a billing assistant for {{company_name}}.

The customer's name is {{customer_name}} and their account tier is {{account_tier}}.

If the customer has a {{account_tier}} plan, they are eligible for priority support.
Pass the variable values when starting the conversation. See Personalization for details.

​
Prompt size limit

The maximum system prompt size is 2 MB. If you need to supply large amounts of reference information, use the knowledge base instead — it is retrieved dynamically and does not count toward the prompt limit.

​
Setting the prompt via API

from xuna_ai import XunaAI

client = XunaAI()

agent = client.conversational_ai.agents.update(
    agent_id="your-agent-id",
    conversation_config={
        "agent": {
            "prompt": {
                "prompt": "You are Aria, a customer support agent for Acme Corp..."
            }
        }
    }
)
Changes to the system prompt take effect immediately for new conversations. Conversations already in progress continue with the prompt that was active at their start.