Swirls

Say what you want in plain language; this table tells you which Swirls primitives build it.

Every Swirls system is a handful of primitives wired together. This page maps common intents to the primitives that express them. It works in both directions: humans use it to find the right blocks, and agents use it to turn a natural-language request into a .swirls file.

Run things

You want	Primitives
Run a procedure the same way every time	workflow
Run something every Monday at 9am	schedule + trigger + workflow
Start a run when another app calls us	webhook + trigger + workflow
Start a run when someone fills in a form	form + trigger + workflow
Do one step for every item in a list	`map` node, or `while` for repeat-until (node types)
Run independent steps at the same time	`parallel` node (node types)
Pause until a person approves	review
Retry, skip, or fall back when a step fails	failure policies
Call one workflow from another	`workflow` node (node types)

Add judgment

You want	Primitives
A step that requires judgment, not exact rules	agent + an `agent` node in the workflow
Chat with an AI that can use our procedures	agent with workflows as tools
The agent answers in Slack or Linear	agent + channel + connection
A chat assistant on our own website	agent + web channel, see Embed agent chat
Restrict what tools the agent uses for routine work	agent `profile` (agents)
Let an agent delegate subtasks	agent `team` (agents)

Keep state

You want	Primitives
Save what a workflow produced and reuse it	stream
Shared files between workflows and agents	disk
Read or write our existing database	postgres + `postgres` nodes
Give an agent a workspace it can explore	disk

Talk to other services

You want	Primitives
Call an API with a key we hold	secret + auth + `http` node
Post to Slack, Linear, Discord, LinkedIn, or Microsoft without managing keys	connection + `http` node
Send email from a workflow	`email` node (node types)
Scrape a web page	`scrape` node (node types)
Validate inputs and outputs between steps	schema

Control who gets in

You want	Primitives
Only finance can use the bookkeeping agent	role + policy
Map our org chart onto the system	role per group + policy grants
The execs reach everything, everyone else nothing	`allow exec -> agent *` in a policy
Our employees sign in with our own identity provider	OIDC federation + role mapping
Protect a public form with a password	`basic` auth on the form
Verify webhook calls with a shared secret	webhook `secret:` + `header:` (resources)

A worked example

"When a customer submits the contact form, summarize it with AI, post it to the sales Slack, and keep a record. Only the sales team can run the follow-up workflow manually."

form + trigger start the run
workflow with an ai node (summarize) and an http node (post)
connection for Slack, no keys
stream keeps the record
role sales + policy grant for the follow-up

Five intents, six primitives, one file you can review in a pull request.

From intent to primitives