Reference

Documentation Index

Fetch the complete documentation index at: https://docs.syllable.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. Workflow Configuration — the shape of a workflow, including activation mode and composing multiple workflows in one agent.
2. Step Configuration — the shape of a single step.
3. Inputs Schema — declaring and reading parameters.
4. Step Transitions — routing between steps.
5. Tool Configuration — controlling tool visibility.
6. Lifecycle Hooks — what fires when.
7. Runtime Lifecycle — how a submission unfolds at runtime, plus the latency and bridge-step rules.
8. Actions Reference — every action and its parameters.
9. Expressions — JMESPath and CEL.
10. Templates — variable substitution in strings.
11. Variables — scopes, naming, and the underlying registry.

​

Workflow Configuration

​

Activation Mode

• call action from another workflow with all step-1 required arguments — the secondary activates, submits step 1 synthetically, and may transition to step 2 in the same turn.
• call action with no arguments, or arguments that don’t cover step 1’s required inputs — the secondary activates and returns step 1’s instructions; the step pointer stays on step 1 and no inputs are recorded. The agent then submits step 1 normally on a later turn.
• Direct LLM submit-tool call — same as the partial-args case above. The agent can “wake” the workflow with a bare submit, and then collect inputs across subsequent turns.

​

Composing Multiple Workflows

{
  "type": "context",
  "context": {
    "task": [
      {
        "type": "steps",
        "id": "triage",
        "start": "auto",
        "tool": { "name": "submit_triage" },
        "steps": [
          {
            "id": "ASK_REASON",
            "inputs": [{ "name": "patient_id", "required": true }],
            "on": {
              "submit": [
                {
                  "action": "call",
                  "name": "submit_patient_lookup",
                  "arguments": { "patient_id": "{{inputs.patient_id}}" }
                }
              ]
            },
            "next": ["SUMMARIZE"]
          }
        ]
      },
      {
        "type": "steps",
        "id": "patient_lookup",
        "start": "manual",
        "tool": { "name": "submit_patient_lookup" },
        "steps": [
          { "id": "LOOKUP", "inputs": [{ "name": "patient_id", "required": true }] }
        ]
      }
    ]
  }
}

• Submit tool names must be unique. Each workflow’s submit tool defaults to submit_inputs if tool.name is not set; collisions across workflows produce duplicate schemas and undefined behavior. Always set tool.name explicitly when you have more than one workflow.
• tools.allow is union-filtered across workflows. Each step’s tools.allow (see Tool Configuration) restricts what the agent sees only when every active workflow’s current step has an allow-list set; if any active workflow’s current step is unrestricted, no filtering applies. The most-permissive workflow wins.

​

Step Configuration

​

id

• Transition routing (next entries)
• Manual navigation (go_to_step)
• Debugging and logging

​

goal

{
  "id": "COLLECT_NAME",
  "goal": "Collect the user's full name for the contact form"
}

​

instructions

{
  "instructions": [
    "Ask the user for their full name. Be polite and professional."
  ]
}

{
  "instructions": [
    "Ask the user for their full name.",
    "If they only provide a first name, ask for their last name as well.",
    "Confirm the spelling if the name is unusual."
  ]
}

{
  "instructions": [
    "Welcome back, {{user_name}}! Let's continue where we left off."
  ]
}

​

Inputs Schema

{
  "inputs": [
    {
      "name": "first_name",
      "type": "string",
      "description": "The user's first name",
      "required": true
    },
    {
      "name": "date_of_birth",
      "type": "string",
      "format": "date",
      "description": "Date of birth (YYYY-MM-DD)",
      "required": true
    },
    {
      "name": "preferred_language",
      "type": "string",
      "enum": ["English", "Spanish", "French"],
      "description": "Preferred language for communication",
      "required": false
    }
  ]
}

​

Available Fields

​

Accumulation Behavior

Turn 1: Agent submits (first_name="Alice")
        → Validation fails: missing date_of_birth
        → inputs.first_name = "Alice" (retained)

Turn 2: Agent submits (date_of_birth="1990-05-15")
        → Validation passes: all required fields present
        → Step advances successfully

• New values overwrite: if the agent provides a new value for an existing input, it replaces the old value.
• Missing values retained: inputs not included in a call keep their previous values.
• Empty string = missing: for string types, "" and whitespace-only strings are treated as empty.
• Cleared on transition: inputs.* is cleared when the workflow transitions to a different step. To keep a value beyond the current step, write it to a global or local.* variable with save or set (see Variables).

​

Referencing inputs in expressions and templates

{"if": "inputs.foo == `true`", "id": "YES"}
{"if": "is_true(inputs.foo)", "id": "YES"}

{
  "on": {"submit": [{"action": "save", "inputs": ["foo"]}]},
  "next": [
    // Same step: either form works, but `inputs.foo` is clearer about where it comes from.
    {"if": "inputs.foo == `true`", "id": "YES"}
  ]
}
// In a *later* step, only the saved global is available:
{"if": "foo == `true`", "id": "YES"}

​

Step Transitions

​

Transition Basics

// Simple unconditional transition
"next": ["NEXT_STEP"]
"next": [{"id": "NEXT_STEP"}]

// Conditional transition
"next": [
  {"if": "inputs.choice == 'A'", "id": "PATH_A"},
  {"if": "inputs.choice == 'B'", "id": "PATH_B"},
  {"id": "DEFAULT_PATH"}  // Fallback (no condition)
]

// Terminal step (workflow ends)
"next": []
// Or simply omit the `next` field

​

Evaluation Order

1. Iterate through next array from first to last.
2. For each entry: if it has an if condition, evaluate it.
3. If condition is true (or no condition), transition to that step.
4. If no entries match, the submission is treated as terminal and the workflow completes in place.

"next": [
  {"if": "score >= `90`", "id": "EXCELLENT"},
  {"if": "score >= `70`", "id": "GOOD"},
  {"id": "NEEDS_IMPROVEMENT"}  // Catches everything else
]

​

Terminal Steps

• It has no next field, OR
• It has "next": [] (empty array).

1. The workflow is marked as completed.
2. The submit tool is removed from the agent’s available tools.
3. The workflow state is preserved for reference.

​

Loop-Back Transitions

{
  "id": "VERIFY_INFO",
  "inputs": [{"name": "provided_dob", "type": "string", "required": true}],
  "on": {
    "submit": [
      {"action": "inc", "name": "local.attempts", "if": "inputs.provided_dob != patient_dob"}
    ]
  },
  "next": [
    {"if": "inputs.provided_dob == patient_dob", "id": "VERIFIED"},
    {"if": "local.attempts >= `3`", "id": "FAILED"},
    {"id": "VERIFY_INFO"}  // Same-step loop: keep inputs, no re-enter
  ]
}

​

Tool Configuration

​

Configuration Options

​

tools.allow

{
  "id": "COLLECT_NAME",
  "tools": {
    "allow": ["submit_contact_form"]  // Only the submit tool
  }
}

{
  "id": "VERIFY_EMAIL",
  "tools": {
    "allow": ["submit_contact_form", "validate_email_domain"]  // Submit + one external tool
  }
}

• Prevent agent from calling irrelevant tools during sensitive steps.
• Progressive disclosure: unlock tools as workflow progresses.
• Security: restrict access to sensitive operations.

• Omitted / null: no restriction — all tools visible.
• [] (empty list): no external tools — only the submit tool is available. This is the standard setting for bridge steps that should auto-advance without any LLM tool decisions.

• Hint path (LLM-guided): tools.allow acts as a guardrail. If the call action’s target tool is not in the allow-list (and is not the submit tool), the pending call is discarded.
• Inject path (synthetic): tools.allow is not enforced — the step author explicitly named the tool in the call action, so intent is clear.

​

tools.call

1. Turn with pending call: the call action takes priority — it forces tool_choice to the target tool. tools.call has no additional effect.
2. Turn without pending call: tools.call: true kicks in — it forces the submit tool (or tool_choice: required if tools.allow is set).

{
  "id": "ROUTE",
  "goal": "Determine next step based on caller data",
  "inputs": [],
  "tools": {"call": true, "allow": []},
  "on": {
    "enter": [
      {"action": "call", "name": "lookup_caller", "arguments": {"ani": "{{vars.session.source}}"}}
    ]
  },
  "next": [
    {"if": "matched_caller", "id": "MATCHED"},
    {"id": "UNMATCHED"}
  ]
}

​

tools.allowGoToStep

{
  "id": "MENU",
  "goal": "Present options to the user",
  "tools": {
    "allowGoToStep": true
  },
  "instructions": [
    "Ask the user what they'd like to do:",
    "1. Check balance → go to CHECK_BALANCE",
    "2. Make payment → go to MAKE_PAYMENT",
    "3. Speak to agent → go to TRANSFER"
  ]
}

{
  "go_to_step": {
    "type": "string",
    "description": "Optional: jump to a specific step ID"
  }
}

• The agent chooses the step by name.
• Invalid step IDs return a validation error.
• Bypasses normal next evaluation when used.
• The current implementation validates the target at submit time; it does not enumerate valid step IDs in the generated schema.
• Use with caution: letting the LLM choose the next step makes the workflow more flexible, but also less predictable.

​

Lifecycle Hooks

{
  "on": {
    "start": [...],
    "enter": [...],
    "presubmit": [...],
    "submit": [...]
  }
}

​

Event Summary

​

on.start

• Initialize workflow-local state.
• Queue first-turn say or call actions.
• Seed values that the first step’s instructions depend on.

{
  "on": {
    "start": [
      {"action": "set", "name": "local.user_language", "value": "English"}
    ]
  }
}

​

on.enter

• Display step-specific greetings or progress indicators.
• Pre-populate inputs from existing data.
• Initialize step-local counters.

{
  "on": {
    "enter": [
      {"action": "say", "text": "Step 2 of 3: Email collection"},
      {"action": "get", "inputs": ["user_email"]}
    ]
  }
}

​

on.presubmit

• Default missing optional fields.
• Transform input values before validation.

{
  "on": {
    "presubmit": [
      {
        "if": "is_false(inputs.middle_name)",
        "action": "set",
        "name": "inputs.middle_name",
        "value": ""
      }
    ]
  }
}

​

on.submit

• Persist inputs to global variables.
• Update counters.
• Confirm submission to user.
• Trigger external tool calls.

{
  "on": {
    "submit": [
      {"action": "save"},
      {"action": "inc", "name": "local.steps_completed"},
      {"action": "say", "text": "Information saved!"}
    ]
  }
}

​

Runtime Lifecycle

​

Timescales

​

Hook Firing Order

​

What Happens in One Submission

• on.submit and the new step’s on.enter both run inside the same submission. That’s a single engine round — the agent sees only the target step’s instructions in the response.
• The engine never “waits” between on.submit and on.enter. If either hook queues a say or call action, those actions accumulate in a single pending queue and are surfaced together in the response.
• A terminal outcome (no branch matches) still returns a response — the last step’s completed status. The agent still needs to generate one final user-facing reply.

​

Why Step Submissions Take Two Agent Turns

• Turn 1 is the tool call itself. The agent decides to submit, the engine processes it, and the engine returns the next step’s instructions. Nothing reaches the user yet.
• Turn 2 is when the agent actually generates the user-facing reply, now informed by the new step’s instructions.

• Two turns is the floor, not the average. Every additional call action or bridge step adds more turns (see the next two subsections).
• The latency floor is roughly two model calls back-to-back. On voice channels, this is audible; on chat it usually isn’t.
• Prefer small, fast models for latency-sensitive workflows. The absolute number of turns doesn’t change with model choice, but each turn is quicker.
• say actions bypass the model-generated reply for that turn — the engine emits their text directly. Use say for short, compliance-critical phrases on voice when you want predictability and lower latency. (note: coming soon)

​

Bridge Steps and the Internal Loop

• Keep bridge-step chains short. If you are stringing together five bridge steps to fetch and massage data, consider consolidating the work into a single custom endpoint.
• A bridge step that’s waiting on a slow external tool is the most common cause of awkward silences on voice calls.
• Prefer one bridge step with one call action over several smaller bridges — fewer turns, less compounding latency.

​

Multiple call Actions Across a Transition

// Step A1 submits, then A2 enters — both have a call action
{
  "id": "A1",
  "on": {
    "submit": [{"action": "call", "name": "Tool_B", "arguments": {...}}]
  },
  "next": [{"id": "A2"}]
}

{
  "id": "A2",
  "on": {
    "enter": [{"action": "call", "name": "Tool_C", "arguments": {...}}]
  }
}

1. A1’s on.submit runs and queues a pending call for Tool B.
2. The workflow transitions to A2.
3. A2’s on.enter runs and queues a pending call for Tool C.
4. The engine drains the queue and surfaces only Tool B in the response — it is the first call queued.
5. Tool C stays in the queue. It will only surface after the next submission.

• Don’t stack call actions across a transition boundary. Pick one: either A1’s on.submit or A2’s on.enter, not both.
• If you really need two external calls as part of one step change, route them through a single endpoint that fans out server-side, or add a dedicated bridge step between A1 and A2 with just the second call.
• If a step’s tools.allow list is non-empty, make sure every call action that could arrive at this step names one of the allowed tools — otherwise the engine will discard it.

​

Real-Time Voice Considerations

• Every extra turn is audible. On chat, the two-turn minimum feels instant. On voice, it’s a noticeable pause. Bridge-step chains are the most common source of awkward silences.
• Prefer say over asking the agent to repeat fixed phrases. say text is emitted without an extra model turn, so it is both faster and more deterministic than “please say X”.
• Avoid on.enter.call for slow tools on steps the workflow enters mid-conversation. Every enter-side call adds at least one turn before the agent can speak.
• Keep on.submit.call arguments complete. When all required parameters are supplied, the engine can inject the call without a second model turn. Leaving required parameters missing forces a hint-based path that costs an additional turn.

​

Actions Reference

​

Action Summary

​

say

{"action": "say", "text": "Welcome! Step 1 of 3."}
{"action": "say", "text": "Please hold while I check...", "role": "assistant"}

​

set

{"action": "set", "name": "local.counter", "value": 0}
{"action": "set", "name": "user_status", "valueFrom": "inputs.status"}
{"action": "set", "name": "full_name", "valueFrom": {"type": "cel", "expression": "first + ' ' + last"}}
{"action": "set", "name": "combined", "valueFrom": {"type": "jmespath", "expression": "{name: user_name, email: user_email}"}}

​

inc

{"action": "inc", "name": "local.attempt_count"}
{"action": "inc", "name": "local.score", "by": 10}
{"action": "inc", "name": "local.retries", "if": "!inputs.is_valid"}

​

get

// Copy from variables of the same name (default mode)
{"action": "get", "inputs": ["user_email", "user_phone"]}

// Always overwrite, even if the agent already supplied a value
{"action": "get", "inputs": ["user_name"], "overwrite": true}

// Set a static value for one or more inputs
{"action": "get", "inputs": ["status"], "value": "pending"}

// Set inputs from a computed expression
{"action": "get", "inputs": ["full_name"], "valueFrom": "first_name"}

• If neither value nor valueFrom is set, the action copies each input from a global variable of the same name (e.g. inputs.user_email ← user_email).
• If value or valueFrom is set, every named input receives that same resolved value.

​

save

{"action": "save"}
{"action": "save", "inputs": ["user_name", "user_email"]}
{"action": "save", "name": "contact", "inputs": ["user_name", "user_email"]}

• No name → writes key X (for example, user_email).
• With name: "contact" → writes key contact.X (for example, contact.user_email).

1. Delete the existing contact = "Alice".
2. Write contact.user_email = "<the input value>".

// Overwrites vars.facility_email with the collected input value
{"action": "set", "name": "vars.facility_email", "valueFrom": "inputs.obtained_email"}

​

call

{"action": "call", "name": "get_current_datetime"}
{"action": "call", "name": "lookup_patient", "arguments": {"patient_id": "{{inputs.patient_id}}"}}

​

Auto-decide routing

​

Common patterns

{
  "on": {
    "enter": [
      {"action": "call", "name": "lookup_patient", "arguments": {"patient_id": "{{patient_id}}"}}
    ]
  }
}

{
  "instructions": ["Call mock_patient_lookup with patient_id 'patient-456'."],
  "on": {
    "enter": [
      {"action": "call", "name": "mock_patient_lookup", "arguments": {}}
    ]
  }
}

{
  "id": "CHECK_TIME",
  "goal": "Record the current date and time, then auto-advance",
  "tools": {"call": true, "allow": []},
  "on": {
    "enter": [
      {"action": "call", "name": "get_current_datetime", "arguments": {}}
    ]
  },
  "next": [{"id": "NEXT_STEP"}]
}

​

Tool results

• have the endpoint persist known values into vars.*, or
• have the agent resubmit normalized result fields through the submit tool.

​

Conditional Actions

{
  "action": "say",
  "text": "That doesn't match our records. Please try again.",
  "if": "inputs.provided_dob != patient_dob"
}

{
  "action": "inc",
  "name": "local.retry_count",
  "if": "!inputs.is_valid && local.retry_count < 3"
}

​

Expressions

​

JMESPath (Default)

// Boolean check (truthy/falsy)
"if": "is_valid"
"if": "inputs.confirmed"

// String comparison
"if": "status == 'active'"
"if": "inputs.contact_time == 'morning'"

// Boolean literal comparison (note backticks!)
"if": "inputs.can_sign == `true`"
"if": "inputs.opted_out == `false`"

// Numeric comparison
"if": "local.attempt_count >= `3`"
"if": "inputs.age < `18`"

// Logical operators
"if": "is_valid && has_consent"
"if": "status == 'morning' || status == 'afternoon'"
"if": "!inputs.opted_out"

// Nested property access
"if": "inputs.address.city == 'Boston'"

// Null/missing check
"if": "inputs.middle_name"       // truthy check
"if": "!inputs.optional_field"   // missing or empty

​

CEL (Common Expression Language)

{
  "valueFrom": {
    "type": "cel",
    "expression": "counter + 1"
  }
}

{
  "if": {
    "type": "cel",
    "expression": "age >= 18 ? 'adult' : 'minor'"
  }
}

// Arithmetic
"expression": "price * 0.9"
"expression": "local.attempts + 1"

// String concatenation
"expression": "first_name + ' ' + last_name"

// Ternary operator
"expression": "is_vip ? 'priority' : 'standard'"

// Boolean logic
"expression": "is_valid && has_consent"

​

When to Use Which

​

Templates

​

Supported Syntax

​

Where Templates Are Expanded

​

Available Variables

​

Examples

{
  "instructions": [
    "Confirm with {{inputs.user_name}} that their email is {{user_email}}."
  ]
}

{
  "action": "say",
  "text": "Hello {{inputs.user_name}}! You have {{local.remaining_attempts}} attempts remaining."
}

{
  "action": "call",
  "name": "lookup_patient",
  "arguments": {
    "patient_id": "{{patient_id}}",
    "dob": "{{inputs.provided_dob}}"
  }
}

​

Variables

​

Variable Scopes

​

Global Variables

{"action": "save"}  // Saves inputs to global scope
{"action": "set", "name": "user_name", "valueFrom": "inputs.name"}

• Data needed after the workflow completes.
• Sharing data between concurrent workflows.
• Final outputs that other systems will use.

​

Task-Local Variables

{"action": "set", "name": "local.counter", "value": 0}
{"action": "inc", "name": "local.retry_attempts"}

• Retry counters within the workflow.
• Flags and intermediate state.
• Data that shouldn’t persist after workflow completion.

​

Step Inputs

• Cleared when transitioning to a different step.
• Accumulated across multiple submissions of the current step.
• Read-only in expressions; use set to modify.

​

Hierarchy Conflict Handling

• customer (scalar) and customer.id (nested)
• contact.email and later contact (scalar)
• foo, foo.bar, and foo.bar.baz mixed in one workflow

​

1) Write-time conflict cleanup (when set/save writes)

• Writing a nested key (e.g., customer.id) removes conflicting scalar parents (customer).
• Writing a parent key (e.g., customer) removes conflicting children (customer.*).
• Siblings (e.g., customer.id, customer.email) can coexist.

​

2) Read-time context expansion (templates/expressions)

• If a scalar leaf already exists at a parent path, deeper keys under that path are skipped.
• If a plain key appears where a nested object already exists, the plain key overwrites that nested object.

​

vars.* Prefix and Platform Variables

• Session context: vars.session.id, vars.session.language, vars.session.source
• Campaign variables: per-call values provided to outbound campaigns (for example vars.customer_name, vars.appointment_time)
• Agent configuration: values defined once on the agent and exposed to every session

{"action": "set", "name": "vars.facility_email", "valueFrom": "inputs.obtained_email"}

​

Pitfall: Mixing Scalars and Nested Keys for the Same Root

• vars.facility_email = "alice@example.com" (campaign value, scalar)
• facility_email.obtained_email = "alice@example.com" (workflow-written, nested under a different root)

​

When to Use Which Scope

​

Practical Naming Guidance

1. Prefer flat snake_case names for global outputs (customer_id, customer_email, preferred_contact_time).
2. Use local.* for per-workflow state (local.retry_count, local.current_phase).
3. If you intentionally use nested global keys (for readability), use a consistent object hierarchy such as customer.id, customer.email.
4. Do not mix scalar and nested forms for the same root key (customer and customer.id) unless replacement is intentional.
5. Avoid custom keys under vars.*; reserve that namespace for platform-managed/session context.