The quality of the AI's responses depends directly on the quality of the instruction you give it. A well-written instruction tells the AI what it needs to achieve, how to do it, and with what information, so it doesn't have to guess. Just as a chef needs a clear recipe to bake the perfect cake, the AI needs precise, complete guidance to respond well to your customers.

Did you previously know it as "AI Agent"? The AI Instructions block is the same one that used to be called "AI Agent". We renamed it to set it apart from the new AI Agents in Botmaker 3.0. The best practices in this article still apply.

You can:

• Understand what an instruction is and why it determines the AI's results.
• Apply six rules to write clear instructions without contradictions.
• Know what goes in each field of the block: Role, Objective, Instructions, Tone and style, and Don't talk about.
• Test and fine-tune your instructions until you get the responses you're looking for.

Key rules for writing effective instructions

To make the rules easy to follow, all the examples use the same case: a store that wants to answer questions about its business hours.

1. Define the objective clearly

Before you start writing, ask yourself what you want the block to achieve by the end of the conversation. A clear objective steers every response in the right direction and keeps the AI from drifting into topics you don't care about.

Write a single, concrete objective in one sentence. If you feel you need several objectives, you're probably better off using more than one block.

Example: "Answer customer questions about the store's business hours."

2. Break the request into clear steps

Organize what the AI needs to do into simple, sequential steps. That way, the AI handles the task one part at a time and the conversation follows a logical order, instead of cramming everything into a single message.

1. Greet the customer by name.
2. Tell them the current business hours.
3. Offer additional information if they ask for it.

3. Provide the necessary context

Include all the information the AI needs that you take for granted: details about your company, who it's talking to, formatting limits, and special cases. The AI can't guess what you don't tell it, and if it's missing a piece of information, it may make it up.

Example: "Our store has different hours on weekends. State this clearly in the response."

Note: if the information is extensive or changes often (for example, a catalog or a list of locations), upload it to a knowledge base and connect it by typing $ in the Instructions field. That way, it doesn't use up characters in the instruction and you only need to update it in one place.

4. Avoid ambiguity and contradictions

Check that no guideline conflicts with another. When two rules contradict each other, the AI has to choose which one to follow, and the result becomes unpredictable. Replace vague words ("brief", "quick", "quite") with concrete, measurable criteria.

Not recommended: "Respond briefly, but also explain everything in detail."

Recommended: "Respond in three lines or fewer, explaining the schedule changes concisely."

5. Include examples for complex cases

When a response needs to follow a specific format or criterion, show the AI an example of a correct response and an example of an incorrect one. Examples make it clear what you expect and reduce misinterpretations.

Correct example: "Our business hours are Monday to Friday, 9 a.m. to 6 p.m., and Saturdays, 10 a.m. to 4 p.m."

Incorrect example: "We're open every day."

6. Test and fine-tune the instruction

Writing instructions is a process of trial and error. After you save the block, click Test in the Bot Designer's top bar and chat with your bot the way a customer would. If a response isn't what you expected, identify which part of the instruction caused it, adjust it, and test again.

Tip: test the same instruction several times and with different questions. Change one detail at a time so you know exactly which change improved (or worsened) the response.

Full example

Here's how the Instructions field would look for the store case, applying all the rules:

1. Greet the customer by name.

2. Ask which location they want to know the hours for.

3. Tell them that location's hours: Monday to Friday, 9 a.m. to 6 p.m., and Saturdays, 10 a.m. to 4 p.m. The store is closed on Sundays.

4. If they ask about holidays, tell them the hours are the same as on Saturdays.

5. Respond in three lines or fewer per message.

6. Before saying goodbye, ask if they need anything else.

Example of a correct response: "Hi, Ana! The Downtown location is open Monday to Friday, 9 a.m. to 6 p.m., and Saturdays, 10 a.m. to 4 p.m. Is there anything else you need?"

Example of an incorrect response: "We're open every day."

Notice that the instruction has numbered steps (rule 2), concrete business details (rule 3), a measurable length criterion (rule 4), and sample responses (rule 5). After that, all that's left is to test and fine-tune it (rule 6).

Important considerations

• Each field has a character limit: Role and Objective accept up to 300 characters; Instructions, up to 4,500. If you run out of space, move extensive information to a knowledge base.
• The AI only knows what you give it: if you don't provide a piece of information, the AI may make it up. When in doubt, include the information or tell it what to say when it doesn't have it (for example, "if you don't know the answer, offer to transfer the customer to an agent").
• Longer isn't better: a well-organized instruction without contradictions works better than a long one with repeated guidelines.
• Changes show up when you publish: after testing and saving, click Publish so your customers get responses based on the new instruction.

Remember to visit our Help Center for further information.