Primitives

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

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

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. Interfaces put a generated app on top for the people who use the system.

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.

Skill — A package of knowledge for an agent: docs, playbooks, and examples in a folder it reads on demand. Use it when the agent needs your domain expertise, house style, or procedures. Declare the block, keep the files in .agents/skills/<name>/, list it in the agent's skills:.

MCP — A slot for a remote MCP server. Declare the slot and https url: in the file; bind an optional bearer token per project in Cloud; the agent discovers its tools at run time. Use it when an agent should use tools you already expose over MCP. MCP tools are for agents only; workflows use nodes.

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. Twenty types, seven jobs: think (agent, ai), compute (code), reach out (http, integration, email, scrape, search, parallel, bucket), branch and repeat (switch, map, fanout, while, wait), remember (stream, disk, database, postgres), compose (workflow), and ask a person (review). The parallel node is Parallel.ai web research, not workflow concurrency; use search for query-centric Firecrawl discovery. Branch the DAG to run fixed steps side by side; use fanout for concurrent per-item iteration or map when each item needs the previous result.

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.

View — A spreadsheet over your streams. Map each stored row into a table and add computed columns that run a graph per row. Use it when you want to see and work with stream data as a table, or add a per-row column calculated by a graph (for example, an AI enrichment).

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.

Database — A PostgreSQL database Swirls provisions and manages for you, declared with a Prisma schema instead of a connection string. Use it when you want a relational database without running one yourself, queried through a database node's generated typed client (context.db.<name>) instead of raw SQL.

Migration — An ordered, run-once data transform against a managed database. Use it when a schema change needs a backfill or rewrite the schema alone can't express. Declare the block, review it, approve it with swirls migrate apply.

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.

Credential profile — A reusable description of credential shape, declared as an auth block: OAuth client credentials, API key header, basic, bearer. Use it when HTTP nodes call APIs with your own credentials, or to password-gate a public form with type: basic.

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.

Action — A typed operation on a provider API: method, path, and input and output schemas declared once, called from integration nodes through a connection. Use it when workflows call provider APIs and you want the request and response typed. Install prebuilt actions with swirls add <provider>.

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.

Interfaces

Every other primitive declares what the system is. Interfaces declare who it is for.

App — A generated application surface over your deployment. Declare what the app is for and which agents, workflows, views, and databases it exposes; Swirls composes the interface at deploy time and renders it with live data. Use it when you want a portal or dashboard without hand-building a frontend. Add a view block, push, and the app grows a page.

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.