flows

List this organization's flows, oldest first: id, name and entry step. Read one with get_flow to see its steps and edges.

Create a flow: a deterministic graph of steps, each step a tool, each edge a condition on what earlier steps returned. Use as soon as a job needs more than one tool or a branch; a prompt is not a place to describe a procedure. The steps are ordinary tool instances (add_step), the branches are edges (add_flow_edge), and the first step added is the entry. A flow becomes a tool the agent can call by registering it with create_tool and config.flow_id, or the work an automation runs with create_automation. It is not for a decision the model should make from what the person says; that is the node graph.

Read a flow whole: its entry step, every step (the tool it runs and the parameters it fixes) and every edge with the condition on earlier results that sends the run along it.

Delete a flow with all its steps and edges, permanently. Use when the flow should no longer exist.

Rename a flow. Use only to change its name; it changes nothing about what the flow does.

Connect two steps of a flow, so one runs after the other. Without a condition the target always follows; with one, only when the test holds: condition is {field: "<step_id>.<path>", op, value}, field reading an earlier step's output (or trigger.<key>, what the run was started with) and op one of ===, !==, >, <, includes, exists. Use it for every branch a job has — "if the slot is free, book it, otherwise stop" is an edge here, not a branch in a tool's code and not a sentence in a prompt. A step with several outgoing edges takes the first whose condition holds; a step with none ends the run, and its output is the flow's result.

This is a flow. To connect nodes of an agent's conversation graph, where the model decides, use add_edge.

Remove an edge from a flow. Use when one path between two steps should no longer exist.

This is a flow; for an agent's conversation graph, use delete_edge.

Set the step the flow starts at. Use only when the flow should start somewhere other than the first step added, which is the entry already: after a restructure, or before deleting the entry step, which is refused while other steps remain. The step must already belong to this flow. Every run begins here and follows the edges out of it, so a step no edge leads to never runs.

Add a step to a flow: one tool instance, run when the flow reaches it. Use once per action the job takes — a tool that fetches, one that computes, one that writes are three steps, never one instance that does all of it. param_overrides fixes the arguments the tool is called with; a value "$ref:<step_id>.<path>" reads an earlier step's output and "$ref:trigger.<key>" reads what the run was started with, so data moves between steps with no code. The first step added becomes the entry; add_flow_edge says what runs after it and on which condition. A step between a fetch and a write that needs a calculation no tool provides is a published custom tool's tool_id.

Delete a step and every edge touching it, permanently. Use when one action should be removed from the flow.

Change what a step does or how it decides where to go next. Use when adjusting one existing step's tool or arguments, not adding a new action.

Testing a flow runs it. Starts at the entry step with inputs (read as $ref:trigger.<key>) and runs every step it reaches for real: a message really sends, a record really writes. Answers what each step was handed, returned or failed with, and which edge it took, and how the test ended: succeeded, failed (a step failed; not an HTTP error), stopped or did_not_terminate.

stop_after_step_id stops right after that step, before what follows runs. run_step_id runs one step: the steps before it reuse what the flow's latest test recorded them returning (marked reused, not run again; stale when the step or what it reads changed since), only those with nothing recorded, and those on a loop, run, then it stops; leaving inputs out then means the latest test's (inputs_inherited), and {} means none. Give one of the two at most. Each step that runs counts as a tool execution, and a test is refused with 402 while the organization may not spend. Each value kept is cut at 64 KB (truncated); kept with the flow's latest 20 tests (list_flow_tests) and purged on the organization's retention window.

What this flow's latest tests did, newest first, at most 20: each step reached, what it ran with and returned (each value cut at 64 KB, truncated), and how the test ended. Use to review a test instead of running the flow again.