Building a Loop

A loop is one document, its record, that says what the loop is for and everything a run of it may do. You write the record as a draft, try the draft in Chat, and publish it. The version you publish is what runs, exactly as you approved it.

Two ways to start

With LoopAssistant

Open Chat. LoopAssistant asks what the loop is for, who will use it, what you already have, what a run must produce and what it may cost. It always asks what you already have, such as an endpoint, a price sheet or your docs, and it does not propose a new loop until you answer. “Nothing” is an answer. It chooses the agents the loop runs itself, from the platform’s agents or one it proposes for you, so it does not ask you which agent to use.

When the loop needs an agent of your own, LoopAssistant starts a second agent that writes it. Its card, Install agent, appears in the same chat. Approving installs the agent into your account and runs nothing; LoopAssistant then names that agent in the loop it proposes. The agent’s role is one of the platform’s roles, or one your account defined if you name it.

It then proposes the loop as a card that names, in words, every tool, collection, output and cost the loop would get. Before you see the card, the proposal is checked against the rules publish applies to the record, so a loop that publish would refuse goes back to LoopAssistant to fix. Read the card, then press Save as draft to keep it or Decline to throw it away. The model that drafts a loop never publishes it.

While LoopAssistant works, or waits on a card or another agent, Stop takes the place of Send in the box, and Stop stays beside the chat’s name too. Enter still sends a message, which it reads before its next step. When it waits on your own answer, Send is back.

LoopAssistant also changes a loop you already have. It proposes the change as an edit to the record, and the card shows what the edit adds and what it removes.

A conversation with LoopAssistant shows what it says and what it asks you. The steps it takes on the way, such as reading your loop, are folded into the platform notes line at the top: press show to read them, with what they cost. Your answer to a proposal names what you decided, such as You approved the loop proposal. A conversation with your own loop shows every step, because that is where you check what your loop does.

By hand

Open Loops and press New loop.
Type a loop id: a lower-case letter, then lower-case letters, digits or underscores — lead_qualification, not lead-qualification. The id names the loop and never changes.
Press Write its first draft. The editor opens on a starter record that already saves.
Edit the record, then press Save draft v1.

The record

The record is YAML. Every key in the starter is required, and the starter’s comments say what each one is for. The keys you will change most:

Key	What it says
`name`, `description`	How the console names the loop.
`entry`	The standing instruction. The model reads it on every turn; your users never see it. Every turn is also told today’s date and weekday, in UTC, so the entry can say “next Monday” or “this year” without naming a date.
`agents`	The only agents a run may use. With more than one, `entry_agent` names the one a person meets.
`capabilities`	The ceiling. A tool that needs anything outside this list is not available to a run, unless `grantable` lets a run ask for it. Permissions and trust says how the two combine with an agent’s role.
`collections`	The only collections a run may write.
`tools`	Your own endpoints that a run may call.
`sources`, `indexes`	What a run may read, and which of your search indexes it may search.
`checks`	What a run’s work must pass, including the test cases that run before publish.
`outputs`	Where a result goes: a collection, a signed webhook, or an email.
`gates`	Which steps wait for a decision, and who decides.
`identity`	How a user proves who they are, and the per-address and per-user limits.
`delivery`	Where users reach the loop, and from which web origins.
`on_topic`	Optional. Which messages the loop answers: `about` is one sentence that names everything the loop answers, and `reply` is what a person reads when their message is not. With `refuses: true` an off-topic message gets `reply` in place of the answer; without it the check only records its judgement. A loop anyone can reach should declare it; see Keep the chat on topic.
`chat`	Optional. `show_activity: true` shows the visitor each step the loop takes while it works, then folds them into one line under its reply that they can open. Absent, the chat shows the conversation alone. See What your visitor sees.
`triggers`	What starts a run: a conversation, a schedule, an event, or your own server.
`budgets`	What one run, one user and one month may spend. Per run must not be more than per user, and per user not more than monthly.
`end_messages`	The user’s last line for each way a run can end, and `otherwise` for every ending you did not name.

When the platform refuses a save or a publish, the refusal names the field and what to change.

Help in the editor

Hover a key in the editor to read what it is for. More shows the key’s full definition, and a key with a fixed set of values lists them. Hover a capability to read what it lets a run do.

The editor marks problems as you type and says each one in words: a key it does not know, a value outside its set (`emial` is not allowed here: `kind` must be one of: email, text, choice, choices, boolean.), a missing key, a capability the platform does not have, and a rule that depends on another key, such as an upload source that names no file. A yellow mark is a guess: an agent or a tool your account does not seem to have. Publishing decides it.

The platform still checks the draft when you save. Each problem it names is marked on its line as well as listed under the editor. The editor changes only the text you type, so your comments stay.

Try the draft

A draft never serves a user. Only Chat can start a run in one: start a new conversation and pick the loop and the version, draft included. The run shows on Runs like any other, so you can read every turn, every tool call and every record it wrote.

Publish

Press Publish v1… on the loop’s page. The review shows the whole record that the press approves, and Publish v1 approves it as it stands. If the draft declares test cases, they must have run against its current text first.

Publishing does three things:

The version is fixed. A published version is never written again.
The loop gets its public id (pl_…) on its first publish. Your page, your server and your keys name the loop by this id, and it stays the same for every later version.
New runs start on the new version. Runs already in flight finish on the version they started under.

Publish also refuses a record that cannot work as written. For example, it refuses:

a record whose agents cannot do the work the record declares,
a crawl source when no agent that a run starts lists records_query, or an upload source when none lists read_file, because no run could read it,
a crawl into a collection the loop does not declare,
a tool that needs approval when no gate says who approves it.

Each refusal names the agent, the tool or the field, and the fix.

Change a published loop

Press Edit as draft v2 on the loop’s page. The editor opens on the published record as the draft of the next version. Save it, try it, and publish it like the first. Discard draft v2… removes the draft and nothing else.

A collection the loop declares can gain fields from one version to the next, and records written before simply lack the new field. Saving the draft refuses an edit that removes a field or changes a field’s type or key. The refusal names the fields: keep them, or declare a new collection.

Archive a loop

An owner of the account can press Archive this loop. An archived loop serves nobody. Runs already in flight finish, and every published version stays readable. Reopen this loop makes it serve again.