What's a workflow?

A workflow is an ordered chain of agents that runs as a single pipeline. Each step is a reference to an existing agent on your site. The first step receives the user prompt; every subsequent step receives the previous step's output and applies its own role on top.

The canonical example: Writer → SEO Optimizer → Translator.

1. Writer takes "Write an article about TypeScript generics" → produces a draft
2. SEO Optimizer takes that draft → returns the same draft restructured for search
3. Translator takes the optimised draft → returns it in another language

Only the final step's output lands in the curation queue. Curators see one item per workflow run, not one per step. Every step's cost is summed and charged to the Cockpit budget once at the end. One agent.completed webhook fires.

How content flows between steps

The runner passes a synthesized Markdown prompt from one step to the next. For step 2 onwards, the user prompt looks like:

You are processing existing content as part of a multi-step workflow. Apply
your role to the draft below and return the improved version using the same
JSON schema.

## Current draft
Title: <previous step's title>
Excerpt: <previous step's excerpt>
Tags: <previous step's tags>

Body:
<previous step's content>

This means each agent in the chain sees the whole draft as it currently stands, not just a diff. Agents are stateless across runs anyway — this just gives the next one enough context to do its job.

Creating a workflow

1. Open /admin/agents and switch to the Workflows tab.
2. Click New workflow.
3. Give it a name (e.g. "Writer → SEO → Translator").
4. Click the agent buttons in the order you want them to run. Each click adds a step.
5. Drag the grip handles (⋮⋮) to reorder. Click the × on a row to remove a step.
6. (Optional) Tick Run on a schedule and set frequency, time, max-per-run, and a default prompt to send to step 1 on each scheduled run.
7. Click Create.

Editing works the same way — click the pencil icon on an existing workflow card to reopen the form pre-populated with its current state. Save changes and the workflow is updated in place (its stats and createdAt are preserved).

Running a workflow

Each workflow card has a prompt textarea and a Run button. Type a prompt, click Run, wait. The runner iterates the steps in order, each calling its agent's LLM through executeAgentRaw (the same code path as runAgent but without intermediate side effects). When the last step finishes:

• One queue item is created with the final contentData
• The Cockpit budget is charged the sum of all step costs
• One recordRun analytics row is written, with model: "<step1> → <step2> → <step3>"
• One agent.completed webhook fires with agentName: "Workflow: <name>"

A single 3-step workflow takes roughly the same wall time as 3 separate agent runs. The savings are in cleanup, not throughput.

Scheduling

Workflows have the same schedule shape as individual agents — enabled, frequency (daily / weekly / manual), time, maxPerRun. The scheduler iterates workflows alongside agents in the same 5-minute tick.

Workflow lastRun keys are namespaced under wf:<id> in _data/scheduler-state.json so they don't collide with agent ids.

Scheduled workflow runs use the workflow's defaultPrompt field as the input to step 1. Manual runs always use whatever the curator types into the per-card textarea.

Per-step budget guards

There's no separate workflow-level budget. Instead, each step's agent is independently checked against its own per-agent cost guards (Phase 4) before its LLM call. If any step's agent is over its budget, the workflow halts at that step and throws.

This is generally what you want — it means a runaway agent in a chain still gets stopped by its own budget without you having to set workflow-specific caps.

JSON mode

The workflow create/edit form has a JSON / UI mode toggle in its header (the same ModeToggle component used by the structured array editor in collections). Switch to JSON to see the entire workflow body as formatted JSON. Edit it directly if you need a structure the visual editor doesn't expose. Switch back and the form re-validates from your edits.

The Save button works from either mode — it parses the JSON body before submission.

See also

• Agents overview — what an agent is.
• Per-agent cost guards — how step-level budgets work.
• Agent templates — start each step from a template instead of a one-off agent.