Workflows

A workflow is a set of steps. Each step is an agent run with its own prompt. Steps can depend on other steps and receive their results, and steps that do not depend on each other run in parallel.

1. research
2. draft
3. verify

Define one

In YAML or JSON:

name: release-notes
description: Write release notes from the last commits
nodes:
  - id: collect
    prompt: List the commits since the last tag and group them by area.
  - id: draft
    needs: [collect]
    prompt: Write release notes from the grouped commits.
    output_format: Markdown with one section per area.
  - id: check
    kind: verifier
    needs: [draft]
    prompt: Check the notes against the commit list. Say PASS or FAIL.

Field	Meaning
id	Unique name of the step
prompt	What the step must do (required)
needs	Steps whose results this step receives. They run first
kind	agent (default), verifier, critic or router
routes	For a router: the steps it may choose between (required for a router)
output_format	The shape you want the result in, added to the prompt
agent, max_turns	Applied by the default executor: a step with agent runs as that built-in agent type, for at most max_turns turns (Client.RunAgentTask). Without agent, the step runs as a normal request

The kind only changes the role written into the step’s prompt: a verifier is asked to check the outputs it depends on and answer PASS or FAIL, a critic to look for weaknesses and risks, a router to choose among its routes. Nothing acts on the answer. A verifier that answers FAIL still counts as a success, and a router does not stop the other steps from running: every step runs once its dependencies have succeeded. Use these kinds to produce a judgement for a person or for your own code to read, not as control flow.

Seshat checks the file before running: duplicate ids, unknown dependencies, a router with no routes or one that routes to itself, and cycles are all refused.

How a run goes

Seshat sorts the steps into levels by their dependencies. The levels run one after the other, and the steps of a level run in parallel, up to MaxParallel. A level starts only when the whole previous level is finished, even if a step of the next level needs only one fast step.

If a step fails, the steps that need it are not run: they are recorded as failed with the error dependency "x" failed. Independent steps carry on. The result lists the failed steps and Success is false. Order lists only the steps that actually ran.

Run it from the CLI

seshat workflow run release-notes.yaml
seshat workflow run release-notes.yaml --json --max-parallel 2

By default up to 4 steps of the same level run at once. The usual --model, --permission-mode and --cwd options work here too.

Run it from Go

def, err := sdk.LoadWorkflowFile("release-notes.yaml")
if err != nil {
    log.Fatal(err)
}

result, err := client.RunWorkflow(ctx, def, sdk.WorkflowOptions{MaxParallel: 2})
if err != nil {
    log.Fatal(err)
}
for _, id := range result.Order {
    n := result.Results[id]
    fmt.Println(id, n.Success, n.Output)
}

ValidateWorkflow(def) checks a definition without running it. By default each step runs as a call to client.Ask, with the prompt built from the step and the results of its dependencies. To run steps your own way, pass an Executor in WorkflowOptions.