Writing Flows
A weaver writes flows: the Python that says which agents are driven, what each is asked, in what order, and when to stop. You have run a flow; this is where you write one.
Before you start
- A flow run behind you. If you have not, start with the User Guide.
- Python you can read:
async def,await, classes, and a pydantic model now and then. - A git repository you don't mind an agent editing.
Every page here is a guide to one thing a flow can do. Each opens with what you will build, explains the idea, then walks through a complete flow you can copy: what each marked line (# ①) does, the command that runs it with what a real run printed, how to check it worked and how to test it without spending a token, then the variations and the pitfalls.
Start here
Four pages, in order. The first has a flow of your own running in five minutes; the rest grow it.
-p and a form at the prompt.Growing a flow
| Many turns at once | gather, TaskGroup, and a session apiece |
| A flow that calls a flow | Build on a flow somebody else wrote |
| Branching a conversation | Two ways out of one conversation, paid for once |
| Worktrees, copies and scratch | One agent working in several directories at once |
What an agent can be asked
| Goals | The CLI's own goal: it decides when it is done |
| Answers in a shape | A turn that answers with a pydantic model instead of prose |
| Hooks | Your code, run at the moments of a session |
| The agent asking the flow | A question mid-turn, answered by the flow's own code |
| The person as an agent | You, driven by a flow like any other agent |
What an agent may touch and what it carries are declared by the flow too: Permissions and Skills are written for you.
When it is ready
| Testing a flow | The flow run on scripted agents: milliseconds, and nothing spent |
| Flowverses | Publish a flow by release, for anybody to install by name or call by ref |
Next steps
Real flows to read are in Flows. Every argument, refusal and return of the flow API is in Reference › Flows.