Open in ClaudeOpen in ChatGPTOpen in Cursor
On this page

Process flows

A process flow is a multi-agent orchestration: a manifest naming several agents and the order in which they run.

Not a larger agent

An agent is not a small process flow, and a process flow is not a large agent. They are different kinds of thing, and treating them as points on one scale leads to the wrong expectations in both directions.

An agent is a worker definition — instructions, tools and a model. A process flow has none of those of its own. It has a manifest: which agents take part, and in what order. The reasoning happens in the agents; the arrangement is the process flow.

Reach for a process flow when the work needs more than one worker: when two parts of it want different instructions, different skills, or a decision that routes between them. One worker's job, however long, is one agent.

They also version separately. A process flow and the agents it names have their own histories, are promoted independently, and roll back independently — see executions and versioning.

The manifest

The manifest is the definition. It names the agents that take part and how they are wired, and it is what you edit when you change the shape of the orchestration. Editing the manifest does not edit the agents' own instructions, and editing an agent does not rewire the manifest.

A manifest has four parts.

  • manifest_version — "1.0", the only value accepted today. Omitting it means the same thing.
  • flow — the process flow itself: a name (required), and optionally a description and a role.
  • agents — the list of agents taking part. At least one is required.
  • wiring — one field, initial_agent, naming the agent that runs first.

Inside agents, each entry describes one agent. Every entry carries a ref, a short label unique within the manifest, and a title; those two are required. The ref is how the rest of the manifest points at this agent, including wiring.initial_agent, so refs are resolved within the one call that creates them rather than being ids you had to know beforehand.

Each entry also has a type, which is one of two values and defaults to the first:

  • skilled_agent — an agent that does work. It carries a prompt template, an llm block, a skills list, and a next naming the agent that follows it. An entry with no next is where that path stops.
  • decider_agent — an agent that chooses. Instead of a single next, it carries conditions, each pairing a decision name with the condition that selects it, and a next_agents map sending each decision to a different agent. A decider needs at least two branches; one branch is a decision nobody is making.

The remaining fields on an entry are optional and off unless you set them: whether the agent reads the knowledge base; whether it pauses and waits for a person before it proceeds; whether its prompt receives a summary of the agents that ran before it, and which of those agents. That last one is given by name — the sibling's ref in a manifest — and resolved to a real id for you.

Writing a manifest that is accepted

The manifest is validated strictly, and in two ways worth knowing before you write one.

A field it does not recognize is rejected rather than ignored, so a plausible-looking name that is not in the contract fails the call instead of silently doing nothing. Several of the near-misses carry a hint naming the field you meant.

Validation also reports every problem it finds at once — a missing flow.name, a duplicate ref, a wiring.initial_agent that names no agent, a next pointing at nothing, a type that is neither of the two — rather than stopping at the first. One round-trip tells you everything that is wrong.

Building one, in one call or several

There are two ways to bring a process flow into being, and the choice is about whether you already know the whole structure.

Pass a complete manifest to create-process-flow and the process flow, all its agents and all the wiring are created in a single call. Prefer this whenever the structure is settled.

Or create a shell — a name, a description, a role, no agents — and add agents to it one at a time with update-process-flow. That tool adds one agent, or edits one already there. Two things to expect from it: an agent it adds must reference agents by their real existing ids rather than manifest refs, because there is no sibling list for it to resolve against; and an in-place edit changes only the fields you include, but cannot rewire an agent's position or branches. To rewire, remove the agent and add it back.

Read a process flow back, including its agents and their wiring, with get-process-flow. It answers by id or by exact name.

Running one

Running a process flow starts a real, side-effecting run and returns an execution_id, the same way running an agent does. It is asynchronous; you read the outcome by polling that execution. A run takes a natural-language goal, and optionally input variables, file ids and a session_id that groups several calls as one conversation.

A run can also be scoped to a slice of the knowledge base by tag, so the agents that read it see the same body of evidence rather than everything the project holds.

Because every agent inside a process flow makes its own governed calls, a policy decision that refuses one agent's call refuses that call, not the orchestration's right to exist. What happened is visible in the execution's trace, and what was refused is in the audit record — see policy decisions and approvals.

Where to go next