Developer docs

Workflow tools: several steps in one call

Updated 7 Oct 2026 · Tools

On this page
  1. How it works
  2. Recipe: refund an order
  3. Recipe: weekly signups to Slack
  4. Recipe: a customer across DB + Stripe
  5. Expressions
  6. Failures and transactions
  7. Limits

The short version

  • A workflow is one tool made of up to 10 steps: sql, http, check and set, run in order.
  • The agent makes one call and gets back only what return says. Fewer round trips, and no raw rows it doesn't need.
  • Checks run before writes, so "refund only if under $200" is enforced by the tool, not by the agent's judgement.
  • The first failing step stops the run, and the error says which step, what already ran and what was rolled back.
  • It's JSON interpreted by Saywire, never code you upload. Same egress rules, secrets and read-only mode as any tool.

1How it works

Steps share a scope. input holds the arguments the agent passed; every step with an id adds its result under that name: a SQL step's rows (or its first row with "one": true), an HTTP step's JSON, a set step's value. Later steps read them as paths such as order.total_cents, in expressions (check.if, set.value, SQL params) and as {{order.id}} placeholders in HTTP paths, bodies and return. Placeholders in paths are URL-encoded; a body value that is exactly "{{x}}" keeps its type.

{
  "kind": "workflow",
  "name": "refund_order",
  "description": "…",
  "inputSchema": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": ["order_id"] },
  "access": "write",
  "enabled": false,
  "transaction": true,
  "steps": [ … up to 10 … ],
  "return": { … what the agent gets back … }
}

A workflow is a write tool if any step writes (a SQL write or any request that isn't GET); it starts turned off, like every write tool. The editor checks references before you save: a step can only read inputs that exist and steps that come before it. Test it from the Tools tab: the run shows each step's status, time and output.

2Recipe: refund an order

Look the order up, refuse anything a person should look at, mark it, then ask your billing service to refund it. Connections: a database (shop_db) and your own billing API (billing_api). With transaction, the status change is rolled back if the refund call fails.

"steps": [
  { "id": "order", "kind": "sql", "connection": "shop_db",
    "query": "select id, total_cents, created_at, status from orders where id = $1",
    "params": ["input.order_id"], "one": true },
  { "kind": "check", "if": "order != null", "fail": "Order {{input.order_id}} not found" },
  { "kind": "check", "if": "order.status == 'paid'", "fail": "Order is {{order.status}}, not paid" },
  { "kind": "check", "if": "order.total_cents <= 20000 && days_since(order.created_at) <= 30",
    "fail": "Over $200 or older than 30 days: needs a person" },
  { "kind": "sql", "connection": "shop_db",
    "query": "update orders set status = 'refunding' where id = $1", "params": ["input.order_id"] },
  { "id": "refund", "kind": "http", "connection": "billing_api", "method": "POST", "path": "/refunds",
    "body": { "order_id": "{{input.order_id}}", "amount_cents": "{{order.total_cents}}" } }
],
"transaction": true,
"return": { "refund_id": "{{refund.id}}", "amount_cents": "{{order.total_cents}}" }

Stripe's v1 API takes form-encoded request bodies, which HTTP steps don't send yet (they send JSON). To refund through Stripe directly today, call a small endpoint of your own that does it, as above; reading from Stripe works as is (next recipes).

3Recipe: weekly signups to Slack

Let SQL do the counting, build one line of text, post it with Slack's chat.postMessage (an HTTP integration for https://slack.com/api with a bot token as bearer auth). Slack answers HTTP 200 even on errors, so a check reads its ok field. Ask your agent to run it every Monday, or call it from any MCP client on a schedule.

"steps": [
  { "id": "week", "kind": "sql", "connection": "app_db", "one": true, "params": [],
    "query": "select count(*) as total, count(*) filter (where a.plan = 'pro') as pro, count(*) filter (where a.plan = 'team') as team from users u join accounts a on a.id = u.account_id where u.created_at > now() - interval '7 days'" },
  { "id": "text", "kind": "set",
    "value": "'Signups this week: ' + week.total + ' (' + week.pro + ' pro, ' + week.team + ' team)'" },
  { "id": "posted", "kind": "http", "connection": "slack", "method": "POST", "path": "/chat.postMessage",
    "body": { "channel": "#growth", "text": "{{text}}" } },
  { "kind": "check", "if": "posted.ok == true", "fail": "Slack said: {{posted.error}}" }
],
"return": { "posted": "{{text}}" }

4Recipe: a customer across your database and Stripe

One read-only call that answers "what's going on with this customer?": your user row, then their subscriptions and recent invoices from Stripe. select (JSONPath) drops Stripe's list envelope, and limit keeps the lists short.

"steps": [
  { "id": "user", "kind": "sql", "connection": "app_db", "one": true,
    "query": "select id, email, stripe_customer_id, created_at from users where lower(email) = lower($1)",
    "params": ["input.email"] },
  { "kind": "check", "if": "user != null", "fail": "No user with that email" },
  { "kind": "check", "if": "user.stripe_customer_id != null", "fail": "This user has never paid" },
  { "id": "subs", "kind": "http", "connection": "stripe", "method": "GET",
    "path": "/v1/subscriptions?customer={{user.stripe_customer_id}}&status=all&limit=5",
    "select": "$.data" },
  { "id": "invoices", "kind": "http", "connection": "stripe", "method": "GET",
    "path": "/v1/invoices?customer={{user.stripe_customer_id}}&limit=5",
    "select": "$.data" }
],
"return": { "user": "{{user}}", "subscriptions": "{{subs}}", "recent_invoices": "{{invoices}}" }

5Expressions

A small language for conditions and computed values. It's parsed and interpreted by Saywire; there's no eval and nothing to import.

WhatSyntax
Values12 3.5 'text' true false null
Pathsinput.email order.total rows[0].id row["odd name"]
Operators! * / % + - < <= > >= == != && || ( )
Datesnow() days_since(t) hours_since(t)
Textlower(s) upper(s) trim(s) contains(a, b) starts_with(s, p) string(x)
Numbersround(x, digits) abs(x) min(a, b) max(a, b) number(x)
Otherlen(x) (text, list or object) coalesce(a, b, …)
  • A path that doesn't exist, or goes through null, is null. So order != null is the way to ask "was it found?".
  • Postgres returns numeric and bigint as text; comparisons and arithmetic treat numeric text as numbers.
  • Timestamps arrive as ISO text, so days_since(order.created_at) works directly, and ISO dates compare correctly as text.
  • + adds numbers and joins text. Comparing null or mixed types is always false.

6Failures and transactions

Steps run one after another. The first one that fails (a check that isn't true, a SQL error, an HTTP status of 400 or more, an expression error) stops the run, and the agent gets an error like this instead of return:

Workflow "refund_order" stopped at step 6 of 6 (http refund): HTTP 409: {"error":"already refunded"}
Already done: step 1 (sql order), step 2 (check), step 3 (check), step 4 (check), step 5 (sql).
Rolled back: step 5 (sql).
  • With "transaction": true, every SQL step runs in one transaction that commits only after the last step. Any failure, including a check or an HTTP step after the SQL, rolls the database changes back. All SQL steps must use the same database.
  • Without it, each SQL step commits on its own (read-only unless the step writes).
  • HTTP calls can't be undone. The error lists each one that already ran as "changes already made and not undone", so the agent can tell the user.
  • Put checks before writes, and the riskiest write (usually the API call) last.

7Limits

  • Up to 10 steps, no loops. One workflow call counts as one call in your usage.
  • 25 seconds for the whole run; each SQL statement 5 s; each HTTP request 20 s. The response to the agent is capped at 256 KB.
  • SQL steps are single, parameterized statements ($1, $2…), up to 500 rows each.
  • On a read-only server, write workflows are hidden. If any integration a workflow uses is paused, the call is refused without running anything.
  • Call logs record each step's kind, status and time, never its values.