Agents
Writing workflows
Everything in Agents is a resource: a YAML document with an apiVersion, a kind, metadata (a name and optional description and labels) and a spec. Workflows are the kind you'll write most, and they can use agents, skills, sandbox profiles, gateways and connections, which are resources too. See Resource kinds for the full list.
Steps
A workflow's spec.steps is a list. Each step has an id, a type and the fields of that type:
| Type | What it does |
|---|---|
agent |
A model works on a prompt with its tools until it's done, and returns typed outputs |
action |
Calls an integration action, such as spudsuite.create_issue |
script |
Runs code on the runner, for anything that needs no judgement |
set |
Sets values from expressions |
wait |
Waits for a time, a duration or a signal |
approval |
Stops until a person approves or rejects |
workflow |
Runs another workflow as a child run |
decide |
Picks a branch with a model or an expression |
grade |
Scores an output against a rubric |
The step types reference lists every field.
A step runs after the step before it in the list unless it says otherwise with needs, a list of step ids. Steps with no path between them run side by side. Every step also takes:
| Setting | Meaning |
|---|---|
if |
An expression; the step is skipped when it's false |
retry |
Attempts, backoff and backoff factor |
timeout |
The longest it may take, such as 30m |
on_error |
fail the run, or continue past the failure |
Expressions
Values can hold {{ … }} expressions:
inputs.<name>for the workflow's inputs,steps.<id>.output.<field>for what an earlier step returned, andsteps.<id>.status,run.id,run.urlandtriggerfor the run itself.
In YAML, quote any value that starts with {{, for example if: "{{ steps.check.output.ok }}".
Agent steps
An agent step gives a model a prompt and tools. Name an Agent resource to reuse a model, instructions and tools across workflows, or set them on the step:
- id: triage
type: agent
agent: triager
prompt: |
Read issue {{ inputs.issue }} and decide how urgent it is.
outputs:
urgency: {type: string, enum: [low, medium, high]}
summary: {type: string}
The model runs on the runner, through a Gateway resource that names the provider and the secret holding its key. The key itself stays in the runner's secrets.
Script steps
Use a script step for work that needs no judgement: reshape data, dedupe, compute, call a plain HTTP endpoint, run tests. It's faster, cheaper and repeatable compared with an agent step. Set a language (python, node, shell or bash), the code, and the inputs it gets and outputs it returns. Inputs are rendered from expressions; the code itself is used exactly as written, so pass data through inputs rather than writing {{ }} inside it.
The step also returns exit_code, stdout and stderr, and a non-zero exit fails it unless fail_on_error is off.
Versions
Every change to a resource makes a new version, kept with who made it and an optional note. Open a workflow to see its versions, and start a run of an earlier one when you need to.