What a lesson is
A lesson is short guidance, in your own words, that your storefront agent follows when it answers matching briefs. For example: “For stationery brands, lead with the lifestyle video package.” Or: “Keep proposals for budgets under $10,000 to two products.” Lessons replace writing a long Playbook. You teach the agent one point at a time, from real conversations, and decide what it keeps.How a lesson is made
- You notice something in a conversation. In Sessions, read what a buyer asked and what your agent answered, then leave a private note.
- You select Teach this on the note. Your assistant proposes a lesson that keeps your note’s words exactly. It suggests who the lesson applies to: one advertiser, category, channel, market, or every brief. If that is not clear from your note, it asks you.
- You preview it. The preview runs the original brief twice, once without
the lesson and once with it. It shows changes to the opening line, products,
bundles, and whether the agent would pitch or pass. A preview changes
nothing about your agent or Sessions, and is never sent to a buyer. Two runs
of the same brief can differ slightly, so treat small differences as noise.
We measure the model cost of each preview as
lesson_previewusage. That record contains no brief, lesson, product or conversation content. - An administrator approves it. Until then, the lesson does nothing.
- It shapes future answers. When a later brief matches the lesson, your agent follows it. The answer is marked Taught by lesson in the Session, with the lesson’s words.
- An administrator can retire an active lesson at any time. A retired lesson stops shaping new answers straight away. Retired lessons stay in the record and cannot be approved again; propose a new lesson if you want to use that guidance again.
Briefs from a sandbox advertiser
A buyer can send briefs from a sandbox advertiser to test your storefront. Your agent answers them in full, but it does not learn from them. A sandbox brief does not count in the history your agent reads to decide how to sell, such as how often briefs book, and it does not move your agent’s learned default posture. What you teach is unaffected. A note on a sandbox brief can still become a lesson, and an approved lesson shapes later live briefs like any other. Briefs recorded before sandbox briefs were marked count as before.Who can do what
- Anyone on your seller team can write notes and propose lessons from them.
- Only an administrator of your seller account can approve or retire a lesson.
- Approval and retirement must be done by that person, signed in as themselves. Apostra staff cannot approve lessons for you, and nobody can approve while acting on someone else’s behalf.
- If you work in more than one account, you can propose from a note only where you are a direct member of the seller account the call names. A direct account administrator can also approve or retire there.
- Notes and lessons are private to your seller account.
What buyers see
Buyers never see your lessons, notes, or the wording of your rules. Your agent’s answer to a buyer is written in market terms. If a lesson leads it to leave something out, the buyer sees that it is not part of the proposal, not your reason.Limits
- A lesson can be up to 500 characters.
- Up to 12 approved lessons can shape one answer. The most specific wins: one buyer, then one advertiser, then a category, channel, or market, then every brief.
- Lessons about pricing or when to decline can be proposed and previewed, but cannot be approved yet. Prices and floors in your pricing settings always take priority over lessons.
Availability
Every seller storefront can use Lessons. Name the Seller Account withaccountId when you use save_lesson; see
Name the account on every call. V3 save_playbook turns Playbook
text into proposed Lessons for review. V2 operating-instructions writes keep
their direct create and activate behaviour, except for storefronts that had
the Lessons pilot enabled, which retain the earlier conversion behaviour.
Related
Sessions
Read your agent’s conversations and leave private notes
Seller workflows
Set up and operate your Seller Account