Build a storyline

What a storyline is for

A plain agent does one thing well. A storyline lets one agent run a whole multi-step process with each person — teaching a course, coaching a program, taking an application through to a decision — and remember where every individual is, across sessions and channels. If you're new to the idea, start with the Storylines concept page; this page is the how-to.

Storylines are a Pro capability. Once it's on for your tenant, you'll find the storyline editor in the console. You can also build storylines over the API (/v1/storylines), which is how a setup wizard or an assistant can generate one for you.

The shape of a storyline

A storyline is a graph. You draw nodes and connect them with exits.

Each node is one step. For that step you set:

• a task — what the agent should be doing here (you can drop in {dimension} or {blackboard.key} and it's filled in with the person's current values);
• its knowledge, skills and tools — added on top of the agent's base set, or, with the advanced switch, replacing them just for this step;
• an optional opening line the agent says on entering the step (leave it blank to switch silently);
• whether it's the entry step and whether it's a terminal (finish) step.

The agent's identity and safety boundaries never change between nodes — only the task, knowledge and tools do.

How a step advances: exit conditions

Every exit out of a node carries a condition. There are five kinds, and choosing the right one matters:

• Rule — a threshold on a dimension or a saved value, built by picking a field, an operator and a number (listening ≥ 70 and attempts ≥ 3). Deterministic, free, no model call. Use this for the decisions that must be reliable.
• User choice — a button the person taps. Good for "ready to continue?" or branching on a clear preference.
• AI — a sentence describing a fuzzy criterion ("when the student can form a past-tense sentence unprompted"), which the model judges. You also write when to check it, so it isn't judged every turn. Use this for judgement calls, not for gates you need to be exact.
• Callback — waits for a signal from an outside system (see below).
• Go to storyline — jumps to a different storyline (branching by outcome, or chaining grades).

When more than one exit could fire, they're evaluated top to bottom — so put the deterministic ones first.

Dimensions: the profile that travels with a person

Under the storyline's settings you define dimensions for your subject — for a language course, listening, speaking, reading, writing, each 0–100. These accumulate on the person across storylines (so they carry from grade to grade), and each can be marked visible to the learner or kept for your eyes only. Dimensions get written three ways: the AI can score them periodically, a rule can set them, or a third-party callback can report them.

Alongside the dimensions, each enrolment has a blackboard — a free-form scratchpad of handoff notes passed from one node to the next. It resets when the person moves to a new storyline.

Bringing in a third party (callbacks)

A node can hand a person off to an outside system and act on what it reports back — a graded quiz, a KYC check, an embedded mini-game. There are two shapes:

• Backend — data goes out to a tool and a result comes back invisibly.
• Redirect-and-wait — the conversation shows a link, locks, and resumes when the outside step finishes (the way a payment window works). If the person cancels or it times out, that's a distinct outcome you can branch on.

The console gives each callback a URL and a signal name to hand to the third party. Results are verified with a short-lived token bound to that person and step, applied once (repeats are ignored), and any dimensions they report are checked against your schema — an outside system can't write a field you didn't define. Treat anything a callback writes as data, not instructions.

Publishing, versions and changing a live storyline

A storyline stays a draft until you publish it. Publishing first validates the graph — no missing entry, no dead ends, nothing unreachable, no dangling or unknown targets — and blocks if anything is wrong. Publishing freezes an immutable version; anyone already partway through stays pinned to the version they started on, so a change never disrupts someone mid-way.

When you delete or change a node that people are currently on, you choose what happens to them: move them to another node (safe), send them back to the start, or clear their progress. The last two lose a learner's progress, so the console asks you to confirm and shows how many people are affected.

Trying it before it's live

The editor has two ways to test. A logic walk-through traces the graph without calling the model (free, instant) to check reachability and conditions. A live run actually feeds messages through the model (it uses your quota, and the editor says so) to feel the real thing.