Primitives

Swirls is an ecosystem of primitives for building agentic systems. There are sixteen top-level blocks in the language, but they organize into five ideas. Learn the five and the rest is reference.

                 the outside world
        ───────────────┬────────────────
  forms · webhooks · schedules · chat platforms
                       │
              ┌────────▼────────┐
   ACCESS ──▶ │    TRIGGERS     │  who may start things
              └────────┬────────┘
              ┌────────▼────────┐
              │    WORKFLOWS    │  deterministic steps (nodes)
              │       ⇅         │
              │     AGENTS      │  actors that reason
              └───┬─────────┬───┘
                  │         │
            ┌─────▼───┐ ┌───▼──────────┐
            │ MEMORY  │ │ CONNECTIONS  │
            │ streams │ │ secrets·auth │
            │ disks   │ │ brokered     │
            │ postgres│ │ OAuth        │
            └─────────┘ └──────────────┘

Triggers feed workflows. Workflows run deterministic steps and call agents when a step needs judgment. Memory holds state beside them. Connections govern what your system reaches out to; access governs who reaches in.

Agents

Agent — An actor that can reason. You give it a fuzzy set of instructions and it decides what to do. Use it when you want to chat with your system, offload tasks that resist exact steps, or add judgment inside a workflow. Agents can have tools, restricted profiles, and a team of subagents to delegate to.

Channel — The glue between an agent and the chat interface you already use. Use it when your team lives in Slack or Linear, or you want the agent embedded in your own website. Declare the binding and the agent answers there.

Workflows

Workflow — A deterministic set of instructions: a standard operating procedure you can declare, version, and reuse. Use it when you already have a procedure and want it to run the same way every time. Workflows are also available to agents as tools, so the fuzzy layer can invoke the exact one.

Nodes — The steps inside a workflow. Sixteen types, seven jobs: think (agent, ai), compute (code), reach out (http, email, scrape, bucket), branch and repeat (switch, map, while, parallel, wait), remember (stream, disk, postgres), compose (workflow), and ask a person (review).

Trigger — The glue between the outside world and a workflow. Use it when something external should start a run. Three sources:

• Form — collect input from a person. You already use forms; now they start workflows.
• Webhook — call a workflow programmatically. Anything that speaks HTTP can start a run.
• Schedule — recurring runs on a cron. Automate the procedure you already repeat.

Schema — The contract between steps: JSON Schema for inputs and outputs, declared once and reused across forms, webhooks, and nodes.

Review — A step that waits for a person. Use it when a human must approve before the run continues.

Memory

Stream — Swirls-managed storage for workflow output. Structured, typed records. Use it when you want to persist what a workflow produced and reuse it, in other workflows or later runs of the same one.

Disk — A file system. Unstructured blob storage shared between workflows and agents. Use it when you need shared working files, control over a file system's contents, or a workspace for an agent. Agents are very good at navigating file systems.

Postgres — The PostgreSQL database you already have, declared with its table schemas. Use it when workflow steps should read or write your existing records with parameterized SQL.

Connections

How your system talks to the outside world, in increasing order of how much Swirls manages for you:

Secret — Sensitive values, declared by name in the file and stored in the vault. Use it when you hold the key. Every app needs secrets; nodes receive only the vars they declare.

Auth — A reusable description of a credential you hold: OAuth client credentials, API key header, basic, bearer. Use it when HTTP nodes call APIs with your own credentials, or to gate a public form.

Connection — Brokered OAuth. Declare a provider slot; authorize once in the Portal; short-lived tokens at run time. Use it for Slack, Linear, Discord, LinkedIn, or Microsoft. No keys to manage, nothing to leak. Prefer this when the provider is supported.

Access

Who may reach in. The mirror image of connections.

Role — A name derived from verified identity facts. Your identity source (Swirls users or your IdP) asserts facts like department: finance; match rules in the file decide what they mean. Use it when you already have an org chart and want to map it to Swirls.

Policy — Grants that attach roles to agents and workflows. Declaring a grant flips the project to deny by default. Use it when you want to control who can talk to an agent or start a workflow.

Where to go next

• Know what you want but not which primitives? See From intent to primitives.
• Ready to write? Start with Writing Swirls and the quickstart.
• Want working examples? Fork a cookbook recipe.