Processes an agent runs for you

Describe repeating work and an agent builds a process, not a screen, without being asked for one. Each occurrence is a run, and a stage can ask a model, make an image, or wait for you.

Some work is not a page, it is a sequence. Reviewing every pull request. Triaging whatever lands in a channel. Taking a deal through five reviews and a committee call. Describe something that happens repeatedly, or complain about doing it by hand, and the agent builds you a process instead of a screen. You do not need to ask for a process, a workflow or a flow by name: if the app will do something more than once, on a schedule, whenever something arrives, or once per item, that is the shape it gets. A screen is what you get when the app does no work of its own, such as a game, a form, or a board the team fills in.

The difference matters when you open it. A screen shows you the current state of something. A process shows you every occurrence of the work separately, how far each one got, and which ones are stuck.

What you see first

You open the work, not the machinery. The first screen is the one the process is for: what came in, what it found, what is open, what needs a decision from you. The agent designs that screen from what you asked for.

Where a row on that screen came out of the process, it says so and links to the occurrence that produced it. So "why is this here?" is one click, and you only go into the machinery when you want to.

The agent is told to build that screen so it drops a row it cannot trace back to a real occurrence, rather than showing it under a link that goes nowhere. An empty screen on a process that has not run yet is telling you the truth, and it is better than a number you cannot follow anywhere. If you are looking at a process built before this, or you see a row whose link does not go anywhere, that is worth asking your agent about: it means the screen is showing you something the process did not produce.

That screen is built for your process specifically, so it is not there on the first day. Until the agent writes it, the front page is empty on purpose: nothing generic stands in for it, because a weather board and a press-coverage board have nothing in common. Meanwhile the Workflow page already shows the run that is happening, every run so far, and what each one produced.

If the front page is still empty once the agent says it is finished, tell it: the front screen is part of the work, not a default it can leave.

Everything below this is that machinery. It is there to inspect. It is not something you have to read to use the thing.

The Workflow page

The process has one page of its own, Workflow, beside the app's own pages. It shows how the process has been running (how many runs this week, how long one typically takes, whether any is still going, how many ended well, and a chart of the last two weeks with one column per day). Under that are two sections, folded to a line each until you open them: the runs, with the latest one and its state on the line, and the process, with its step count and what starts it. Open one and it stays open for you next time.

Runs

Each time the process happens, it is a run. A run is the thing you open.

Runs are numbered from #1 in the order they started, and the number is how a run is referred to everywhere: in the list, on its own page, and in its link, so "run 12" means the same thing to everyone. The runs list shows one row each: its number and what it is called, whether it is going, finished or failed, what started it, when, and how long it took. If the agent set the process up to name its runs after the work, the rows read as work rather than as numbers alone. A deal review might list "#12 Meridian Bio, 26/50", and a name can sharpen as the run learns more.

Open a run and it reads as what happened. Its name and how it ended, then one line saying how it started, how long it took and where it got to, then the stages down the page in order.

One stage is open at a time, and it is the one that is happening. Everything finished folds to a single line saying what it was and what came of it, and everything still to come folds to a line saying it is to come. Click any of them to open it: what the stage is for, what it produced, and how long it took. A stage that failed stays open, because the reason it failed is the thing on the page worth reading.

Each stage carries a small mark saying what it is. Where a stage talks to a product you use, that product's own mark; otherwise what the stage does, a person, a model, a wait, a write. Where the process does two things at once, those stages sit together in one block, so you can see the split rather than having to work it out.

When a stage changes something you can go and look at, it offers a link to it. There is one such link on a run, on the most recent stage to have changed anything, so it moves down the page as the run proceeds.

That page follows the run as it happens. The timings count up, so you can leave it open and watch.

A stage inside a loop says how many times it ran. Where a process repeats a stage until it is done, that stage reads something like "took 12m 12s over 61 laps": the total of every lap, and the number of laps it took. The count is the part that makes the total mean something, because eight minutes against one stage reads as a single very slow step unless the page says it was sixty-one ordinary ones. A stage that ran once says only how long it took, as before.

There are three ways to look at the same run, on one control: List, which is the above; Workflow, the shape of the process with this run's progress on it; and Waterfall, which ranks the stages by how long each took, longest first, counting every lap of a repeated stage and including one still running.

Behind it is an advanced view, offered at the foot of the pages that have a fuller telling, in words. That is the machinery: every event with its timestamp, the raw output of each stage, the decisions as they were taken, the whole shape of the process, and the controls. A run that failed says which stage failed and why, and offers to try again from that stage; a run still going can be cancelled from there. A cancelled run stays in the list with its history, it just stops.

The setting is remembered for you, and only for you. It is not part of the address, so a link you send somebody opens in whichever mode they last chose, not yours. Turning it off takes every page back to plain language: what the process does, when it runs, and what happened, with as little of the machinery as it can manage. Two things survive it, both on purpose. A schedule too irregular to put in words is shown as it was written rather than described wrongly. And a run with no name of its own is listed by its number alone, because something has to tell two runs apart. Set the process up to name its runs and the name sits beside the number.

Definition

Every process shows its definition under its runs on the Workflow page: what the stages are, what starts a run, and what a run needs before it can begin. It is the thing to read when you want to know what the process does rather than what one run of it did, and it is what to point at when you want the agent to change how the process works.

A process that has never run still shows its definition, because before the first run the shape is the only thing there is to see.

What a stage can do

Not every stage is the same kind of work, and which kind a stage is matters more than it looks.

• One question to a model. Classify a pull request, summarise a document, pull three fields out of a paragraph. One question, one answer, no tools and no memory. It is the cheapest and most predictable kind of stage, and it is the right one only when the work really is a single question.
• The agent itself. The agent works with its tools and its memory, the way it does in a chat, and reports back. A stage that has to send a message, read shared files, or weigh something up with tools needs this rather than the one above. Asking for the cheap version where the work needs the agent builds a process that quietly cannot do its job.
• Code on a temporary computer, created for the stage and thrown away when it finishes. What it produced is kept with the run.
• A generated image or video, covered below.
• Waiting, either for a clock or for something outside the process to say the run may carry on.

Whatever a stage produced is shown under it on the run page, one line per field. A field that holds a list, the seven articles a search found or the verdicts a model gave, reads as "7 items", and usually opens when you click it. A list of records opens into a table, one row per item and up to eight columns; when the items carry more fields than that, the table says how many more and Advanced mode has all of them. A list of plain values opens as a list. Some lists do not open, because a table of them would have to invent a shape they do not have, and a column that holds only the process's own internal ids is left out. A cell that is a link is clickable. Advanced mode shows the same output raw.

An answer from a model can come back as plain text, or shaped into named fields so a later stage can branch on it. When it is shaped, the Definition lists those field names, so you can check a branch against them before you run anything.

A prompt can quote the run's own data: what the run started with, and what earlier stages produced. A very long value is shortened rather than sent whole, and the run names the ones it shortened, so a stage that answered about part of a document says so rather than looking like a clean success. What is never shortened is the instruction the process author wrote: when the quoted data is too long for one prompt, the data gives way, not the question. If you keep seeing the same field shortened, have an earlier stage summarise it instead of sending a fragment.

A prompt can only quote a stage that runs before it. Naming a later one is refused when the process starts, because there would be nothing there to quote.

Where that data came from an outside trigger, treat it as somebody else's writing. It reaches the model marked as third-party text, and anyone who can open a pull request chooses what is in it. So a model's reading of it should not be the only thing standing in front of something irreversible. Put a decision stage there.

Generated images and video

A stage can generate an image or a video from a prompt, and the result is kept with the run and shown on it.

Three things are worth knowing before you rely on it:

• These are not private. The app keeps the generated image or clip and serves it itself, and anyone who has its address can fetch it. Do not put anything confidential through one of these stages expecting the result to stay secret.
• Video is slow and it costs real money. An image takes tens of seconds, a video takes minutes, and each attempt costs whether or not the result is any good. Nothing retries on its own, so a generation that fails is a failed stage rather than a quiet second charge.
• A stored file can go missing. If the computer serving the app is recreated, media from older runs goes with it. The app also keeps only so much of it at a time, and the oldest goes first when that fills up, so a picture from a run months ago may not still be there. Either way the run says the file is no longer available rather than showing you a broken image. Anything you want to keep, save somewhere of your own.

When a stage waits for you

A stage can be a decision rather than a step. When a run reaches one, it stops and waits for a person. Nothing else in the app changes when that happens, which is why it is said in three places.

You will be told wherever you are. A marker appears in the app's own navigation, on every screen, and a banner at the top of every page except the run doing the asking. Both carry the question itself and both take you straight to it: the run opens with the decision already in view rather than somewhere below the fold.

You answer it on the run. The decision sits on the stage that is asking, with the work that led to it right there: whatever the process put in front of you, which may be figures, a list it drafted, or a note it sent you elsewhere. You should not have to reconstruct the case from the history before you can answer. Each item says which stage produced it, so you can open that stage if you want to see more.

Then the answers, in the process's own words, each one saying where the run goes next. "Invest" and "pass" rather than "approve" and "reject", if that is what the process actually asks. There is a box for why, which is worth filling in: whoever reads the run in three months is usually not you.

Some decisions are for named people. If one is not yours, the page says whose it is and shows you the case without letting you answer for them.

Once answered, the run records what you decided, what you were looking at when you decided it, and your name against it. That record stays with the run.

Stop asking me this

If a stage keeps asking about something you would rather it just did, the decision has a stop asking me this option. Answer once and every future run takes the same answer on its own.

The run still records the decision and the fact that you removed the need for it, so the history does not quietly change shape. You can turn the question back on from the same place.

Other views

An app can carry pages of its own beyond the Workflow page: what is outstanding, what the process has found, whatever the work needs. The first of these is the screen you land on, and the rest appear as tabs beside it. Ask the agent for the view you want and it can add one.

What can start a run

• By hand. A start button on the process, with a form for anything the run needs to know before it begins. A process that needs nothing says so, and there is nothing to fill in.
• On an event. Something happening elsewhere, like a pull request opening.
• On a clock, for work that should happen nightly or weekly.

A process may accept more than one of these. A pull request review might start automatically when a pull request opens, and still let you start one by hand when you want a second look without waiting for a push.

Starting one by hand is not only something a person does. An agent can start a run too, the same way it uses anything else it has been given access to. So each run records who started it and the run page says so by name, whether that was you, a teammate, or one of your agents. A run nobody started says how it began instead: on a clock, or on an event from outside.

Making changes

Ask the agent, the same way you would ask for a change to anything else it built. Point at the Definition, say what should be different, and it edits the process.

A run already going keeps the process as it was when that run started, so an edit never changes what an in-flight run is doing halfway through. New runs get the new version.

Related

• Apps and running code for what agents can build and run generally
• What agents can do for what you can ask for