Instructions are the plain-English brief that tells your agent what to do — the single most important part of every agent. Set up your trigger first (see Set up your agent's trigger); what it delivers shapes what your instructions describe.
What are instructions?
Instructions are a free-text field in the agent builder where you describe the agent's job — like briefing a new staff member. The agent reads them every run and uses them, along with the tools you've added, to decide what to do.
The five things every good set of instructions includes
What triggers this agent and what information it will receive
Start by telling the agent what it's responding to. Reference the trigger event in plain language — for example, "a new patient is created in Athena Health" or "a new intake form is submitted in JotForm." The agent receives the event's data as context, so describe what's in it.
"This agent runs when a patient submits a new intake form in JotForm. The form includes the patient's full name, date of birth, phone number, email address, chief complaint, and insurance information."
What the agent should do, step by step
Be explicit about each step. Don't assume the agent will infer the right sequence — spell it out.
"1. Check whether a patient with this date of birth and name already exists in Athena Health.
2. If the patient exists, update their contact information with any new details from the form.
3. If the patient does not exist, create a new patient record in Athena Health using the form data.
4. Send the patient a welcome SMS via Spruce Health confirming their intake was received."
How to handle edge cases and decisions
Think about what could go wrong or be ambiguous, and tell the agent how to handle each case.
"If the insurance information is missing or incomplete, skip the insurance verification step and add a note to the patient record in Athena Health saying 'Insurance information pending.'
If more than one matching patient is found, do not create a duplicate. Add a note to the oldest matching record and stop."
What a successful run looks like
Describe what "done" means. This helps the agent recognise when to stop.
"The agent has completed its job when: the patient record has been created or updated in Athena Health, and the patient has received a confirmation SMS via Spruce Health."
Guardrails — keep the agent from getting stuck or going off the rails
Even with clear steps, things go wrong — tools return errors, systems lag, records can't be found. Tell the agent how to handle these mechanical failures so it doesn't loop forever or send the same SMS twice.
Cover three things:
- Retry limits — how many times the agent should try a failing step before giving up.
- Loop prevention — caps on how many times the agent can call the same tool, or how many steps it should take overall.
- Stopping conditions — what to do when it gets stuck, and where to escalate.
"If a tool returns an error, retry up to 3 times. If it still fails, stop the run and post to the #ops-alerts Slack channel describing what went wrong.
Do not call the same tool more than 5 times in a single run. If you've already sent a patient SMS in this run, do not send another one — even if a later step seems to call for it.
If you can't make a confident decision after gathering information from your tools, stop and post a summary to #ops-review for a human to handle."
Why this matters in healthcare: Without guardrails, an agent that keeps retrying could send duplicate SMS messages to a patient, create duplicate records, or run indefinitely on a stuck step. Guardrails are how you keep small bugs from becoming patient-facing problems.
Full example: Patient intake agent
Here's a complete set of instructions covering all five sections — trigger context, steps, edge cases, success, and guardrails:
Agent name: New Patient Intake Processor
Trigger context: This agent runs when a patient submits a new intake form in JotForm. The form includes: full name, date of birth, phone number, email address, chief complaint, and insurance information.
Steps:
- Search for an existing patient in Athena Health using the patient's date of birth and last name.
- If no match is found, create a new patient record in Athena Health with all available form fields.
- If a match is found, update the existing record with the phone number and email from the form.
- Send a confirmation SMS to the patient's phone number via Spruce Health: "Hi [first name], we've received your intake form. Our team will be in touch shortly to confirm your appointment."
- Post a message to the #new-patients Slack channel with the patient's name, chief complaint, and the link to their Athena Health record.
Edge cases:
- If insurance information is missing or incomplete, skip the verification step and add a note to the patient record saying "Insurance information pending."
- If more than one matching patient is found, do not create a duplicate. Add a note to the oldest matching record and stop.
Success: The agent is done when the patient record exists in Athena Health with the latest form data, the confirmation SMS has been sent via Spruce Health, and the Slack message has been posted.
Guardrails:
- Retry any failing tool call up to 3 times before stopping.
- Do not send more than one SMS to the same patient in a single run, even if a later step seems to call for it.
- If the agent can't complete a step after 3 retries, post a summary to #ops-review and stop — do not loop.
Bonus: Instructions starter template
A copy-paste-ready scaffold for the Instructions field in the Keragon agent builder. Mirrors the five-essentials framework above.
How to use:
- Copy the block below.
- Paste it into the Instructions field on your agent.
- Replace everything in <angle brackets> with your specifics.
- Delete any line you don't need. Keep the section labels — they help the agent (and your teammates) read the brief.
TRIGGER CONTEXT This agent runs when <describe the trigger event — e.g. "a new patient submits an intake form in JotForm">. The event includes: <list the fields the agent will receive>. STEPS 1. <First step — name the app and the action, e.g. "Search for an existing patient in Athena Health using date of birth and last name."> 2. <Second step> 3. <Continue with one numbered step per action> EDGE CASES - If <describe an ambiguous or unexpected situation>, <what the agent should do instead>. - If <another edge case>, <fallback behaviour>. SUCCESS The agent has completed its job when: - <First success condition> - <Second success condition> GUARDRAILS - Retry any failing tool call up to 3 times before stopping. - Do not call the same tool more than 5 times in a single run. - Do not <describe an action that should not repeat — e.g. "send more than one SMS to the same patient"> in a single run. - If you can't complete a step, post a summary to <Slack channel or escalation path> and stop. Do not loop.
Notes
- Section labels are part of the brief. Keep TRIGGER CONTEXT, STEPS, EDGE CASES, SUCCESS, GUARDRAILS as plain-text headings — they help the agent parse the structure and help your teammates read it later.
- Be explicit with app names. Write "in Athena Health" not "in the EHR" — the agent uses the named app to pick the right tool.
- Default guardrails are conservative. The 3-retry / 5-call limits are sane defaults for most healthcare flows. Tighten them for high-stakes actions (e.g. payment, prescription), loosen them for low-stakes reads.
- PHI stays out of the template. Patient data flows in at runtime through the trigger and tools — never paste real patient information into the Instructions field.
See also
- Write your agent's instructions (help center) — the five-essentials framework, examples, and common mistakes
- Set up your agent's trigger (help center) — what your trigger delivers shapes the trigger-context block
- Add tools to your agent (help center) — the tools you connect determine what actions your steps can reference
Common mistakes to avoid
Too vague: "Check the patient record and do the right thing." — The agent doesn't know what "the right thing" is. Always specify exact steps.
Assuming the agent knows your system: "Update the patient like we usually do." — The agent has no prior knowledge of your team's conventions. Write it out explicitly.
No edge case handling: If you don't tell the agent what to do when something unexpected happens, it will either stop or make a guess. Always include a fallback for the most common failure scenarios.
Too long and unstructured: A wall of text with no numbered steps makes it hard for the agent to follow the right sequence. Use numbered steps for the main workflow.
Tips for healthcare contexts
- Name the app explicitly. Don't write "update the patient record" — write "update the patient record in Athena Health." The agent uses this to know which tool to call.
- Avoid PHI in the instructions themselves. Your instructions are a template, not a record. Patient data flows in at runtime through the trigger and tools.