Primitives

A primitive declares one part of a Swirls system. Agents, workflows, storage, connections, access rules, and interfaces compose into a project; the platform provisions their resources and runs their work. Learn the six families below, then follow the links for declarations and field reference.

Read Platform overview for the project and deployment model, or Infrastructure for where these resources run.

                 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, SDK calls, and published MCP tools can start workflows, whose nodes call agents and external services. Memory stores data and files; connections supply outbound credentials; access rules restrict invocation. People use your own application, an external assistant, or a hosted Swirls App. See Build apps with Swirls for that boundary.

Agents

• Agent: a persistent model-driven worker with instructions, tools, profiles, and optional subagents. Use it for conversation and tasks that need judgment or multiple tool calls.
• Channel: binds an agent to a chat platform, shared app room, or web embed. MCP channels publish an agent, selected workflows, or both.
• Skill: reference material the agent reads on demand. Keep the files in .agents/skills/<name>/, declare a skill block, and list it in the agent's skills:.
• MCP: a remote tool server. Declare its URL and auth mode, then bind or connect credentials per project in Cloud. Agents discover its tools at runtime; workflows use node types for external calls.

Workflows

• Workflow: steps and dependencies for a procedure you can version and reuse. Agents can call workflows as tools.
• Decision: reusable typed questions for Jev. A workflow supplies state and receives probabilities for explicit routing, review, and model selection.
• Nodes: the steps within a workflow. The 20 types cover model calls (agent, ai, decision), computation (code), external services (http, integration, email, scrape, search, parallel), control flow (switch, map, fanout, while, wait), storage (stream, disk, database, postgres), and child workflows (workflow).
• Trigger: binds a form submission, webhook request, or schedule to a workflow.
• Form: collects input from a person using a declared schema.
• Webhook: accepts an HTTP request to start work.
• Schedule: starts recurring work on a cron expression.
• Schema: reusable JSON Schema for inputs and outputs across forms, webhooks, and nodes. File uploads use schema-marked file values.
• Review: pauses a workflow node for approval or form input from a person.
• Playbook: a hosted test suite with fixtures, assertions, mocks, and optional model judges. Run it with swirls test.
• Mock: substitutes outputs for external calls or review responses during playbook runs. Node mocks name both workflow: and node:.

Use map for sequential iteration with access to the previous result, fanout for concurrent per-item work, or separate DAG branches for fixed parallel steps. The parallel node calls Parallel.ai for web research; search provides query-based web discovery.

Memory

• Stream: typed, versioned records produced by a workflow and available to other runs.
• View: a table over stream records, with optional computed columns that run a workflow per row.
• Disk: persistent files shared by workflows and agents. Workflows run commands against the disk; agents mount it in their sandboxes.
• Database: PostgreSQL provisioned by Swirls from a Prisma schema. Workflow nodes query it through the generated client at context.db.<name>.
• Migration: an ordered, run-once data transform for a managed database. Use it for backfills and rewrites that a schema change cannot express. Approve with swirls migrate apply.
• Postgres: a database you already operate. Declare its connection and table schemas, then query it with parameterized SQL.

Connections

• Secret: named sensitive values stored in the project vault. Nodes receive the variables their declarations request.
• Credential profile: an auth block describing how to apply credentials to HTTP requests. Supports OAuth client credentials, API keys, basic auth, and bearer tokens. Basic auth can also protect public forms.
• Connection: a named outbound credential slot. Swirls brokers OAuth for supported providers; self-managed connections use vault credentials.
• Action: a provider API operation with transport and input/output schemas. Call it from an integration node through a connection; install catalog actions with swirls add <provider>.
• Connector: an inbound OAuth application that authenticates external MCP clients accessing published agents and workflows through a platform: mcp channel.

Access

• Role: a name derived from verified identity attributes. A match block can map facts such as department: finance to a role.
• Policy: grants that determine which agents a role may invoke and which workflows it may start directly. Agent grants also accept nested workflow and tool restrictions. Adding a grant changes the project to deny by default. See enforcement for the current scope of those restrictions.

Interfaces

App

An app is a hosted workspace with navigation, OpenUI pages, workflow review inboxes, shared chat rooms, and thread directories. Use it when a team needs an interface to a deployed system. Shared rooms reference a channel { platform: swirls } through an app channel: page.

An app block is optional. A custom frontend, API, or MCP server can call the same backend through the SDK. A managed MCP channel hosts the external tool interface for declared workflows and agents.

Where to go next

• From intent to primitives: choose primitives for a specific task.
• Writing Swirls: declaration syntax and embedded code.
• Quickstart: deploy your first project.
• Cookbook: workflow examples.