> ## Documentation Index
> Fetch the complete documentation index at: https://fliqr.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Write Effective AI Agent System Prompts in Fliqr AI

> Write system prompts that control your AI Agent's tone, scope, and output format — including structured JSON output and dynamic contact field injection.

The system prompt is the instruction set your AI Agent follows for every conversation. It runs before any user message, which means it shapes every response the agent generates. A vague prompt produces inconsistent, off-brand answers. A well-structured prompt produces predictable, useful ones.

## Overview

When a conversation starts, Fliqr AI sends your system prompt to the language model along with the conversation history. The model uses your instructions to decide what to say, what to avoid, and how to format its output. You write the system prompt once and it applies to all conversations handled by that agent.

System prompts are also where you inject dynamic contact data using field variables — so the agent can address customers by name, reference their account, or adapt its behavior based on stored attributes.

## Prerequisites

* An AI Agent configured in Fliqr AI — see [AI Providers](/docs/core-concepts/ai-agents/ai-providers)
* Basic familiarity with your AI Agent's intended use case
* (Optional) Custom User Fields set up for your contacts — needed for variable injection

## Anatomy of a Good System Prompt

A system prompt that produces reliable results typically has four sections:

1. **Role definition** — Who is the agent? What company does it represent?
2. **Context and constraints** — What can it discuss? What is off-limits?
3. **Output format** — Should it reply in plain text, or return structured JSON?
4. **Examples** — One or two short examples anchor the model's behavior for edge cases.

Keep each section explicit. The model cannot infer constraints you do not state.

## Writing Your First System Prompt

<Steps>
  <Step title="Open the Agent editor">
    Go to **AI Agents** → select your agent → **System Prompt** tab.
  </Step>

  <Step title="Define the role">
    Start with a one-sentence role statement. Name the company, the job, and the scope.

    ```text theme={null}
    You are a customer support agent for Acme Corp.
    You help customers with order tracking, returns, and product questions.
    ```
  </Step>

  <Step title="Add constraints">
    State explicitly what the agent must not do. Constraints prevent the model from improvising in ways that create liability.

    ```text theme={null}
    You NEVER discuss competitor products or make pricing promises.
    Always reply in the same language the customer uses.
    If you cannot answer, say: "Let me connect you with a human agent."
    ```
  </Step>

  <Step title="Specify output format">
    If your Flow expects structured output (quick replies, cards), instruct the model here. Otherwise, plain text is the default.
  </Step>

  <Step title="Test in the Playground">
    Open the **Playground** tab and send a few test messages, including edge cases like off-topic requests or questions your knowledge base does not cover.
  </Step>
</Steps>

## Complete Example: Customer Service Agent

The following prompt is production-ready for a general customer service agent. Adjust the company name, scope, and fallback instruction to match your context.

```text theme={null}
You are a customer support agent for Acme Corp.
You help customers with order tracking, returns, and product questions.
You NEVER discuss competitor products or make pricing promises.
Always reply in the same language the customer uses.
If you cannot answer, say: "Let me connect you with a human agent."
```

## Injecting Contact Data with Field Variables

You can inject stored contact data into the system prompt at runtime using the `{{field_name}}` syntax. Fliqr AI replaces these placeholders with the contact's actual values before sending the prompt to the model.

```text theme={null}
The customer's name is {{first_name}}.
Their last order ID is {{last_order_id}}.
Their account tier is {{account_tier}}.
If the customer's account tier is "VIP", prioritize speed and offer expedited options.
```

This lets a single agent behave differently for different customer segments — without building separate agents or flows for each one.

<Note>
  Field variables are replaced at conversation start. If a variable has no value for a given contact (e.g., `{{last_order_id}}` is empty), it renders as an empty string. Add a conditional instruction to handle missing values gracefully: `"If last_order_id is not provided, ask the customer for their order number."`
</Note>

## JSON Output Prompting

When your Flow needs the agent to return structured data — such as quick replies, cards, or a handover signal — instruct the model to respond exclusively in JSON. Combining this with a strict schema example keeps the output consistent.

```json theme={null}
Your response must always be a single JSON array with one message object.
Never include explanatory text outside the JSON.

Example format:
[
  {
    "message": {
      "text": "How can I help you today?",
      "quick_replies": [
        { "content_type": "text", "title": "📦 Track Order", "payload": "📦 Track Order" },
        { "content_type": "text", "title": "↩️ Start Return", "payload": "↩️ Start Return" },
        { "content_type": "text", "title": "🛍️ Browse Products", "payload": "🛍️ Browse Products" }
      ]
    }
  }
]
```

<Tip>
  Always include a concrete JSON example in the prompt. Describing the format in prose alone leads to structural inconsistencies — models follow examples more reliably than abstract descriptions.
</Tip>

## Common Mistakes

| Mistake                   | Result                                                               | Fix                                                         |
| ------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| No language instruction   | Agent defaults to English even when users write in French or Spanish | Add: "Always reply in the same language the customer uses." |
| Vague role ("be helpful") | Agent answers questions outside your intended scope                  | Be specific: name the company, the topics, and the limits   |
| No fallback instruction   | Agent invents an answer when it does not know                        | Add an explicit "I don't know" response template            |
| Missing output format     | Agent returns prose when your Flow expects JSON                      | Specify format with a concrete example                      |

## Example Prompts for Different Use Cases

<AccordionGroup>
  <Accordion title="Sales Qualifier">
    ```text theme={null}
    You are a sales qualification assistant for TechFlow Inc.
    Your goal is to determine whether a prospect is a good fit for our B2B software.

    Ask the following questions one at a time:
    1. What is your company size?
    2. What problem are you trying to solve?
    3. What is your timeline for making a decision?
    4. Do you have budget allocated for this?

    After collecting all four answers, summarize the prospect's profile and
    respond with a JSON object: {"qualified": true/false, "reason": "..."}.

    Do not pitch features. Do not discuss pricing. Only qualify.
    Always reply in the same language the customer uses.
    ```
  </Accordion>

  <Accordion title="FAQ Bot">
    ```text theme={null}
    You are an FAQ assistant for Bright Solar, a residential solar panel company.
    You answer questions about installation timelines, financing options,
    warranty coverage, and maintenance.

    You do not quote specific prices — direct pricing questions to the sales team.
    You do not discuss competitor products.
    Keep responses under 120 words unless a detailed explanation is essential.
    Always reply in the same language the customer uses.

    If a question falls outside solar energy topics, say:
    "That's outside my area — for that, please contact our support team at support@brightsolar.com."
    ```
  </Accordion>

  <Accordion title="Appointment Scheduler">
    ```text theme={null}
    You are an appointment scheduling assistant for Greenview Dental.
    Your job is to collect the information needed to book a new patient appointment.

    Collect the following, one at a time:
    - Patient's full name
    - Preferred appointment date and time (offer morning or afternoon if unsure)
    - Reason for visit (cleaning, exam, pain, cosmetic)
    - Contact phone number

    Once collected, confirm the details back to the patient and respond with:
    {"action": "book_appointment", "name": "...", "datetime": "...", "reason": "...", "phone": "..."}

    Do not confirm that the appointment is booked — a human staff member will confirm.
    Always reply in the same language the customer uses.
    ```
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup cols={2}>
  <Card title="Knowledge Sources" icon="book-open" href="/docs/core-concepts/ai-agents/knowledge-sources">
    Add documents and URLs so your agent answers from your own content.
  </Card>

  <Card title="Functions & Actions" icon="bolt" href="/docs/core-concepts/ai-agents/functions-actions">
    Let your agent call external APIs to retrieve live data mid-conversation.
  </Card>
</CardGroup>