# Write instructions the agent can follow > Write complete HeyRik agent instructions covering identity, language, context, conversation order, knowledge, tools, guardrails, recovery, handoff, and closing. Source: https://www.heyrik.com/docs/academy/write-instructions Build one readable instruction document covering identity, language, known context, conversation order, knowledge and tools, guardrails, recovery, and closing. 18 minute lesson Outcome: A complete, testable instruction document Follow along in your workspace.[Open dashboard](https://www.heyrik.com/assistants) ## By the end of this lesson You will replace the generated prose with one complete, structured instruction document. Another reviewer should be able to predict the agent’s behavior for the happy path, correction, missing facts, human requests, silence, opt-out, and closing by reading it. ## Open the instruction document Dashboard → AI Agents → Property Enquiry Assistant → Assistant Details. 1. ### Open the Draft agent Confirm the Live control is off before changing behavior. 2. ### Stay in Assistant Details Scroll below Voice, Languages, and Greeting to the prompt document. 3. ### Click inside the instruction document It is edited as one readable Markdown-like document with headings. Enabled sections are saved as ordered prompt sections. 4. ### Copy the current content somewhere temporary Keep it only for comparison or rollback; do not mix duplicate generated sections into the reviewed prompt below. ## Use all eight instruction levels Each heading owns one type of behavior. This keeps revisions narrow and makes omissions visible. 01 ### Identity & Purpose Business, audience, one job, success condition, and primary limitation. **Avoid:** You are a helpful assistant. 02 ### Language & Tone Starting language, switching rule, turn length, vocabulary, and confirmation style. **Avoid:** Sound natural and professional. 03 ### Known Context Declared inputs, when they may be used, and unresolved-placeholder behavior. **Avoid:** Assume the caller’s details are known. 04 ### Conversation Flow Ordered questions, branches, corrections, refusals, confirmation, and completion. **Avoid:** Collect all required information. 05 ### Knowledge & Tools Which claims require approved sources and when a configured action may run. **Avoid:** Use your knowledge and tools. 06 ### Guardrails & Handoff Prohibited behavior, human triggers, and the fallback when transfer is unavailable. **Avoid:** Do not hallucinate; escalate when needed. 07 ### Recovery Confusion, silence, correction, refusal, wrong person, opt-out, and unsafe behavior. **Avoid:** Handle edge cases gracefully. 08 ### Closing Confirmed summary, real next action, correction invitation, thanks, and end. **Avoid:** End when done. ## Paste the complete reviewed prompt This example uses the variables created in Lesson 3 and the knowledge source you will attach in Lesson 5. **Complete property-enquiry instructions** ``` ### Identity & Purpose You are the inbound property-enquiry assistant for {{company_name}}. Your only job is to understand the caller's property requirements and, when appropriate, obtain permission for a property expert to follow up. Success means the caller confirms the captured requirements and the next action. Do not pressure the caller or claim that a property is available. ### Language & Tone Start in English. If the caller speaks Telugu, continue in Telugu. Use short, warm sentences and ask one question at a time. Repeat important amounts, dates, phone numbers, and locations for confirmation. Do not use internal terms such as "lead", "CRM", "variable", or "qualification score" with the caller. ### Known Context The business name is {{company_name}}. The caller's name may be {{customer_name}}. Use it naturally only when a value is available. Never read an unresolved placeholder aloud. ### Conversation Flow 1. Identify the business and ask how you can help. 2. Confirm whether the caller wants a flat, villa, plot, or something else. 3. Ask the approximate budget or budget range. 4. Ask the preferred location. 5. Ask when they plan to buy. 6. Ask one relevant clarification only when an answer is ambiguous. 7. Summarize the property type, budget, location, and timeline. 8. Ask whether the summary is correct. 9. Ask for permission to arrange a follow-up from a property expert. If the caller corrects an answer, acknowledge the correction, replace the value, and confirm the revised value before continuing. If the caller refuses a nonessential question, continue without it. Do not repeatedly pressure them. ### Knowledge & Tools Use attached knowledge for project names, pricing, amenities, locations, and policies. Use a configured tool only for the action described by that tool and only after collecting and confirming its required inputs. If approved knowledge or a configured tool does not provide the answer, say that a property expert must confirm it. Never estimate price, availability, legal status, or investment returns. ### Guardrails & Handoff Never invent facts, make financial guarantees, request passwords, one-time codes, or payment-card information, or claim a human action happened when it did not. Transfer only when transfer is enabled and the caller asks for a person, becomes distressed, or needs information the agent cannot safely provide. If transfer is unavailable, capture the reason and offer a human follow-up. ### Recovery If the caller does not understand a question, rephrase it once using simpler words. If the caller is silent, follow the configured silence prompts and retry limit. If this is the wrong person or the caller asks not to be contacted, apologize, record the outcome, and end without continuing the flow. If the call becomes abusive or unsafe, end politely according to business policy. ### Closing Summarize the confirmed requirements and the agreed next action. Do not say a follow-up is booked unless the caller agreed and a configured action confirmed success. Ask whether anything needs correction, thank the caller, and end naturally. ``` ## Enter the prompt without creating duplicate rules The document should contain one copy of each heading and one coherent sequence. 1. ### Select the generated instruction document Replace the generated content with the complete reviewed prompt rather than appending a second flow beneath it. 2. ### Keep each ### heading on its own line The product saves the document as ordered prompt sections, using headings to separate responsibilities. 3. ### Check variable chips company\_name and customer\_name should resolve to declared Input variables. Create or repair them in Variables rather than deleting the placeholders silently. 4. ### Leave factual values out Do not paste project prices, live availability, or changing policy into the prompt. Lesson 5 attaches those facts as knowledge. 5. ### Wait for the saved state Navigate away and back only after the builder confirms the edit is saved. **A prompt cannot complete an external action** The instruction “book a visit” or “create a follow-up” does not connect a calendar, CRM, or Custom API. Without a confirmed action, the prompt must describe the result as a request or consent—not a completed booking. ## Verify the instruction document Use text search and a spoken read-through before starting a test call. Complete lesson 4: Write instructions **Complete this lesson**Loading saved progress · Checking saved progress… 0 of 9 **01**The document contains exactly one Identity, Language, Known Context, Flow, Knowledge, Guardrails, Recovery, and Closing section.**02**The primary job and successful completion condition are explicit.**03**The agent asks one question per turn and confirms amounts, dates, numbers, and locations.**04**Corrections replace and reconfirm the old value instead of continuing with stale data.**05**Missing knowledge triggers a limitation and human path, never an estimate.**06**Transfer happens only when enabled and its condition is met; an unavailable transfer has an honest fallback.**07**Wrong person and do-not-contact requests stop the flow.**08**The closing distinguishes confirmed actions from requests or consent.**09**Every placeholder has a declared input and every required output is named in Variables. ## Common instruction mistakes Long prompts fail from contradiction and vagueness more often than from lack of words. ### Appending to the generated flow Correct it Replace duplicated or conflicting content with one reviewed hierarchy. ### Writing facts into behavior Correct it Move prices, hours, project details, and policies into an approved knowledge source. ### Saying “never hallucinate” Correct it Name the missing-fact trigger and the exact safe response. ### Writing a rigid script Correct it Define order, decisions, and recovery while allowing natural caller wording. ### Promising tool success Correct it Require a confirmed integration response before saying an action happened. ### Forgetting refusal and correction Correct it Describe how to skip nonessential data and replace corrected values. ### Mixing input and output variables Correct it Inputs are supplied before a call; outputs are extracted from what the caller confirms. API equivalent ### The instruction document is config.prompt\_sections `PATCH /agents/{id}`[Open reference](https://www.heyrik.com/docs/api-reference/agents/patch-agents-id-edit-an-agent-any-field-or-section) Send ordered objects with `title`, `content`, `order`, and `enabled`. Enabled sections compile from lowest order to highest. A patch to `config.prompt_sections` replaces the full current flow, so include every section the agent should retain. New instructions apply to the next call.