Agent flow

You can skip this page as long as the assistant does what it should. The flow is the heart of the agent, and it's worth touching only when the task can't be solved with knowledge, actions or personality.

What it is

The flow is the steps that make up one piece of the agent's work: from the customer's question to the reply.

A regular assistant has one step: think — reply. But there can be several steps, and it's the shape of the flow that separates "a bot that answers" from "a bot that answers and checks itself".

Steps come in three kinds:

• a model call — the actual "thinking". There can be as many of these steps as you like, each with its own task;
• a request without a model — simply fetch data from someone else's system; or watch a page: such a step returns only what has changed since last time, and when nothing has — nothing, and the model isn't called after it (Page watch);
• a script without a model — do work by a rule: calculate, process data, work with a repository. Details below.

Steps can be conditional ("nothing new — don't touch the model"), and steps that don't depend on each other run at the same time.

Ready-made shapes

When creating an agent, the builder takes one of the ready-made templates — it provides both the personality and the shape of the flow:

Template	Shape	For whom
Website assistant	one step: answers itself, calls actions when needed	most people
Reply with a check	two steps: one writes the reply, the other rereads it	where the cost of a mistake is high
Background worker	one step, no one to talk to: delivers the result through an action	for scheduled work
Personal assistant	one step for talking with you; a morning summary on a schedule	for yourself
Page watch	a check without a model → the model only on a change	prices, availability, job openings
Deep research	agrees on the details in conversation; in the task — plan → branches at once → report as a file	a report with sources
Search agent	agrees on the details in conversation; in the task — source registry → crawl → results base	search base

A template doesn't provide knowledge, actions or keys — everyone has their own, and the builder adds them in the conversation. It will say out loud what's missing right after creating the agent.

When it's worth changing the flow

There's one realistic case: the agent promises too much. Then a second, checker step helps — it throws out of the reply everything that isn't in the knowledge.

Before replying, have it reread itself and remove anything that isn't in the materials

It costs more — and you'll be told in advance

Every extra step with a model is one more model call. Before the change, the builder will show both what exactly will change and how much it will cost:

This graph is up to 2 model calls per run and up to about 40 s.

That is, a conversation becomes roughly twice as expensive. You see this before you say "yes".

Separately, the builder will warn you if what you have in mind won't make it in time to answer a live visitor: nobody waits that long in a chat, and such work belongs in a schedule.

What a script step can do

A script isn't just "calculate". The step runs in a separate environment that the platform spins up for the duration of the run and shuts down afterwards, so you can do real work in it, not just arithmetic.

What	How it looks to you
process data	collect, calculate, convert formats — anything awkward to ask the model for
work with a repository	name the address — the platform checks it out into a working directory before the run
publish the result	name a branch — the work goes there after a successful run
give a file to the other side of the conversation	a report, spreadsheet, image or archive arrives in the conversation as a link

Every night, take our repository, build a dependency report and put it in the reports branch

You won't be asked for repository keys

Access to the repository is given by the platform, not by you: no token gets into the runtime environment, so the script can't read it. If the builder asks you to bring a key from a third-party service for this — that's a mistake, tell it so.

Limits worth knowing in advance:

• the working directory lives for exactly one run. A file created in it this time is gone next time. What should be kept, put in the agent's persistent folder (it exists when you work with the agent yourself), in the repository, or hand over as a file;
• internet access in it is limited. Package registries and repositories are available, not any address;
• only what actually worked gets published. If the script fails, nothing goes to the repository, and you'll find out. Half the work dressed up as finished is worse than an honest failure;
• one step has a time cap — two minutes by default. You can ask for longer, but not more than five. If it doesn't finish, it's stopped, and you'll be told plainly: "ran out of time" and "broke" are different answers, and they're fixed differently;
• the whole background run — on a schedule or trigger — has a five-minute cap. The steps inside it share this time: a long script leaves less for the rest of the run;
• a file the agent hands over is up to 25 MiB. A bigger one won't be sent at all, rather than sent truncated: a broken file with a confident "done" is worse than a refusal.

You're not the only one who can get a file

It's the same ability: the agent puts the finished file into the conversation as a link — whether it's talking to you or to your customer. A ready invoice, a selection, an export on request.

Files you uploaded in advance are a different thing and live separately. See What the agent knows.

The agent's persistent folder

Besides the working directory, which disappears with the reply, the agent has a persistent folder — /agent. Files in it stay between conversations and runs: a journal, notes, spreadsheets, intermediate data, its own scripts.

Keep my ideas journal — every time, add whatever I dictate

Save this file for later

What's in your folder?

For this the agent needs the ability to run code; the personal assistant already has it, and for another agent the builder will add it — ask it to "keep my journal in a file".

Who sees the folder. Only you. The folder is mounted only in runs of the owner themselves: in the messenger chat you linked as the owner, in the "Speak as owner" conversation in the panel, and in scheduled work the agent does on your behalf. In a conversation with a site visitor, a trusted person or your site's administrator, the folder doesn't exist at all: the agent there can neither read from it nor write to it — files in such a conversation live for one reply, as before. A flow step script that writes to /agent will fail in such a conversation and say why; for conversations with customers, keep data in the notebook.

Where to see it. In the panel — the "Agent files" row: a list with the size and date of each file, download, delete, erase all. The same in words to the builder: "what's in the agent's folder?", "delete that file", "erase everything in the folder" (it will ask for consent). Only dashboard admins see the row.

Limits worth knowing in advance:

• space — 100 MB per agent. How much is used is shown in the panel row and in the sheet;
• when the space runs out, the folder becomes read-only. The agent will say so right away, as soon as its write overfilled the folder, and next time — that it can't write. Delete what you don't need in the panel (or ask the agent to clean up while it still can) — and writing comes back. Within one run, code can write more than the limit: it applies from the next time;
• file changes can't be undone. "Undo" restores the agent's settings, not its files: what was overwritten or deleted in the folder can't be recovered. The platform doesn't take snapshots of the folder before a run;
• links inside the folder (a shortcut to another file) are visible in the list, but you can't download through them;
• if the row says "unavailable" — the environment where the agent runs code can't currently keep files between conversations. The agent will then say so: "this won't be kept between conversations", not "saved";
• the agent's browser has no folder. Pages from the open web and your files never meet in the same environment.

Privacy. The list of files, together with the files themselves, is included in the data export (the Account section → "Your data"); a single file can also be downloaded in the panel. The folder is erased together with the agent. What the agent reads from the folder, it passes to the language model — like everything it works with.

Do the same thing with each one

The most common kind of work that can't be described in one step: "find everything new and process each one".

Every day, look for new listings matching my criteria and assess each one separately

A step marked as iterating runs once per item in the list — and it's the platform that does this, not the model. The difference is that by the hundredth item the model no longer remembers the first, while the platform counts: the run log says "processed 137 of 137", not "done".

Worth knowing:

• up to 200 items at a time. More — a refusal with a hint to narrow the selection, not silent truncation: "all processed" about a third of the work is worse than an honest "too many";
• four at a time. Each item that goes to the model is a separate call and separate credits;
• a failure of one item is shown separately. "Processed 340, 7 of them with an error" — not "an error occurred";
• the list can come from the notebook too. You can iterate not only over the output of the previous step but also over cards the agent collected earlier: records:listing?status=new. This way a thousand-item job goes in batches of 100 — each run takes up to a hundred cards not yet processed, if the step changes the card's status (What the agent collected);
• unfinished work is reported. If the run ended before the list did, that's a problem in the panel, not a line in the trace: otherwise the summarising node would report "all processed" about a third of the work.

Ask you and carry on

There are decisions the agent doesn't take on itself: whether to take a property, which option to choose, whether to give a discount. For these it has a third way to reach you — besides "allow an action" and "notify":

If you're not sure whether a property is worth it — ask me and wait

The agent asks the question, does what doesn't depend on the answer, and ends the run — it doesn't hang there waiting. You see the question in the panel ("Asking") and in a notification, and you answer under the question itself, in words to the builder ("tell it: yes, take it"), with Reply to the message in Telegram, or simply by replying to the email if the agent has email connected — and the agent carries on in a separate run, with your answer as input.

It will wake up without the memory of that conversation, so along with the question it records what it was going to do with the answer. You can see this next to the question.

A question expires after a week

An answer a month later is an answer to something that no longer exists. An expired question is shown separately as "didn't get an answer", and you get a notification about it: this work was stuck for a week.

Come back to it later

The agent can postpone one-off work and come back to it on its own:

Publish the post, and a day later collect its metrics and tell me how it went

This isn't a schedule: a schedule wakes the agent every time, while here it comes back once and to a specific thing. This is how the agent starts to see the result of its own work — not just do it.

In the panel this is the Postponed row. Each postponement can be viewed and cancelled: it shows what exactly the agent will do and when.

The reply comes back where it was promised: if the agent told a visitor in the chat, a day later it will write to that visitor, not to you as a notification. A promise made in a conversation is kept in it.

If the platform didn't wake up on time

Overdue work isn't performed and is marked separately. "Remind me today before 18:00" done at three in the morning is worse than not done — so we show it as our failure, not as done.

Such a row isn't a dead end: next to it there's Retry, and the work is set again in the agent's own words — not a retelling of yours. In the panel this is a separate Missed row.

Changing the flow always asks first

This is one of the changes customers will see right away. The builder will:

1. look at how the flow is set up now;
2. say in words what it will add, remove or rearrange;
3. wait for a clear "yes";
4. and only then make the change.

Changed your mind afterwards — say "undo", and the flow will go back to how it was.

If it got worse

Put the flow back as it was

Put the agent back to how it was yesterday

Restore points are taken automatically before every conversation in which something changes. See If it didn't come out right.

Next

• If it didn't come out right — undo and restore points.
• How much it costs — what credits are charged for.

Rehearsal: check without consequences

After you've changed actions or the personality, the best check is a real customer question. But a real question to an agent with a "place an order" action would mean a real order. That's why there's a rehearsal: tell the builder "show me what you'd do with 'I want two pizzas'".

The agent will reply for real — with the same knowledge and the same personality — but will record every outside action instead of performing it: the order won't be placed, the email won't be sent, the card won't be saved, the operator won't be called. You'll see both the reply and the "would have done" list with arguments — exactly the actions you wanted to see.

Three things worth knowing:

• no trace is left: a rehearsal doesn't go into conversation history, the reply cache or the memory about people; the next real customer won't see it;
• reads are real: knowledge, internet search and reading cards work as usual — otherwise the reply wouldn't be the agent's reply;
• the run is paid: the model replies for real, so a rehearsal costs as much as one conversation and shows up in the run log as "rehearsal".

And the same for a schedule

A background agent is the one that needs a rehearsal most. It acts with no person around: when at 9:00 it sends out two hundred emails, nobody will be watching, and the only way to know in advance what exactly it would do was to wait until nine.

show me what the morning summary will do

The agent will go through its run with this schedule's task — for real, on your behalf — but will record the actions. The agent's memory doesn't move: otherwise the next real run would skip work that nobody did.

Do this every time after creating or changing a schedule. The builder will suggest it too.

Via the API — POST /v1/dashboard/bots/{id}/rehearse with {"message": "…"} for a conversation or {"trigger_id": "…"} for a schedule; the response contains answer and would_do.