Agents

What it is. An actor that can reason. You give it a fuzzy set of instructions and it decides what to do, unlike a workflow, which follows exact steps.

Use it when you want to chat with your system, offload tasks that resist exact procedures, or add a judgment step inside a workflow. Agents can carry tools, restricted profiles, and a team of subagents.

Works with channels (chat surfaces), skills (knowledge packages), MCP servers (remote tools), workflows (as a node, or with workflows as the agent's tools), disks (a workspace), and access roles (who may invoke it).

An agent block defines a persistent LLM worker. It has a model, a secret, and optional tool workflows, skills, MCP server slots, and profiles. Invoke the agent from a workflow with a type: agent node, chat with it in Swirls Cloud or from the CLI, or expose it on a channel.

When to use agent vs ai

Use type: ai for a single model call that returns a value. Use type: agent when the model needs to reason, call tools, or work on files over multiple steps.

The agent block

The agent block is a top-level declaration. A workflow node references it by name.

secret llm_creds {
  vars: [ANTHROPIC_API_KEY]
}

agent support_agent {
  label: "Support Agent"
  description: "Triages support tickets and drafts responses."
  provider: anthropic
  model: "claude-3-5-sonnet-20241022"
  secrets: llm_creds
  maxSteps: 15
  system: @ts {
    return "You are a support agent. Use the available tools to investigate and resolve tickets."
  }
  tools: [lookup_ticket, post_reply]

  profile escalation {
    description: "Handles escalated tickets with expanded tool access"
    system: @ts {
      return "You are a senior support agent. Be thorough. Document every action you take."
    }
    tools: [lookup_ticket, post_reply]
  }
}

Field reference

Provider and secret key

Each provider expects a specific variable in the secret block:

The key must appear in the vars list of the referenced secret block. Set its value with swirls env set or the project vault. See Secrets and auth.

Profiles

A profile scopes the agent to a specific persona. Declare it inside the agent block with profile <name> { }.

The agent node selects a profile with profile: <name>. When a profile declares tools, skills, or mcp, those become the effective sets. When it declares system, that overrides the agent's system prompt.

A profile cannot override model, provider, secrets, team, wallet, or disks. Profiles apply on the workflow-node path; chat sessions use the agent's default system prompt.

A profile controls what the agent may do when it runs. To control who may invoke the agent at all, use the top-level role and policy blocks. See Access control.

Subagent teams

An agent can delegate to other agents. List them in the team field. Each team member becomes a callable tool that the model invokes with a task description. The member runs as its own agent, with its own model, tools, and sandbox, and returns its result to the caller.

Use teams to compose specialists. One orchestrator routes work to focused agents instead of holding every tool and instruction itself.

secret vendor_keys {
  vars: [OPENROUTER_API_KEY]
}

agent researcher {
  label: "Researcher"
  secrets: vendor_keys
  model: "openai/gpt-4o-mini"
  tools: [search_kb]
  system: @ts {
    return "Research the question and return concise findings with sources."
  }
}

agent writer {
  label: "Writer"
  secrets: vendor_keys
  model: "openai/gpt-4o-mini"
  system: @ts {
    return "Turn findings into clear, well-structured prose."
  }
}

agent orchestrator {
  label: "Orchestrator"
  secrets: vendor_keys
  model: "google/gemini-3.1-flash-lite"
  maxSteps: 16
  team: [researcher, writer]
  system: @ts {
    return [
      "You coordinate specialists.",
      "Call a team tool with a clear task describing what to do.",
      "Relay the specialist's answer plainly.",
    ].join("\n")
  }
}

Rules

• Team members are referenced by bare identifier, not a quoted string.
• Each member must be a defined agent block in the workspace.
• An agent cannot list itself in its own team.
• A team member name cannot collide with a workflow tool name in the same agent's tools.
• Teams cannot form a cycle. a -> b -> a is a validation error, and so is any longer loop.
• Team members resolve their own skills and mcp lists. They do not inherit the caller's.

Skills and MCP servers

Two more ways to extend an agent, each with its own page:

• Skills package reference material from your repo. Declare a top-level skill block, list it in skills:, and the agent reads the files on demand at runtime.
• MCP servers connect the agent to remote tools. Declare a top-level mcp block as a named slot, list it in mcp:, and bind the slot to a server URL and credential in Swirls Cloud.

The sandbox block

An agent with a sandbox: { } block gets a persistent Linux workspace where it can run code and manipulate files. The block controls the workspace's resources and idle lifecycle, and its presence enables the built-in workspace tools. Mounting disks: enables them too.

agent data_agent {
  model: "gpt-4o"
  secrets: oai_creds

  sandbox: {
    cpus: 2
    memoryMiB: 2048
    diskGiB: 10
    autoStopMinutes: 30
    autoArchiveMinutes: 1440
    autoDeleteMinutes: -1
    ephemeral: false
  }
}

Resource fields

Lifecycle fields

The sandbox provisions lazily. A turn that does not call any workspace tool never starts one. Workspace files persist across turns for the same agent unless ephemeral: true. Scratch files live at /srv/workspace; shared disks listed in disks: mount at /mnt/disks/<name>.

The wallet block

The wallet: { } block gives the agent a tool-spend budget and enables the hosted Zero tools: zero_search (free catalog search), zero_get (inspect a capability's schema), zero_fetch (paid capability calls), and zero_wallet_status (remaining budget). The budget is a per-agent cap enforced per UTC calendar window against your organization's prepaid tool-spend balance.

agent researcher {
  secrets: vendor_keys
  model: "openai/gpt-4o-mini"

  wallet: {
    budget: 50
    cadence: daily
    maxPerCall: 2
  }
}

There is no profile-level wallet override.

The agent node

A type: agent node invokes a top-level agent block from within a workflow. The workflow execution waits for the agent turn to complete, then continues with the agent's output.

node triage {
  type: agent
  label: "Triage ticket"
  agent: support_agent
  profile: escalation
  prompt: @ts {
    return "Investigate and resolve this ticket: " + context.nodes.root.output.description
  }
  schema: @json {
    {
      "type": "object",
      "required": ["resolution", "category"],
      "properties": {
        "resolution": { "type": "string" },
        "category": { "type": "string" }
      },
      "additionalProperties": false
    }
  }
}

Field reference

System prompt precedence

Three layers can contribute a system prompt. Later layers win:

1. Agent system (lowest priority)
2. Profile system (overrides agent)
3. Node system (overrides profile and agent)

Structured output

When a node declares schema, the runtime instructs the model to return a JSON object matching that schema. The validated object becomes the node's output, accessible as context.nodes.<nodeName>.output in downstream nodes.

Good to know: The field is schema, not outputSchema. Writing outputSchema: on an agent node is a parse error.

Tools as workflows

Tools are workflows. There is no separate tool syntax in the DSL. Any workflow can become a tool if it meets three requirements:

1. A non-empty description on the workflow block. The model reads this description to decide when to call the tool.
2. An inputSchema on the root node. This defines the function signature the model sees.
3. An output schema on every leaf node (outputSchema on the root, schema on other leaf nodes). This types the return value.

workflow lookup_ticket {
  label: "Look up ticket"
  description: "Retrieve a support ticket by its ID. Returns the ticket title, description, and current status."

  root {
    type: code
    label: "Entry"
    inputSchema: @json {
      {
        "type": "object",
        "required": ["ticket_id"],
        "properties": { "ticket_id": { "type": "string" } },
        "additionalProperties": false
      }
    }
    outputSchema: @json {
      {
        "type": "object",
        "required": ["ticket_id"],
        "properties": { "ticket_id": { "type": "string" } },
        "additionalProperties": false
      }
    }
    code: @ts {
      return { ticket_id: context.nodes.root.input.ticket_id }
    }
  }

  node fetch {
    type: postgres
    label: "Fetch from DB"
    postgres: main_db
    select: @sql {
      SELECT title, description, status FROM tickets WHERE id = {{ticket_id}}
    }
    params: @ts {
      return { ticket_id: context.nodes.root.output.ticket_id }
    }
    schema: @json {
      {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "description": { "type": "string" },
            "status": { "type": "string" }
          }
        }
      }
    }
  }

  flow {
    root -> fetch
  }
}

The agent lists this workflow in its tools array. When the model decides to look up a ticket, the runtime runs lookup_ticket as a checkpointed workflow execution and returns the output to the model.

How a turn runs

When an agent node executes, the runtime starts a turn:

1. The prompt value becomes the user message.
2. The effective system prompt (from agent, profile, or node) becomes the system message.
3. The model generates a response. If it calls a tool, the runtime runs the corresponding workflow.
4. Tool output returns to the model for the next step.
5. Steps repeat until the model returns a final response without tool calls, or maxSteps is reached.

The default maxSteps is 20. Set it lower to limit cost, or higher for tasks that require many steps.

Every turn assembles one tool set from the agent's declarations: tool workflows, team members, skill tools, MCP tools, and Zero tools when a wallet is declared.

Built-in workspace tools are available when the agent declares a sandbox block or mounts disks: read, write, edit, bash, grep, find, ls. These operate on files inside the agent's sandbox. An agent that declares neither runs with its declared tools only. Tool workflows and built-in tools both count toward maxSteps.

Each turn is durably checkpointed. If the worker restarts mid-turn, the execution resumes from the last completed checkpoint. See How execution works.

Persistent chat

When agent chat is enabled for a hosted project, agents can run as multi-turn chat sessions. The platform stores the full conversation transcript.

In the Portal, the Agents page lists every deployed agent. Open any agent to chat in-app. No platform: web channel required. Sessions are keyed by agent name and stream to /chat/agent/:projectId/:agentName.

For a standalone chatbox link or SDK embed, declare a platform: web channel. Sessions there are keyed by channel name and use /chat/web/:projectId/:channelName.

From the CLI:

swirls chat start support_agent

This starts an interactive session with support_agent. Each message you send becomes the prompt for a new turn. The agent retains its sandbox state and conversation history across messages.

Complete example

This example wires a form trigger to an agent that triages a ticket and posts a Slack notification.

secret llm_creds {
  vars: [ANTHROPIC_API_KEY]
}

agent triage_agent {
  label: "Triage Agent"
  description: "Classifies and routes support tickets."
  provider: anthropic
  model: "claude-3-5-sonnet-20241022"
  secrets: llm_creds
  maxSteps: 10
  system: @ts {
    return "You are a support triage agent. Classify the ticket and determine routing."
  }
  tools: [fetch_kb]

  profile critical {
    description: "For tickets marked urgent"
    system: @ts {
      return "You are handling a critical ticket. Escalate quickly. Be concise."
    }
    tools: [fetch_kb]
  }
}

workflow fetch_kb {
  label: "Search knowledge base"
  description: "Search the knowledge base for relevant articles. Pass a keyword query."

  root {
    type: code
    label: "Entry"
    inputSchema: @json {
      {
        "type": "object",
        "required": ["query"],
        "properties": { "query": { "type": "string" } },
        "additionalProperties": false
      }
    }
    outputSchema: @json {
      {
        "type": "object",
        "required": ["articles"],
        "properties": {
          "articles": { "type": "array", "items": { "type": "string" } }
        },
        "additionalProperties": false
      }
    }
    code: @ts {
      return { articles: ["Article A", "Article B"] }
    }
  }
}

workflow triage_ticket {
  label: "Triage Ticket"

  root {
    type: code
    label: "Entry"
    inputSchema: @json {
      {
        "type": "object",
        "required": ["subject", "body", "priority"],
        "properties": {
          "subject": { "type": "string" },
          "body": { "type": "string" },
          "priority": { "type": "string" }
        },
        "additionalProperties": false
      }
    }
    outputSchema: @json {
      {
        "type": "object",
        "required": ["subject", "body", "priority"],
        "properties": {
          "subject": { "type": "string" },
          "body": { "type": "string" },
          "priority": { "type": "string" }
        },
        "additionalProperties": false
      }
    }
    code: @ts {
      return {
        subject: context.nodes.root.input.subject,
        body: context.nodes.root.input.body,
        priority: context.nodes.root.input.priority
      }
    }
  }

  node run_agent {
    type: agent
    label: "Triage with agent"
    agent: triage_agent
    profile: critical
    prompt: @ts {
      const { subject, body } = context.nodes.root.output
      return `Triage this ticket.\nSubject: ${subject}\nBody: ${body}`
    }
    schema: @json {
      {
        "type": "object",
        "required": ["category", "suggested_response"],
        "properties": {
          "category": { "type": "string" },
          "suggested_response": { "type": "string" }
        },
        "additionalProperties": false
      }
    }
  }

  flow {
    root -> run_agent
  }
}

Common mistakes

outputSchema on an agent node

The field is schema, not outputSchema. Using outputSchema on a type: agent node is a parse error.

// Incorrect
node triage {
  type: agent
  agent: triage_agent
  prompt: @ts { return "Triage this ticket" }
  outputSchema: @json { { "type": "object" } }
}

// Correct
node triage {
  type: agent
  agent: triage_agent
  prompt: @ts { return "Triage this ticket" }
  schema: @json { { "type": "object" } }
}

secrets: as a quoted string

The secrets field on an agent block takes a bare identifier, not a quoted string. A quoted value silently fails to resolve.

// Incorrect
agent bad_agent {
  model: "gpt-4o"
  secrets: "llm_creds"
}

// Correct
agent good_agent {
  model: "gpt-4o"
  secrets: llm_creds
}

Provider and secret key mismatch

Each provider resolves a specific key name. If the variable in your secret block does not match the expected name, the agent fails at runtime.

// Incorrect: provider is anthropic but secret declares the wrong key
secret bad_creds {
  vars: [OPENROUTER_API_KEY]
}

agent bad_agent {
  provider: anthropic
  model: "claude-3-5-sonnet-20241022"
  secrets: bad_creds
}

// Correct
secret llm_creds {
  vars: [ANTHROPIC_API_KEY]
}

agent good_agent {
  provider: anthropic
  model: "claude-3-5-sonnet-20241022"
  secrets: llm_creds
}

system as a plain string

The system field on an agent block or agent node must be a @ts { } block. A plain string is rejected.

// Incorrect
agent bad_agent {
  model: "gpt-4o"
  secrets: llm_creds
  system: "You are a helpful assistant."
}

// Correct
agent good_agent {
  model: "gpt-4o"
  secrets: llm_creds
  system: @ts {
    return "You are a helpful assistant."
  }
}

Profile tools not a subset of agent tools

A profile's tools must be a subset of the agent's tools. Listing a workflow in a profile that is not in the agent's tools is a validation error.

// Incorrect: post_reply is not in the agent's tools list
agent bad_agent {
  model: "gpt-4o"
  secrets: llm_creds
  tools: [lookup_ticket]

  profile escalation {
    tools: [lookup_ticket, post_reply]
  }
}

// Correct
agent good_agent {
  model: "gpt-4o"
  secrets: llm_creds
  tools: [lookup_ticket, post_reply]

  profile escalation {
    tools: [lookup_ticket, post_reply]
  }
}

Tool workflow missing description, inputSchema, or leaf schema

A workflow used as a tool must declare a non-empty description, an inputSchema on its root node, and an output schema on every leaf node. Missing any of these causes the tool to be silently unusable.

See Tools as workflows for the full contract.

Expecting workspace tools without a sandbox

The built-in workspace tools (read, write, edit, bash, grep, find, ls) register only when the agent declares a sandbox block or mounts disks. An agent with neither gets its declared tools only, and file or shell instructions in the prompt go nowhere.

// Workspace tools available: sandbox declared
agent builder {
  model: "gpt-4o"
  secrets: llm_creds
  sandbox: {
    cpus: 1
  }
}

Further reading

• Skills: Package knowledge from your repo and let the agent read it on demand.
• MCP servers: Give the agent tools from remote MCP servers, bound per project in Swirls Cloud.
• Channels: Expose an agent as a chat assistant on Slack, Linear, Discord, or the web.
• Workflows: DAG structure, edges, and subgraphs.
• Node types: All 20 node types including the agent node.
• Secrets and auth: secret blocks and provider key setup.
• How execution works: Checkpointing, durable execution, and the agent turn loop.
• Common mistakes: Parser errors and silent drops.