Core Concepts

Loop

A loop is a bounded piece of work you define once and offer to your users: what it is for, the sources it may read, the tools it may call, what it must produce, who may use it, and what each run may cost. Loops belong to your account. For the jobs a loop can do — answering, qualifying, booking, triage, refunds, expenses, digests — see What Loops Are For.

Version and publish

You write a loop as a draft. Publishing turns the draft into a numbered version, and a published version never changes. A draft never serves a user. If the loop declares test conversations, the version publishes only after they have run on it.

The record you approved is what runs. A run holds exactly the tools its version grants. A tool the version does not offer does not exist in the run, whatever a user types.

Run

A run is one use of a published loop: a conversation with a user, or a headless run your server starts. Every run is recorded turn by turn, and you can watch it live and stop it at any point. A run that ends says why — for example completed, over_budget, lapsed, stopped or check_failed.

Subject

A run’s subject is who it is for, as the platform verified it: an anonymous visitor, a user your own system vouches for with a signed assertion, or a member of your account testing from the console. Per-user caps, and the record of who ran what, key on it.

Gates

A run can stop and wait. It waits on its user when the loop asks them something, on you (the operator) when a step needs your decision, or on an external system that answers through a callback.

Every gate has a lifetime. What happens when the user declines, or nobody answers in time, depends on who the run waited on:

• Your decision. A gate you do not decide in time lapses, and the run that holds it ends with the loop’s lapsed message. A visitor does not wait for you: in a run for somebody outside your account, the visitor’s conversation ends once your decision is all that is left, so the visitor has already read the loop’s closing line.
• A form the user fills in. If the user declines the form, or nobody answers it in time, the loop reads that the user gave nothing, and the run goes on.
• A tool on your page. If the user declines the action, or your page has no handler for the tool, the loop reads that as the answer and the run goes on.
• An email check. A code the user does not redeem in time ends the run with the loop’s own words.

Budgets

Money is counted before it is spent. Four limits apply to every run: the account’s wallet, a cap per loop, a cap per user and a budget per run. Each call is reserved against them before it is made, and a run ends at the first limit it meets. Your users never see a budget, a model or a price — only the conversation.

Delivery

A delivery is where a loop meets its users, and a loop declares the ones it allows:

A loop with no declared delivery is not reachable from outside your account.