Agents
Runs, approvals and signals
Every time a workflow runs, that's a run. SpudSuite queues it, a runner with room and the right labels takes it, and the runner reports each step back as it goes. Runs can wait for days, for a person or a signal, without holding the runner.
Run states
queued β running β (waiting β running)* β succeeded | failed | cancelled | lost
A run is waiting when it's parked on an approval or a signal. It's lost when its runner stops reporting and the run's lease runs out, for example because the machine was switched off.
The run page
Open a run from Runs, a workflow, or the overview. It updates while you watch.
- What this run made or changed comes first: the issues, pages, chat messages, goals and register items it created, changed or commented on, each linked, with the step that did it. Links found in what steps returned, such as a pull request, are listed too.
- Steps are one line each: whether it worked, what it does (for an agent, the model, how many turns and what it cost), when it ran within the run, and how long it took. Open a step to see what went wrong and how to fix it, what it made, what it was asked, the agent's conversation (what it said, the tools it used and what they answered), what it returned, and what happened, step by step. The step as written and Everything it returned show the raw versions.
- Timeline lists everything that happened, in words. Details on a row shows the raw event.
Select a step's name on the made list or the timeline to jump to that step.
Approvals
An approval step pauses the run until a person decides:
- id: review
type: approval
message: "Ship the fix for {{ inputs.issue }}?"
approvers: [dana@acme.com]
While it waits, the run page and the overview show Approve and Reject, with an optional comment. When the step lists approvers, only they can decide. A rejection stops the run. The same decision can come from the API:
curl -X POST "https://spudsuite.com/api/agents/runs/$RUN_ID/approve" \
-H "Authorization: Bearer $SPUDSUITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"step": "review", "approved": true, "comment": "Looks good"}'
Signals
A wait step with a signal pauses until something sends data into the run:
- id: deployed
type: wait
signal: {name: deployed}
Send one from the run page, or from another system:
curl -X POST "https://spudsuite.com/api/agents/runs/$RUN_ID/signals/deployed" \
-H "Authorization: Bearer $SPUDSUITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"payload": {"env": "prod"}}'
Running it again
Once a run has finished, its page has Run again. It starts a new run of the workflow's current version with the same inputs, acting for you, and takes you to it. The new run links back to the one it repeats, and the old run lists the runs that came after it.
When a run failed partway, you'll also see Retry from and the name of the failed step. A retry runs the same version as before. It keeps the outputs of the steps that succeeded, so they don't run a second time (nothing is posted twice), and starts at the step that failed. A retry needs runner 0.1.15 or newer. Until one is online, the retry waits in the queue.
Run again and record runs it again and records everything it touches, so an eval can replay it offline. See Replay recorded runs.
Cancelling
Cancel on the run page stops a run. The runner stops its steps at their next checkpoint.