Agents

Getting started

Agents runs AI workflows for your workspace. SpudSuite keeps the workflows, the queue, approvals and history; the work itself happens on a runner, a small program you install on your own machine, a server, Docker or Kubernetes. This guide takes you from nothing to a finished run in about five minutes.

#Connect a runner

1. Open Runners and pick where it runs: macOS and Linux, Windows, Docker or Kubernetes.
2. Copy the install command and run it on that machine.
3. On a desktop the SpudSuite Runner app opens and pairs with this workspace. On a server the runner prints a short code: a workspace admin approves it on the Runners page.

Runners call SpudSuite, never the other way round, so they work behind firewalls. Secrets, such as model keys and tokens for other services, stay on the runner and are never sent to SpudSuite.

#Write your first workflow

Open Workflows and choose New workflow. A workflow is a YAML document:

apiVersion: agents.spudsuite.com/v1
kind: Workflow
metadata:
  name: hello
  description: Says hello in a chat channel
spec:
  inputs:
    name: {type: string, description: Who to greet}
  steps:
    - id: greet
      type: action
      action: spudsuite.post_message
      with: {channel: general, text: "Hello {{ inputs.name }}, from a runner!"}

Save it, and every runner picks it up on its next sync. Saving again with changes makes a new version; saving it unchanged keeps the version it had.

Prefer to describe it? Open the Assistant (⌘J) and say what you want. It writes the YAML and asks before saving anything. See The assistant.

#Run it

Open the workflow and choose Run. SpudSuite makes a form from its inputs; fill it in and start the run. A runner with room and the right labels takes it, and you land on the run page, which updates as it moves.

You can also start runs from the API with an API key:

curl -X POST "https://spudsuite.com/api/w/acme/agents/runs" \
  -H "Authorization: Bearer $SPUDSUITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow": "hello", "inputs": {"name": "Ana"}}'

#Next steps

• Read Writing workflows for steps, expressions and agents.
• See Runs, approvals and signals for what happens while a run is going.
• Look anything up in the API reference, resource kinds and step types.