> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lessons

> Teach your storefront agent how you like to sell, in your own words, and stay in control of what it learns.

## 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

1. **You notice something in a conversation.** In [Sessions](https://docs.apostra.com/v3/sessions.md),
   read what a buyer asked and what your agent answered, then leave a private
   note.
2. **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.
3. **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_preview` usage. That
   record contains no brief, lesson, product or conversation content.
4. **An administrator approves it.** Until then, the lesson does nothing.
5. **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.
6. **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.

You can also propose a lesson directly, without starting from a note.

## Briefs from a sandbox advertiser

A buyer can send briefs from a [sandbox advertiser](https://docs.apostra.com/v3/account-access.md#sandbox-advertisers-and-live-spend)
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 with `accountId` when you use `save_lesson`; see
[Name the account on every call](https://docs.apostra.com/v3/name-the-account.md). 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

> [card] [Sessions](https://docs.apostra.com/v3/sessions.md)
>
> Read your agent's conversations and leave private notes

> [card] [Seller workflows](https://docs.apostra.com/v2/setup/v3/seller-workflows.md)
>
> Set up and operate your Seller Account


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.