How to Write Effective AI Agent Prompts

Writing clear, structured prompts helps your AI Agent behave more accurately and respond naturally. This guide covers how to write effective prompts for AI Agents on respond.io, including both Instructions and Actions.

Instructions vs. actions

Writing instructions

When creating instructions, structure them clearly so AI Agent always knows who it is, how to behave, and what steps to follow. We recommend breaking down instructions into four parts.

Note: AI Agent instructions support up to 10,000 characters. If you exceed the limit, you’ll be prompted to shorten your instructions before saving.

Tips for instructions

Writing clear, structured instructions helps your AI Agent behave consistently. Below is a best-practice example for a Lead Qualification Sales Agent and the key tips to follow.

# CONTEXT
* You're chatting with someone exploring our product (new, returning, or browsing). Your goal is to guide them to the right product or plan.

# ROLE & COMMUNICATION STYLE
* Be warm, helpful, and relaxed—never pushy. Ask one question at a time. Keep replies short, clear, and encouraging.

# TOP-LEVEL FLOW
1. Greet and welcome the Contact (Contact name $contact.firstname). 
2. Ask, collect, and save Contact fields: name, email, and phone (all required).
3. Ask about their needs: **"Do you have a budget in mind? 🙂"**

## QUALIFY LEAD
1. **Qualified:** If budget ≥ 100000, recommend a product based on their answers using the Knowledge Source.
 1.1 If they show interest, ask: **“Would you like to book a demo or talk to someone?”**
 1.2 If yes, assign to @Sales Team and update the lifecycle stage to Hot Lead. If not ready, let them know you're here if they need help later.
2. **Unqualified:** If budget < 100000, continue answering any questions they have.

# BOUNDARIES
1. Do not inform the contact that they are qualified or unqualified. Gracefully proceed with the flow.

• Use canonical terms (the exact names and actions from your Workspace):

  • Teams/agents: e.g. @Support Team, @Sales Team, @Jane Doe

  • Actions: e.g. Assign to, Close conversation, Update Lifecycle stages, Update Contact fields

  • Contact fields: e.g. Name field, Email field, Phone field — so data is saved/updated correctly

• Structure your instructions clearly:

  • Break steps into logical order (Greet → Ask → Decide → Assign)

  • Use point form instead of paragraphs (Shift + Enter for line breaks)

  • Use headers (# H1, ## H2) for each section. For example:

    # CONTEXT
    # ROLES AND COMMUNICATION STYLE
    # TOP-LEVEL FLOW
    ## SUB-LEVEL FLOW
    # BOUNDARIES

• Keep language clean and usable:

  • Write in clear, conversational English (other languages work too if canonical terms are preserved)

  • Use symbols (=, <, :) for comparisons or conditions

  • Keep grammar/spelling correct

  • Use emojis sparingly (to stay approachable but professional)

• Be clear about capabilities:

  • State what the Agent can and cannot do

  • Don’t overload instructions with details → use Actions for execution (e.g. assigning, closing, updating fields)

• Organize by flows and scenarios:

  • Start with a top-level flow (e.g. Greet → Ask → Decide → Assign)

  • Break it into scenarios for common situations

    • Example: In the Sales Agent prompt above, “Qualifying Lead” is its own scenario

  • This makes prompts easier to read, update, and maintain

Writing action prompts

Action prompts are used when AI Agent performs something before sending a reply — like assigning a chat or closing the conversation.

These should be short, specific, and focused on execution.

How to write them

For each action, describe:

• When it should happen (the condition)

• What the Agent should do

Tips for actions

AI Agents can be told what to do in two places:

• Instructions box

  • Here you usually write your step-by-step flows, e.g. “Greet → Ask → Assign → Close”.

  • These are sequential instructions, meaning they run in order like a script.

• Actions settings

  • Here you can configure non-sequential rules, e.g. “If user asks for a human → Assign to @Support Team”.

  • These don’t depend on the flow; they can trigger anytime.

For best accuracy, it’s recommended to cover actions in both places (instructions and action settings). This way AI Agent always knows what to do.

If you only add them in the instructions box, make sure the respective actions are enabled too — otherwise AI Agent won’t be able to execute them, even if your instructions mention them.

Writing prompts for follow-ups

AI Agents can automatically send follow-up messages when a Contact doesn’t respond after a specific time — helping you keep conversations going and increase engagement.

To enable this, add clear follow-up instructions in the Instructions section of the AI Agent configuration page.

Here’s an example showing how an AI Agent handles follow-ups, responses, and conversation closure:

If the customer doesn't reply after 2 minutes, send a gentle follow-up like: "Hey, you still there? No rush, just checking in." If there's still no reply, close the conversation, update lifecycle to Cold Lead, and say "I'll close the conversation. Feel free to ping me anytime you wish to continue!"

How this works:

• After 2 minutes of no response, AI Agent automatically sends the follow-up message.

• If the Contact still doesn’t respond after that, AI Agent executes the next actions in the prompt — closing the conversation, updating Lifecycle status, and sending the final message.

• If the Contact replies before the last action in your prompt, all remaining follow-up actions are cancelled and the conversation continues as normal.

This example shows how you can chain multiple steps into a single follow-up flow within your prompt.

Follow-up basics

• AI Agent checks if the Contact hasn’t replied after the time you specify in your prompt.

• If no response is received within that time, AI Agent sends the follow-up message you define.

• Follow-up sequence stops automatically if:

  • The Contact replies before the scheduled time

  • The conversation is unassigned or closed

  • AI Agent determines the Contact is no longer interested, has said goodbye, or the objective is achieved

You can include one or multiple follow-ups in your prompt to handle different scenarios or escalation steps.

If you’ve written follow-up instructions before the Follow-Up feature was launched, you’ll need to resave your template for the changes to take effect.

Follow-Up Limits

• Each follow-up must be scheduled within 24 hours (1 day) of the previous message.

• You can include up to 5 follow-ups per prompt, each with its own timing, message, and actions (e.g., send a reminder, assign a user, or close the conversation).

• AI Agent will follow the timing defined in your prompt, but messages sent outside WhatsApp’s 24-hour window may fail to deliver.

• After the final follow-up, AI Agent continues any remaining actions defined in your prompt (e.g., assigning or sending messages).

Using the prompt optimizer

When editing instructions or action prompts, you can use the prompt optimizer tool to improve clarity and phrasing while keeping the original intent.

Use it when:

• You want a more polished or structured version of your prompt

• You’re not sure how to phrase things clearly

• You’re starting from scratch and want guidance

Simply click Optimize, review the suggested rewrite, and adjust if needed.

This works for both general instructions and specific actions like assigning conversations or closing chats.

Using variables

Variables make responses feel personal and accurate.

Variables can be used in both instructions and actions — especially when gathering or referencing Contact details.

Using the @ variable

The @ variable allows AI Agents to assign a conversation to a specific team, human agent, or another AI Agent based on the instructions or action prompt.

It supports routing that mimics manual assignments made in the Inbox — making it especially useful in templated actions.

Tips for variables

• Use clear logic in your action prompts (e.g. “If the Contact asks about pricing, assign to @Sales.”).

• If possible, align your Workspace team structure with how you want to use AI Agents for routing.

Using Contact field variables in prompts

You can use $contact.fieldName to dynamically reference a Contact’s existing information. These are especially useful when:

• You want AI Agent to personalize its greeting or response

• You need to verify or confirm details the Contact has previously shared

• You want to avoid asking for info that’s already available

Tips for Contact field variables

Contact field variables personalize your Agent’s responses and help it save or update customer data automatically.

• What happens behind the scenes: When AI Agent is generating a reply, variables are swapped with the actual value from the Contact profile.

  • Example: $contact.name → becomes “Wilson” in the conversation.

• What AI actually sees: AI Agent only sees the value (“Wilson”), not the variable label ($contact.name).

Why this matters

• If you just write “the email you gave earlier”, AI Agent won’t know you meant $contact.email — it will only see the value (like wilson@email.com), and could get confused if multiple emails are mentioned.

• By always referencing the field name and the value (e.g., Email: $contact.email, Phone number: $contact.phone), you make it crystal clear which piece of information you’re talking about.

• If you want AI Agent to save or update a field, be explicit and mention the field ID in your prompt:

  • Example: “Save and update the email field if the user provides a new one.”

Prompt examples

Now that you’ve learned how to structure prompts, use variables, and write clear instructions, let’s look at some full examples. These compare good prompts vs bad prompts so you can see how the best practices come together in real life.

Example 1

Good prompt

# CONTEXT
* Guide pricing-page visitors to the right plan.

# ROLE & COMMUNICATION STYLE
* Warm, concise; one question at a time.

# TOP-LEVEL FLOW
1) Greet the customer using their name: $contact.firstname
2) Ask & save **Name field**, **Email field**, **Phone field**
3) Ask budget

## SCENARIOS
* If budget ≥ 100000 → Recommend plan; ask demo
  - If yes → **Assign to @Sales Team**; **Update Lifecycle stages** → **Hot Lead**
* Else → Answer questions; keep chat helpful

# BOUNDARIES
* Can: Recommend, **Assign to**, **Update Contact fields**, **Update Lifecycle stages**
* Cannot: Offer discounts or take payments

Why this works:

• Clear headers, top-level flow, scenarios.

• Fast to read, easy to maintain.

Bad prompt

Hey welcome! get their info and budget, recommend something, maybe send to sales if they’re big. 
If they’re not sure, just keep chatting and don’t say they’re qualified or whatever. we’ll figure it out later and close it.

Why this doesn't work:

• No headers, no sections, no sequence.

• Readers must guess the order and actions.

Example 2

Good prompt

# CONTEXT
* Triage product issues and route correctly.

# ROLES AND COMMUNICATION STYLE
* Calm, professional, friendly 🙂

# TOP-LEVEL FLOW
1) Greet the customer with their name: $contact.firstname
2) Ask for a brief summary and steps already tried

## SCENARIOS
* Urgent (login blocked | data loss | outage) → **Assign to @Support Team**; set expectations
* Non-urgent → Provide steps/help doc; if resolved **Close conversation**; else **Assign to @Support Team**

# BOUNDARIES
* Can: Share guides.
* Cannot: Access billing, reset passwords, change ownership.

Why this works:

• Clean, professional English with precise terms.

• Canonical actions/teams/fields are used verbatim.

Bad prompt

hi there pls help user with issues
- if its urgent ping tech team. 
- grab name/email/phone if u can. 
- if they’re vip send to sales team. close when done n mark hot lead

Why this doesn't work:

• Slang/typos (“pls”, “suppot teem”), vague actions, inconsistent capitalization.

• No canonical team names or action verbs.

Example 3

Good prompt

# CONTEXT
* Handle enterprise feature requests and handoffs.

# ROLES AND COMMUNICATION STYLE
* Transparent, not pushy.

# TOP-LEVEL FLOW
1) Ask and update: **Name field**, **Email field**, **Phone field**
2) Confirm needs and budget

## ACTION STEPS (Correct Order)
* Demo requested AND budget ≥ 100000:
  1) Recommend plan; confirm demo
  2) **Assign to @Sales Team**
  3) **Update Lifecycle stages** → **Hot Lead**
  4) Summarize next steps; confirm
  5) **Close conversation**
* Info only / not ready:
  - Share overview; keep Q&A
  - **Close conversation** only after they confirm done

# BOUNDARIES
* Can: Recommend plans. 
* Cannot: Offer discounts, modify contracts.

Why this works:

• Each action has prerequisites and exact order.

• Separate step lists remove ambiguity.

Bad prompt

If someone asks for enterprise features:
- close the chat to keep it tidy
- then mark them Hot Lead and later assign sales if they reply again.
- Get email if needed.

Why this doesn't work:

• Assigns before identifying; updates lifecycle randomly; closes too early.

• No clear triggers for each action.