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.
The Workflows page
Workflows shows each workflow as a card that reads left to right:
- Starts: the triggers that start it, in plain words such as Mondays at 09:00 or When issue created, with when it fires next and when it last fired. The switch beside each one turns it off and on. A workflow with no trigger says When someone runs it, and Add a trigger makes one already pointed at it.
- The workflow: its name, what it does, and its steps in order. Agent steps are tinted, and approvals are yellow. A workflow you adopted from a blueprint says which one.
- Agents: the agents its steps use. Choose one to open it in its own editor.
Open takes you to the workflow builder, and Run opens it with the run dialog up. If you have the SpudSuite app on a computer, the run dialog has Where it runs: choose My computer to run it there (see This computer). New trigger and New workflow are at the top, and Paste YAML saves one or more resources at once.
Below the cards you'll find any triggers whose workflow is gone (they start nothing until you point them at one), agents no workflow uses yet, and links to everything else in the workspace, such as gateways and cloud identities, on their own pages. Ready-made workflows are under Blueprints.
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.