HeyRik DocsAcademyLesson 4 of 8
Lesson 4 of 8

Write instructions the agent can follow

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
In this lessonOutcome

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.

What done looks like

You can demonstrate the lesson result in the dashboard and complete its practical checklist before continuing.

01

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.

02

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.
03

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.
04

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.

05

Verify the instruction document

Use text search and a spoken read-through before starting a test call.

Complete lesson 4: Write instructions
Complete this lessonLoading saved progress · Checking saved progress…
0 of 9
06

Common instruction mistakes

Long prompts fail from contradiction and vagueness more often than from lack of words.

Appending to the generated flow

Why it fails

It leaves behavior, data, or ownership ambiguous.

Correct it

Replace duplicated or conflicting content with one reviewed hierarchy.

Writing facts into behavior

Why it fails

It leaves behavior, data, or ownership ambiguous.

Correct it

Move prices, hours, project details, and policies into an approved knowledge source.

Saying “never hallucinate”

Why it fails

It leaves behavior, data, or ownership ambiguous.

Correct it

Name the missing-fact trigger and the exact safe response.

Writing a rigid script

Why it fails

It leaves behavior, data, or ownership ambiguous.

Correct it

Define order, decisions, and recovery while allowing natural caller wording.

Promising tool success

Why it fails

It leaves behavior, data, or ownership ambiguous.

Correct it

Require a confirmed integration response before saying an action happened.

Forgetting refusal and correction

Why it fails

It leaves behavior, data, or ownership ambiguous.

Correct it

Describe how to skip nonessential data and replace corrected values.

Mixing input and output variables

Why it fails

It leaves behavior, data, or ownership ambiguous.

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

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.