Skip to main content

Workflow graphs

A single-step agent is one system prompt, one model and its tools. A workflow chains several steps: classify a request, look something up, ask a person, reply. You build it on a graph canvas in the console, and every run is a durable, checkpointed workflow traced in Runs & traces.

A workflow is an agent like any other. It has versions and a live version, and it is reached the same ways: the Agent API, the hosted chat, channels, A2A and voice.

Open the editor​

Open Workflows and choose New workflow, or open an existing one. You need the developer or admin role on the project.

The editor has a palette, the canvas and an inspector for the selected step:

  • Drag a step from the palette onto the canvas, or onto an arrow to insert it there.
  • Drag from a step's dot to another step to connect them.
  • Zoom and pan the canvas. The canvas stays left to right in every console language.
  • The editor checks the graph as you edit and lists what is wrong before you can save.

Every save is a new version. A workflow with steps in a simple line is saved as an ordinary multi-step agent.

Step kinds​

KindWhat it does
Model stepA model call with a system prompt, a model and optional tools, exactly like a single-step agent. Its output goes to the next step.
Approval gateA model step whose tool calls always ask a person first.
BranchNo model call. Checks conditions in order and takes the first that holds, or the else path. Passes its input on unchanged.
ParallelNo model call. Starts up to 8 lanes at once with the same input. Each lane runs until it reaches the join.
JoinWaits for every lane and combines their outputs: as text sections, headed by each lane's last step, or as a JSON object keyed by it.
LoopRuns a path of steps over and over, each pass reading the previous pass's output, until a condition holds or the cap is reached. The cap is at most 20 passes.

Each step reads the output that reached it. A model step can instead read another step's output, or the run's original input, with Input from. The step it names must always have run first.

Model settings​

A model step's Model settings tab sets how its model answers. Leave a field empty to use the model's default.

SettingRange
Temperature0 is the most predictable; higher is more varied.
Top PThe share of likely words the model picks from, above 0 and at most 1.
Max answer tokensThe longest answer the step may give.
Max tool roundsModel calls the step may make while it uses tools. Default 5. Only used when the step has tools.

The settings are checked when you save, and sent with each of the step's model calls.

Structured output​

Turn on Answer with JSON in a fixed shape and give a JSON Schema to make a step answer in a fixed shape, for example to classify a request into fields a branch can test. The top level must be an object. Supported: type, properties, required, enum, items, pattern, minimum, maximum and $defs.

The step's answer is checked against the schema. A mismatch gets one retry, with the model told what was wrong; a second mismatch fails the run.

Conditions​

Branches and loops test conditions. A condition has:

  • a subject: the output that reached the step (or the loop pass's output), the run's input, another step's latest output, or a run variable
  • an optional path into the subject read as JSON, such as refund or items.0.amount. A model's ```json fence is fine.
  • an operator: equals, not_equals, contains, not_contains, starts_with, ends_with, gt, gte, lt, lte, is_empty, not_empty, is_true or is_false
  • a value, for the operators that compare, and whether case matters

Regular expressions aren't supported, on purpose: a pathological pattern could stall a run.

A branch has at most 20 conditions.

Run variables​

A condition can test a run variable as vars.<name>, such as vars.customer_tier. The workflow's settings list the variables its conditions read. A run is started with their values: the editor's Test run asks for them, and API callers send variables to POST /agents/{name}/run. See the Agents API.

Memory​

A workflow's settings also say how much of a conversation its model steps are sent. See Conversation memory.

Triggers​

A workflow, like any agent, can start on a schedule or from a signed webhook. See Schedules and webhooks.

Test and cancel​

Choose Test run in the editor. The dialog follows the run step by step, shows each approval gate with Approve and Reject, so a loop that asks on every pass can be approved without leaving the editor, and has Cancel run.

A run's page in Runs & traces shows which branch was taken, which steps were skipped, each loop pass, and a Cancel button. Cancelling needs the developer or admin role and is audited.

Limits​

  • A loop's cap is 1 to 20 passes.
  • A run stops, as a failure that says why, after 200 step runs in total. Nested loops multiply, so this protects your models from a runaway graph.
  • A parallel step has at most 8 lanes. If one lane fails, the others are cancelled.
  • Approvals, guardrails, redaction and usage are per model step, exactly as in a single-step agent. Each loop pass asks for its own approval.

Voice​

On a voice or phone call, a multi-step workflow runs one whole workflow per turn, with every step, tool and approval gate. The caller hears a short filler while it works. See Voice agents.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →