You can use instructions to add rules and conditions to each module of your AI Agent. The AI Agent Builder generates the main agent prompt from the settings you choose in each module. At the same time, instructions let you add logic specific to your hiring process, such as ending the conversation when a candidate doesn’t match the criteria, skipping questions, or writing a status back to your ATS.
When to use this
Use instructions when:
- 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 a 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.
-
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 Agent Builder automatically generates the complete agent prompt based on the configurations and settings selected within each module. Refer to the Agent Characteristics article to learn more.
- 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. Insert a Variable
You can insert a variable with a keyboard shortcut or with the toolbar. In both cases, you must select the variable from the menu. Text you type yourself isn't recognized as a variable.
Use a keyboard shortcut
| Type | Opens |
| {{ | Full variable menu |
| {{r | Read Value from ATS list |
| {{u | Update Value to ATS list |
For example, to insert a Read variable:
- Type {{ where you want the variable to appear.
- Choose Read Value from ATS from the menu. You can also type {{r and search for the variable.
- Type the variable name to search for a field. The list is filtered based on your search. For example, type "job" to see all job fields.
- Use the arrow keys to move through the list, then press Enter to insert the variable. Press Esc to close the menu.
If you opened the full variable menu, you can choose Read Value from ATS, Update Value to ATS, or Response from Data Collection.
Use the toolbar
- Place your cursor where you want the variable to appear.
- Click Read Variable or Update Variable.
- Search for the variable and select it.
The variable appears as a colored chip at your cursor position. The legend at the bottom of the panel shows what each color means.
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.
Remove a Variable or Clear Instructions
- To remove a variable, place your cursor immediately after it and press Backspace.
- To delete everything in the editor, click Clear.
- To close the menu, press Esc.
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.
Add Instructions to a Module
The Instructions section is available in Greetings, Data Collection, Screening and the Agent Characteristics modules. You can follow the steps below to add instructions to a module:
- Go to AI Agents and open the agent you want to update.
- On the Build tab, click the module you want to add instructions to.
- In the Instructions section, click to add instructions. If the module already has instructions, click Edit. The Instructions panel opens.
- Type your instruction. Write each rule as a short condition and action.
- Insert the variables and collected data your rule needs. See Insert a Variable below.
- Review your instructions, then click Save.
Review Your Instructions
- Hover over a variable to see its name and the record it belongs to, for example, "Medix Process Status of the owner for the candidate".
- Hover over Variables Used at the bottom of the panel to see all variables used in your instructions.
- Check the character count. Each module's instructions can contain up to 6,000 characters.
After You Save
After you click Save, the module shows your instructions in a read-only view. You can scroll to read longer instructions. To make changes, click Edit to reopen the Instructions panel. The agent follows your instructions the next time it runs that module.
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 |