Workflows — executors, edges and events

A workflow is a graph you design, rather than behaviour you hope a prompt produces. There is one governing idea here, and it is worth grasping before the details, because it answers most of the questions on its own.

Two primitives

Executors are the nodes. Every node is an executor — either some logic, or a call to an agent. An agent node invokes an AI agent. A for-each node handles multiple items without you duplicating nodes for each one.

Edges are how nodes join. Four kinds:

• Direct — straight through.
• Conditional — branch on a test.
• Switch-case — a multi-way branch.
• Multi-selection, or fan-out, then fan-in — run several paths in parallel, then aggregate the results.

That vocabulary is enough to describe most orchestration questions.

Building and running one

• Workflows are designed declaratively in the portal.
• They are saved manually. There is no auto-save, which is a small thing that has cost people work.
• You run and test in chat, then call from code via the project endpoint with an extra_body workflow reference.

Structured output

On an agent node: Details, then Text format, then JSON Schema.

And a rule that belongs on every checklist: never put secrets in schemas, prompts or variables. Anything in those may be echoed back, logged, or included in a trace.

Monitoring

Subscribe to events. The ones to know are type == "output", node completed, and error.

Connected agents, the deprecated cousin

Connected agents offered no-code, natural-language delegation between agents. Two things to know: the behaviour is nondeterministic, and classic connected agents are deprecated in favour of workflows. Hosted agents are not supported in the designer.

If a question offers connected agents as the way to orchestrate something, check whether the scenario actually wants determinism — because that is usually why the answer is a workflow instead.

The principle behind most workflow questions

Push logic out of prompts and into workflow control flow.

Language models are reasoning engines, not logic engines. Asking a prompt to reliably branch three ways on a condition is asking the wrong component to do the job. It will mostly work, which is worse than failing, because the failures are occasional and unexplained.

The practical test: if an answer option solves a branching problem by writing a longer system prompt, it is the wrong one. The right answer moves the branch into an edge.