Skip to content

Define Flow Contracts

How do you make a flow reusable? Define its inputs and types, declare its outputs, and map them in Return response. If no Return completes, a successful flow returns {}.

These example contracts belong to Invoice intake, in the development version:

Flow Required inputs Outputs Purpose
Check invoice Invoice ID: text; Amount: number invoice_id: text; review_needed: boolean Flag amounts over 1000.
Store invoice Invoice ID: text; Amount: number; Review needed: boolean invoice_id: text; status: text Accept the decision for later storage.

In the app: open Workflows → Invoice intake → Dev. Create a missing flow with New flow. Then open Inputs → Add new input and set Display name, type, and Required.

With an assistant: every workflow-scoped tool call carries an explicit workflowId. Start with the workflow list from workflow_list.

{ "limit": 100 }

Take Invoice intake’s data.items[].id as <workflowId>. If several match, ask which one. limit caps at 100; if data.hasMore is true, copy the exact ID from the app.

List its flows with flow_list.

{ "workflowId": "<workflowId>" }

Use the data.items[].id of each existing flow. Create the missing ones with flow_create, and note each data.flowId: Check invoice as <flowId>, Store invoice as <storeFlowId>.

{ "workflowId": "<workflowId>", "name": "Check invoice" }
{ "workflowId": "<workflowId>", "name": "Store invoice" }

Read both contracts with flow_get before adding fields. A label that already exists creates a second input. Compare the data.flowInputs IDs, labels, types, and optional values, and look at data.flowOutputs.

{ "workflowId": "<workflowId>", "flowId": "<flowId>" }

Call flow_get again with <storeFlowId>. Add only the missing declarations with flow_input_add, one call per input, with optional: false for a required input:

{ "workflowId": "<workflowId>", "flowId": "<flowId>", "display": "Invoice ID", "type": "text", "optional": false }
{ "workflowId": "<workflowId>", "flowId": "<flowId>", "display": "Amount", "type": "number", "optional": false }
{ "workflowId": "<workflowId>", "flowId": "<storeFlowId>", "display": "Invoice ID", "type": "text", "optional": false }
{ "workflowId": "<workflowId>", "flowId": "<storeFlowId>", "display": "Amount", "type": "number", "optional": false }
{ "workflowId": "<workflowId>", "flowId": "<storeFlowId>", "display": "Review needed", "type": "boolean", "optional": false }

A required input still accepts a blank invoice ID or a negative amount. Use If / Else to route invalid invoices to an explicit invalid-input result. Only when skips just its node.

Caller Missing-value behavior
External workflow API Rejects any missing declared required input before creating an execution. flow_inputs accepts IDs, stored names, or display names; unknown keys and conflicting aliases are rejected.
Trigger or subflow Validates referenced inputs only: missing required values fail the frame; omitted optional values become null; unused inputs are ignored. Stored default metadata does not fill them.
Development root-flow test Uses supplied values or saved test values for referenced inputs; absent text becomes "", other absent types become null.
Isolated-node test Requires every referenced flow-input ID explicitly; omission fails with ISOLATED_FLOW_CONTEXT_REQUIRED. Explicit null, "", false, and zero count as supplied.

In the app: add each output under Outputs → Add new output. Then choose Add action → Actions, search Return response, and configure every field.

With an assistant: add only the missing outputs with flow_output_add, each with an explicit caller-facing name:

{ "workflowId": "<workflowId>", "flowId": "<flowId>", "display": "Invoice ID", "name": "invoice_id", "type": "text" }
{ "workflowId": "<workflowId>", "flowId": "<flowId>", "display": "Review needed", "name": "review_needed", "type": "boolean" }
{ "workflowId": "<workflowId>", "flowId": "<storeFlowId>", "display": "Invoice ID", "name": "invoice_id", "type": "text" }
{ "workflowId": "<workflowId>", "flowId": "<storeFlowId>", "display": "Status", "name": "status", "type": "text" }

Then find Return response with integration_action_list:

{ "query": "Return response" }

Note Return response’s data.items[].nodeSlug as <slug> and its paired key as <componentKey>. Reuse a Return that already exists. Otherwise inspect the discovered action with integration_action_get and add it with node_add.

{ "integration": "<slug>", "key": "<componentKey>" }
{ "workflowId": "<workflowId>", "flow": "<flowId>", "node": "<slug>", "key": "<componentKey>", "name": "Return decision" }

Note the new data.nodeId as <nodeId>. For an existing Return, use its data.nodes[].id from flow_get. Read each Return field’s bindings with expr_context, once with "prop": "invoice_id" and once with "prop": "review_needed":

{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "invoice_id" }

Use the current data.flow[].js names. If they are flow.invoiceId and flow.amount, set each with node_prop_set and js:

{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "invoice_id", "js": "flow.invoiceId" }
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "review_needed", "js": "flow.amount > 1000" }

Wire producers directly into the Return when a field reads their output. This example reads flow inputs. Fill Store invoice’s Return when you implement storage.

A completed Return writes every output, not only the ones you set. Untouched text writes "", and untouched non-text writes null. Later completed Returns overwrite earlier values. Use one complete Return per execution path.

Output edits synchronize every Return automatically, despite the stale flow_output_add warning. A rename rekeys the field. A type change that changes the editor resets values and expressions. Reread each Return after a contract edit.

An input’s ID, stored name, display label, and current expression binding differ. A label change recomputes the bindings, while stored expressions keep their IDs. An output’s name is the caller’s key; retain it during a display rename by keeping flow_output_update’s name unchanged.

In the app: edit Amount’s Display name under Inputs. With an assistant: take Amount’s data.flowInputs[].id from flow_get as <inputId> and rename it with flow_input_update, which takes input for the input ID and display for its label:

{ "workflowId": "<workflowId>", "flowId": "<flowId>", "input": "<inputId>", "display": "Invoice amount" }

Read the binding back with expr_context and expr_decompile, each called with:

{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "prop": "review_needed" }

Deleting and recreating an input removes the old caller mappings and leaves dangling expressions. Validation reports DANGLING_FLOW_INPUT_REFERENCE, and evaluation fails. Rename in place, or repair the dependents.

In the app: select Dev → Check invoice → Test, then inspect Run history. These tests only decide, so they store no invoices.

With an assistant: lay out the flow with flow_layout ({ "workflowId": "<workflowId>", "flowId": "<flowId>" }), validate it with workflow_validate ({ "workflowId": "<workflowId>" }), and read its inputs with run_inputs:

{ "workflowId": "<workflowId>", "nodeIdOrFlowId": "<flowId>", "flow": true }

From the returned data.flowInputs[].id values, use Invoice ID as <invoiceInputId> and Invoice amount as <amountInputId>.

Run the flow below and above the review threshold with run_flow.

{ "workflowId": "<workflowId>", "flowId": "<flowId>", "target": "dev", "inputs": { "<invoiceInputId>": "INV-104", "<amountInputId>": 120 } }
{ "workflowId": "<workflowId>", "flowId": "<flowId>", "target": "dev", "inputs": { "<invoiceInputId>": "INV-105", "<amountInputId>": 1500 } }

Check each data.output. Expect the matching invoice_id, with review_needed false then true. A Run flow caller receives these named outputs. Tab order does not call Store invoice. Continue with Loop and Reuse Flows.