Skip to main content
Instructions are the part of the agent you write yourself. Popcorn adds the rest at reply time: your knowledge bases, the capabilities you switched on, the customer’s details and the date. Instructions work best when they tell the agent how to use those things, not when they try to replace them. This page explains what the agent already knows, what to write, and how Draft with agent writes instructions for you.

​
What the agent gets besides your instructions

Every reply starts from your instructions plus context Popcorn adds automatically: Two consequences:
  • Do not paste product prices, stock or policies into the instructions. Put them in a knowledge base or keep them in your store; the instructions should tell the agent to look them up.
  • Do not describe actions the agent has no tool for. An agent with Hand over to your team off cannot hand over, however clearly the instructions ask it to.

​
What to write

The onboarding agent and Draft with agent use the same four-part structure. Cover these four parts, in this order:
Who the agent is, for which business, for which products or services, and in what manner. One or two sentences: “You are a customer service representative for Noor Perfumes. You help customers with orders, delivery and returns in a warm, professional way.”
Tell the agent to answer greetings directly, to search the knowledge base before answering any question about products, services or policies (even questions that look off-topic), to use what it finds as-is, and what to say when the knowledge base has nothing: for topics outside your business, a short “I don’t have details about that” plus an offer to help with what you do sell; for topics inside your business, the tool to use (for example handing over to your team).
Tone, language, length and pacing. The onboarding instructions ask for replies under 50 words, one question at a time, and the customer’s own language. If you want Arabic replies in a specific dialect, say so here.
What the agent must not do: invent facts, add its own requirements or promises beyond the knowledge base, claim it forwarded or processed something without using a tool, collect data you do not want collected, or make commitments on the company’s behalf.

​
Rules that reflect how Popcorn works

These lines are worth keeping in any instruction set because the rest of the product depends on them:
  • “Search the knowledge base before answering questions about products, services or policies.” The agent only searches a knowledge base when it decides to; this line makes it decide to.
  • “When the knowledge base says to forward or hand over, use the handover tool. Never say you have done something unless you used a tool to do it.” Without this, an agent can tell a customer “I’ve passed this to the team” while nothing happened.
  • “Use only the facts you found. Do not add suggestions, requirements or outcomes that are not in the knowledge base.” Check replies before sending, if you switch it on, scores replies partly on whether they invent facts that are not in the knowledge base (see Check replies before sending).
  • “Reply in the customer’s language.” The agent replies in whatever language the instructions and the customer lead it to, so state the rule explicitly.

​
What belongs elsewhere

​
Draft instructions with the agent

The Draft with agent button under Instructions turns a plain-language description into a full instruction set in the four-part structure above. It works the same on the Create agent page and on an existing agent’s Instructions tab. If the field is empty, the dialog opens as Draft instructions with the agent. If the field already has instructions, it opens as Improve instructions with the agent and shows them as Current instructions.
1

Describe the agent

Pick a starting point under Start from an example (Customer service, Sales or Technical support) and edit it under What should your agent do?, or write your own: your store, what customers ask about, and when to involve your team. Two or three sentences are enough. A single word such as “assistant” is rejected and nothing is written, so add more detail and try again. Click Draft instructions.
2

Review the draft

The draft appears under Draft, with the dialog titled Review the draft. Edit description goes back to your description.
3

Refine if needed

Say what to change asks What should change? (“use a warmer tone and mention our free delivery offer”); anything you do not mention stays as it is. Under Or add a suggestion, click one of Make the agent’s role and store clearer, List the main tasks step by step, Set a friendly, clear tone, Say what the agent must not do or Add example replies to add it to your note, then click Improve instructions. Restructure reorganises what you have into four sections (Role and Context, Primary Tasks, Communication Style, Limitations) and is asked to keep all your information.
4

Use the result

Click Use these instructions. The text replaces whatever was in Instructions; the button appears once the text differs from what you opened the dialog with. Read it once: the generator writes placeholders such as the company name from your description, so correct anything it guessed.
If it cannot write a draft you see Couldn’t write instructions. Try again. Nothing reaches the page until you click Use these instructions. The text is not saved until you save the agent, and reaches customers only after you publish.

​
Example

A sales agent for a perfume store with a connected Shopify store, Recommend products, Take orders in chat and Hand over to your team switched on, and a “Policies” knowledge base:
Why it works:
  • Line 2 of the tasks makes the agent search the “Policies” knowledge base before answering, which is the only way it can quote the real return policy.
  • Lines 3 and 4 only work because Recommend products and Take orders in chat are on; they steer the agent to the tools rather than describing products by hand.
  • Line 5 pairs a rule with the handover tool. If you also want a specific trigger such as “any mention of a wrong item”, put it under Add your own handover rules so it is attached to the tool itself.
  • Nothing in it duplicates data that lives in the store or the knowledge base.

​
Check the result

Instructions apply only to the published version. After editing, click Save and review, publish, then use the test chat and start a new conversation before you try it. To see how a published version performs over time, open Spotlight.