Decision engine
Picks the best option for each user by learning from behavior. An A/B test picks a single winner; the decision engine sees the differences between user groups and keeps learning.
Picks the best option for each user by learning from behavior. An A/B test picks a single winner; the decision engine sees the differences between user groups and keeps learning.
Manage it from the Decision Engine page in the dashboard or via the API.
POST /v1/apps/{appId}/decision-agents
Authorization: Bearer <admin-scoped key>
{
"slug": "teklif",
"name": "Offer selection",
"arms": [{ "id": "indirim", "label": "10 percent off" }, { "id": "kargo", "label": "Free shipping" }],
"reward_events": ["purchase"],
"reward_window_hours": 72,
"holdout_percent": 10,
"context_prediction": "kayip",
"use_best_channel": true
}| Field | Description |
|---|---|
arms | 2–8 options. They cannot be changed later, because learning is tied to them. Create a new agent for new options |
reward_events | Events that count as success |
reward_window_hours | How long a reward is awaited after a decision, 1–720 hours, default 72 |
holdout_percent | Randomly assigned control share, 0–50, default 10 |
context_prediction | Optional prediction model short name: the agent learns separately per score bucket |
use_best_channel | Uses the best channel as context |
Using it in a journey
Add the Smart decision step and select the agent. Each option becomes a separate handle. The step does not send a message; add a send step with its own content to each handle. Preference and suppression rules are applied at the send step.
If the agent is paused or deleted, the user goes to the Unreachable handle. Do not leave handles empty.
Using it from your app
POST /v1/apps/{appId}/decision-agents/{id}/decide
Authorization: Bearer <notifications:write-scoped key>
{ "external_id": "musteri-42" }The response returns arm_id, label, policy and context. The decision is recorded, and the agent learns as reward events arrive.
How it decides
Thompson sampling is used: a probability distribution is kept for each option's success rate, a sample is drawn from each distribution, and the highest sample wins. A rarely tried option gets a chance because it is uncertain, and a proven option pulls ahead. No language model is used, and no personal data leaves the system.
- If a context has fewer than 30 resolved trials, the overall statistics are used.
- Only resolved trials count: those that received a reward or whose window has closed. A trial in progress is not counted as a failure.
- Data from the last 90 days is used: when behavior changes, learning changes too.
- Rewards are processed every 10 minutes.
Reading the lift
GET /decision-agents/{id}/report compares the learning policy with the control group. significant is true only if the difference is statistically significant (p < 0.05) and the learning policy is ahead. The dashboard says the same: if it shows "No evidence yet", do not claim a lift.
With holdout_percent: 0, the lift cannot be measured.
Limits
- The agent will also show a poor option for a while: that is the cost of learning. Choose your options accordingly for sensitive content.
- At most 20 agents per app. Deleting an agent also deletes its learning.
- It is not used in campaigns: a campaign sends a single piece of content, while a journey branches.
Journeys (Phase 11)
A journey is an automated flow that enrolls a user through a trigger and moves them through wait, condition, branching and send steps (the equivalent of the legacy provider's Journeys). In the API, the resource name is journeys, the field name is journey_id, and the event…
A/B testing and holdout (Phase 12)
Compare content variants in campaign and journey sends, measure incremental impact with a control (holdout) group, and pick the winner automatically or manually. Design decisions: ADR-0019. Shared code:…