Writing Custom Instructions for AI Agent Builder
Write custom instructions that control exactly how your Agent collects information, handles responses, and moves through a conversation.
When to use this
- You're setting up a new Agent and need to define how it responds to different answers based on certain conditions
- Your Agent isn't routing conversations the way you expect
- You want the agent to perform certain actions (ex: end conversation, write back a value to the ATS (disposition), skip certain questions, etc.)
Before you start
Add all your questions to the Data Collection or Screening module first. Instructions reference questions by number and by hint of what the question is about (e.g., if the candidate provides X input, then ask Question 1 (What is their job preference) - if those aren't set yet, the logic has nothing to point to.
Important: The Agent Builder automatically generates the complete agent prompt based on the configurations and settings selected within each module.
You do not need to write or paste the entire agent prompt in the Instructions section. Doing so can lead to conflicts, duplication, or unintended agent behaviour.
The Instructions field should only be used to add additional guidelines, rules, or conditions that are specific to your use case and that you want the agent to follow. These instructions act as additional guidance on top of the prompt that Agent Builder already creates.
How instructions work
Instructions are guidelines, not fixed scripts. The Agent reads your instructions and applies them based on the context of the conversation - so the wording of a candidate's response may vary, but the Agent still interprets the intent correctly.
For example: if your greeting asks "Are you currently seeking employment opportunities?", the Agent should recognize a positive response not just when the candidate says "Yes" - but also when they say:
- "I'm exploring new opportunities"
- "I'm open to the right role"
- "Yeah, I'm looking"
This is why instructions use positive and negative instead of yes and no. It gives the Agent the flexibility to understand real responses.
The three building block elements
Every special instruction is built from one or more of these elements. Learn each one first - combining them becomes straightforward once you understand what each one does.
1. Response Pickers < >
Select the question from the question response picker to reference the candidate's answer to that specific question.
The Agent matches the candidate's answer to that question - regardless of how they phrase it.
Example:
If <Are you currently seeking employment opportunities?> is negative,
politely end the conversation.
Why this matters: You don't need the candidate to say "No" for this to trigger. The Agent reads the intent. Someone who says "Not right now" or "I'm just browsing" will still be caught by this instruction.
Note: To ensure the question response picker functions correctly, verify that all relevant questions have been added to the Data Collection module's questions section.
2. ATS Variables {{ }}
Use double curly braces to reference an ATS field
{{field.name}}
Variables used in instructions:
| Variable | What it references |
|---|---|
| {{email}} | The email address of the candidate as per the ATS record |
| {{candidate.zipcode}} | The candidate's zip code from your ATS |
| {{joborder.zip}} | The open job's zip code from your ATS |
| {{status}} | The candidate's disposition status |
Example:
Check if {{email}} is correct.
If not, ask Question 2 to update it.
3. Question Numbers
Reference questions by number to control what gets asked next, what gets skipped, and when the conversation ends.
Example:
If <Which of the following best describes your employment status?> shows
they are looking for a job, ask Questions 2, 3, 4, 5, and 6.
Tip: Keep a numbered list of your questions open while writing instructions. "Question 6" is only meaningful if you know what Question 6 is.
Anatomy of a complete instruction
Most instructions follow one simple pattern: condition → action.
If [response picker or variable] is [positive / negative / value], [what happens next].
Here's a real example, broken down:
If <Are you authorized to work in the US?> is negative,
set {{status}} as 'Not Eligible' and end the conversation
with a message explaining that the role is not visa-sponsored.
| Part | What it does |
|---|---|
| <Are you authorized to work in the US?> | Identifies which question triggers this logic |
| is negative | Defines the condition |
| set {{status}} as 'not eligible' | Updates the candidate's disposition in your ATS |
| end the conversation with a message... | Controls exactly what the Agent says and does next |
How to write your first instruction
Use this four-step process every time you write a new instruction.
Step 1 - Identify the trigger question.
Ask yourself: which question, when answered a certain way, should change what happens next? That question is your starting point.
Step 2 - Choose the right element.
| What you're referencing | Element to use |
|---|---|
| A question and the candidate's answer to it | Response picker < > |
| A saved field from the ATS or conversation | Variable {{ }} |
| Which question to ask next | Question number |
| Which ATS field to set/write back to | Variable {{ }} |
Step 3 - Write the condition using positive or negative.
✅ If <Are you interested in exploring new roles?> is negative, end the conversation.
❌ If the user says no to the job interest question, end the conversation.
Step 4 - Write the action clearly.
Tell the Agent what to do: skip ahead, ask a set of questions, end the conversation, or say something specific. If it's an exact message, put it in quotes.
Full worked example: Screening for a warehouse associate role
This section walks through a complete Agent setup from start to finish - the question list, the full instruction set written as it would appear in the module, how the conversation branches for different candidates, and what each path actually looks like.
The setup
A recruiter at a staffing agency is building an outbound screening agent for warehouse associate candidates. Before any recruiter reviews a candidate, the Agent needs to:
- Confirm the candidate is actively looking for work
- Check US work authorization (hard stop if not eligible)
- Verify the candidate's contact details and location
- Collect role-specific screening information
- Exit early if the candidate doesn't meet education requirements
- Route fully qualified candidates forward
Step 1 - Build the question list first
Before writing a single instruction, finalize every question. Instructions reference questions by number - if you change the order later, every instruction that references a number will need to be updated.
| Question # | Question | Module |
|---|---|---|
| Q1 | Are you authorized to work in the US? | Data Collection |
| Q2 | What is your full name? | Data Collection |
| Q3 | What is your current email address? | Data Collection |
| Q4 | What is your phone number? | Data Collection |
| Q5 | What is your current zip code? | Data Collection |
| Q6 | What type of shift are you available for? (Day / Evening / Night / Flexible) | Data Collection |
| Q | How many years of warehouse or logistics experience do you have? | Data Collection |
| Q9 | What is the highest level of education you've completed? | Data Collection |
Step 2 - Writing the custom instruction based on the user’s response to the Greeting message
Greeting message:
"Hello! I'm reaching out about warehouse associate opportunities in your area. Are you currently seeking employment opportunities? If so, I'd love to take a few minutes to learn more about you."
Add this instruction in the Data Collection module:
If the user is interested in the conversation and responds positively,
start asking the above questions.
If the user is not interested in the coversation, then end the conversation with the exact message:
"Thanks for chatting with me! If you'd like to explore our open positions
in the future, please visit abc.com/job-board."
What this does: The Agent doesn't require the candidate to say "Yes." It recognizes "I'm open to it," "Yeah, looking for something," or "Definitely" as positive - and routes them forward. Anyone who says "Not right now" or "I'm not interested" gets the closing message and exits cleanly.
Step 3 - Writing custom instructions based on candidate’s response to the Data Collection questions
Once a candidate passes the greeting, they move into Data Collection. This is where eligibility is checked and contact details are gathered.
All Data Collection instructions - written exactly as they appear in the module:
1. If <Are you authorized to work in the US?> is negative,
set {{status}} to 'Not Eligible' and end the conversation with the exact message: "Thank you for your time. Unfortunately, this role requires US work authorization and we're unable to proceed at this stage."
2. If <Are you authorized to work in the US?> is positive,
ask Questions 3 (full name), 4 (email), 5 (phone), and 6 (zip code).
3. Ask the candidate if {{email}} is their current email address.
If not, ask Question 4 to update the email address.
What instruction 1 does: Work authorization is a hard disqualifier. The Agent exits the conversation immediately and sets the status in your ATS - no recruiter action needed. The exact message in quotes is what the candidate receives, word for word.
What instruction 2 does: The agent will ask the rest of the data collection questions for only authorized candidates. Labelling each question number in parentheses makes this instruction easy to audit - you can see at a glance what each number refers to without opening the question list.
What instructions 3 does: Instruction 3 catches a stale email on file and corrects it before moving forward.
Writing custom instructions based on certain static Screening questions
Static screening questions can be included in the data collection module.
Few custom instructions examples for static screening questions
1. Ask Questions 7, 8, and 9.
(Question 7 – shift preference, Question 8 – years of experience,
Question 9 – education level)
2. If <What is the highest level of education you've completed?> is lower
than high school or GED, end the conversation with the exact message:
"Thank you for taking the time to speak with us. Based on the role requirements,
we're unable to move forward at this time, but we encourage you to check
our job board for other opportunities at abc.com/job-board."
3. If <How many years of warehouse or logistics experience do you have?> is positive
and <Are you authorized to work in the US?> is positive,
continue to the closing message.
What instruction 2 does: Candidates who don't meet the education threshold are exited before any recruiter time is spent. The exact message ensures a respectful close every time, with a consistent redirect to the job board.
What instruction 3 does: This is the final gate. The Agent checks both experience and work authorization before moving a candidate to the closing message - meaning only candidates who've cleared every requirement get through.
Step 5 - Configure Screening Module.
You can screen candidates using AI-generated questions or questions already added in the Data Collection module, or both.
Option 1 - AI-Powered Questions
Enable AI-Powered Questions to allow the Agent to automatically generate screening questions using the mapped job variables configured during setup. But before you do that
The Agent will create and evaluate relevant screening questions based on the job information provided.
Option 2 - Predefined Questions
Enable Predefined Questions to reuse questions that have already been added in the Data Collection module.
To add existing questions:
- Select Predefined Questions.
- Search for a question using the search box.
- Select the questions you want to include in screening.
The selected Data Collection questions will now be used as part of the candidate evaluation process.
You can use AI-Powered Questions, Predefined Questions, or both together.
Add Screening Instructions
Use the Screening Instructions section to define additional rules or conditions that the Agent should follow during screening.
Examples:
If <Do you have a valid driver's license?> is negative,
end the conversation with the exact message:
"Thank you for your time. This position requires a valid driver's license."
If <How many years of experience do you have?> is greater than 3,
continue to the closing message.
What this does
AI-Powered Questions help generate job-specific screening questions automatically.
Predefined Questions allow you to reuse existing Data Collection questions for evaluation without creating them again.
Screening Instructions provide additional logic that determines how candidates move through the screening process.
Step 6 - Set the Closing message
The Closing module sends the final message to candidates who complete the full flow. This one doesn't need an instruction - it's configured directly in the Closing module.
Closing message example:
"Thank you, {{name}}! We've received your information and a member of our team will be in touch shortly to discuss next steps. In the meantime, feel free to browse our open roles at abc.com/job-board."
What to avoid
| ❌ Don't do this | ✅ Do this instead |
|---|---|
| Do not add the entire prompt with Agent role, tone, etc. Agent Builder generates the entire prompt based on module configurations and custom instructions, if any. | Only add custom guidelines/conditions in the instructions that you want the agent to honour/follow |
| Write "if the user says yes" | Use is positive |
| Write "if the user says no" | Use is negative |
| Reference a question as "the email question" | Use the exact question text in < > or its question number |
| Write an exact closing message without quotes | Wrap it in quotes so the Agent uses it verbatim |
| Add instructions before all questions are finalized | Lock down your question list first, then write instructions |
| Reference question numbers without labels when listing many | Add parenthetical labels - (Question 3 - name, Question 4 - email) |
Quick-reference card
| Element | Syntax | Use when... |
|---|---|---|
| Response picker | <Question text> | You want to trigger logic based on the candidate's answer to a specific question |
| Variable | {{field.name}} | You want to check or update a saved ATS or conversation field |
| Question number | Question 4 | You want to control which question comes next or which to skip |
| Positive / Negative | is positive / is negative | You want to capture intent without requiring a specific word or phrase |