Workflows & DSL

Anatomy of a workflow

A workflow definition is a single root Workflow node whose children execute in order. Children can be nested groups, so the whole document forms a tree:

{
  "type": "Workflow",
  "id": "support-triage",
  "participants": [
    { "name": "customer", "bind": "run_initiator", "surface": "widget" }
  ],
  "children": [
    { "type": "Message", "id": "hello", "content": "Hi! Tell us what happened." },
    { "type": "Input", "id": "issue", "prompt": "Describe the issue",
      "input_type": "TextArea", "participant_role": "customer" },
    { "type": "Agent", "id": "triage",
      "prompt": "Classify this support issue: {{issue}}" }
  ]
}

Each node has a type discriminator, a unique id among its siblings, and writes its result into run state under that id — so later nodes can reference {{issue}} or {{triage.urgency}}.

The authoritative JSON Schema is public at GET /api/v1/schema/workflow — point your editor or CI at it for instant validation.

Node types

Bulk execution

Use Parallel for a small static set of durable branches. Use WorkflowCall.for_each when one child workflow should process an array. Durable mode creates recoverable child runs; ephemeral mode runs an eligible synchronous target inline.

Template variables

Any string field can reference run state with {{path.to.value}}. Paths resolve with scope walking — the engine looks in the current group scope first, then parents, then root state:

{{issue}}                 → value captured by the "issue" node
{{triage.urgency}}        → field extracted by the "triage" agent
{{personal.name}}         → value inside the "personal" group

When a string is only a template reference (e.g. "{{search.results}}"), the raw value is passed through with its native type — arrays stay arrays. Mixed strings like "Hello {{name}}" resolve to text.

Declared run inputs

The root node's optional inputs array declares the typed fields callers supply when starting a run via POST /api/v1/runs:

"inputs": [
  { "id": "name", "input_type": "Text", "required": true },
  { "id": "plan", "input_type": "SingleSelect",
    "options": ["free", "pro", "enterprise"], "default": "free" }
]

The API validates the input payload against these declarations and rejects bad requests with 422. Validated values are written into initial run state, reachable as {{name}}, {{plan}}, etc. Workflows without declared inputs accept arbitrary JSON.

Participants & surfaces

The root participants array names everyone involved in a run and defines two things per participant:

• Bind strategy — how the name resolves to real user(s): run_initiator, deployer, static (fixed email / user id), tenant_member, team_member, or unbound.
• Surface — the transport they communicate over: widget, widget/voice, inbox, form, phone, messaging/whatsapp, messaging/telegram, and more. Voice is a mode of a transport, selected via config.style (push_to_talk, continuous, live). See Surfaces & transports.

"participants": [
  { "name": "requester", "bind": "run_initiator", "surface": "widget" },
  { "name": "caller", "bind": "run_initiator", "surface": "widget/voice", "config": { "style": "live" } },
  { "name": "approver", "bind": "team_member", "team": "finance", "surface": "inbox" }
]

HITL nodes (Input, Agent, Message…) target a participant via participant_role. External participants join with participant tokens matching that role name.

Branching & conditions

Conditional and Loop nodes evaluate conditions over state. Operators include eq, neq, gt, gte, lt, lte, contains, starts_with, in, exists and their negations. Conditions compose with and / or / not:

{
  "type": "Conditional",
  "id": "route",
  "condition": {
    "type": "and",
    "conditions": [
      { "field": "triage.urgency", "op": "eq", "value": "high" },
      { "field": "plan", "op": "in", "value": ["pro", "enterprise"] }
    ]
  },
  "then": [ { "type": "Message", "id": "fast", "content": "Priority lane!" } ],
  "else": [ { "type": "Message", "id": "norm", "content": "We'll be in touch." } ]
}

Conversational agents

Set an Agent to mode: "converse" when it should gather structured information over several adaptive turns. The effective participant surface selects the runtime: text, push-to-talk, and continuous voice use turn-based collection; an eligible widget/voice participant with config.style: "live" uses one persistent Gemini Live conversation.

Agent reliability controls

Agent nodes support ordered fallback_models, model reasoning controls, per-call tool_choiceand tool_timeout_ms, plus cumulative token, tool-call, and iteration limits. The model catalogue identifies structured-output, reasoning, caching, and vision capabilities so unsupported controls are explicit in the editor.

{
  "type": "Agent",
  "id": "review",
  "model": "openai/gpt-4.1",
  "fallback_models": ["anthropic/claude-sonnet-4-5"],
  "memory": { "thread": "sales_review" },
  "limits": { "max_total_tokens": 20000, "max_tool_calls": 12, "max_iterations": 8 },
  "tool_choice": "auto",
  "tool_timeout_ms": 15000,
  "output_schema": {
    "type": "object",
    "properties": { "summary": { "type": "string" } },
    "required": ["summary"]
  }
}

Named memory threads are scoped to one run and must be dot-free. Delegate to a registered agent with {"agent":"name"}in tools. Use run_workflowwhen delegation must survive suspension or collect participant input; the parent resumes without replaying completed tools.

Attachments & multimodal input

Add images or documents to an Agent turn with anattachments array. Each entry must be one complete artifact/URL template reference or an absolute HTTP(S) URL. Save-time validation rejects known models withoutsupports_vision; unknown catalogue entries are checked again at runtime.

{
  "type": "Agent",
  "id": "inspect_receipt",
  "model": "openai/gpt-4o",
  "attachments": ["{{upload._artifact}}"],
  "input": "Extract the merchant, date, and total."
}

Connection bindings

Tool and Agent nodes reference a stable requirement slug, such ascrm, instead of an environment-specific connection. Bind that slug to a concrete connection when you deploy. Native providers such as Zoho expose only the operations enabled by the connection's selected capabilities and granted scopes.

{
  "type": "Tool",
  "id": "create-lead",
  "tool": "crm_create_lead",
  "connection": "crm",
  "arguments": { "data": [{ "Last_Name": "{{review.last_name}}" }] }
}

Validation

Input nodes (and declared run inputs) accept deterministic validation rules: required, min / max, min_length / max_length, pattern, email, url, phone, location, file rules (file_size, mime_type, duration), and an llmrule for semantic checks (“must be a plausible company name”). Rules compose with and / or / not.

Complete example

{
  "type": "Workflow",
  "id": "feedback",
  "participants": [
    { "name": "respondent", "bind": "run_initiator",
      "identity": { "anonymous": true }, "surface": "widget" }
  ],
  "children": [
    { "type": "Message", "id": "welcome",
      "content": "Thanks for trying us! Two quick questions." },
    { "type": "Input", "id": "score", "participant_role": "respondent",
      "prompt": "How likely are you to recommend us?",
      "input_type": "Rating", "variant": "nps" },
    { "type": "Conditional", "id": "branch",
      "condition": { "field": "score", "op": "lte", "value": 6 },
      "then": [
        { "type": "Input", "id": "why", "participant_role": "respondent",
          "prompt": "Sorry to hear that — what went wrong?",
          "input_type": "TextArea" }
      ],
      "else": [
        { "type": "Message", "id": "yay", "content": "Glad you like it!" }
      ]
    },
    { "type": "Agent", "id": "summarise",
      "prompt": "Summarise this feedback: score {{score}}, comment {{why}}" }
  ]
}

Deploy this with Public access, and the Quickstart steps put it live on a page.