The short version
- A workflow is one tool made of up to 10 steps:
sql,http,checkandset, run in order. - The agent makes one call and gets back only what
returnsays. 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.
| What | Syntax |
|---|---|
| Values | 12 3.5 'text' true false null |
| Paths | input.email order.total rows[0].id row["odd name"] |
| Operators | ! * / % + - < <= > >= == != && || ( ) |
| Dates | now() days_since(t) hours_since(t) |
| Text | lower(s) upper(s) trim(s) contains(a, b) starts_with(s, p) string(x) |
| Numbers | round(x, digits) abs(x) min(a, b) max(a, b) number(x) |
| Other | len(x) (text, list or object) coalesce(a, b, …) |
- A path that doesn't exist, or goes through
null, isnull. Soorder != nullis the way to ask "was it found?". - Postgres returns
numericandbigintas 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. Comparingnullor 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.