Skip to content
Optima docs
Guides

Score customers with a continuous agent

Build an agent that rates the churn risk of every customer who has ordered, check its cost, test it in dry run, then go live.

By the end you will have an agent that sets a churn_risk attribute (low, medium or high) on every profile in a "Customers with orders" segment, and keeps it current.

Before you start

  • An active text model; see AI models, and the agents_editor role (it also lets the agent read the segment you pick). To read the log you also need agents_auditor or an administrator role.
  • A segment named Customers with orders, and a text attribute churn_risk on the profile entity.
  • A purpose your own user holds, for example the one your marketing analysis runs under.
  • Your own roles must let you write customer data (data_editor or an administrator role), because the agent acts as you.

Steps

  1. Create the definition. Under Agents, Definitions, New definition. Name it Churn risk. Prompt: "Rate how likely this customer is to stop buying: low, medium or high. Use the order count, the date of the last order and the recent orders. Set churn_risk and explain your rating."
  2. Add a continuous trigger. Choose Add continuous trigger. Set Works through to Profiles in a segment and pick Customers with orders. Leave the sweep schedule daily.
  3. Choose what it reads. Under Attributes the agent reads add orders_count and last_order_at. Under Recent events of these types add order_placed and set Last N events per type to 10.
  4. Refresh. Set Refresh results older than (days) to 30 so that every rating is renewed monthly even if the profile did not change.
  5. Allow the write. Under Actions add the attribute churn_risk with Allowed values low, medium, high, and choose the purpose. Save the definition.
  6. Create an instance from it, with a budget you are comfortable with. See instances.
  7. Run the preview. On the instance choose Run preview. When it finishes, read Full pass ≈ … tokens and the cost. If that is more than you want to spend, lower the budget or cut the attributes the agent reads, and preview again. The preview saves no rating, but it spends real tokens on 20 profiles and leaves Would have entries in the run log. Plan for the estimate twice if you dry-run a full pass first: going live later processes the profiles the dry run saw again.
  8. Start in dry run. Choose Start dry run. The card shows the first pass advancing. No rating is saved to any profile.
  9. Read the log for one profile. Open Run log, enter a profile id in the Profile box and read the Would have entry, which says "Would set churn_risk to …" with the rating, and the explanation behind it. Once live, the entry says "Set churn_risk".
  10. Go live. When the ratings look right, choose Switch to live and confirm. Going live processes again the profiles only the dry run saw: the card says that at the next sweep the agent processes again, live, what the dry run covered, and those profiles are rated again, live, over the next sweeps, which costs those tokens a second time. The card keeps saying it is up to date unless the first pass was still running.

Check that it worked

Open a rated profile: churn_risk holds a value, and the log entry for it says Set. Every profile the dry run rated is rated again when you go live, and new customers joining the segment are rated within a day.

If something goes wrong

  • Start is disabled. Run a preview first; see continuous agents.
  • The sweep is paused. The budget window is used up. It continues when the window resets; nothing is lost.
  • Some customers have no rating. They have not consented to the purpose and are skipped, or their rating failed; look for Item failed entries in the log. Failed profiles are tried again within a day.

On this page