SpudSuiteHelp Open SpudSuite

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, and steps.<id>.status,
  • run.id, run.url and trigger for 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.

Something unclear, or out of date? Spud wants to know: tell us from SpudSuite and we'll fix the page.