Skip to main content
Agent Instructions are the part of the agent you write yourself. Popcorn adds the rest at reply time: your Knowledge Base folders, 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 the AI Instruction Builder drafts 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 the 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 without Handover cannot hand over, however clearly the instructions ask it to.

​
What to write

The onboarding agent and the AI Instruction Builder both use the same 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 calls a folder’s search 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.” The AI Manager, if you switch it on, scores replies partly on whether they invent facts that are not in the Knowledge Base (see AI Manager).
  • “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

​
Generate instructions with the AI Instruction Builder

The sparkle icon on the Agent Instructions field opens the AI Instruction Builder. It turns a plain-language description into a full instruction set in the four-part structure above. If the field already contains instructions, the same icon opens Improve Instructions instead: your text appears under Current Instructions with its Instruction Quality checklist, Improve with Feedback lets you describe what to change, and Restructure Format (shown while the quality score is below 80%) reorganises what you have into the four sections without removing information. Use These Instructions writes the result back into the field.
1

Describe the agent

Pick a starting point under Start with a Template (Customer Service, Sales Assistant or Technical Support) and edit it under Your Description, or write your own: what the agent does, its role, tone and limits. Two or three sentences are enough; a single word such as “assistant” is rejected and nothing is generated, so add more detail and try again.
2

Generate

Click Generate Instructions. The draft appears under Generated Instructions with an Instruction Quality score. The score is a checklist of five points: Clear agent role definition, Specific tasks and capabilities, Consistent tone and style, Clear limitations and guardrails, Contains helpful examples.
3

Refine if needed

Improve with Feedback lets you type what to change (“add an example for returns”, “make the tone more formal”). Unmet checklist points are offered under Suggested Improvements; click one to add it to your feedback. Edit Description goes back to your description.
4

Use the result

Click Use These Instructions. The text replaces whatever was in Agent Instructions. Read it once: the generator writes placeholders such as the company name from your description, so correct anything it guessed.
The generated 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, Product Recommendations, Checkout and Handover switched on, and a “Policies” folder in the Knowledge Base:
Why it works:
  • Line 2 of the tasks makes the agent search the “Policies” folder before answering, which is the only way it can quote the real return policy.
  • Lines 3 and 4 only work because Product Recommendations and Checkout 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 Use custom handover instructions 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 & review, publish, then use Test Agent and reset the conversation before you try it. To see how a published version performs over time, open Spotlight.