Reference - Syllable SDK

This reference documents all configuration options for Step Workflows. For an introduction to what Step Workflows are and when to use them, see the Overview.

Step Configuration

Each step in a workflow is defined with the following properties:

Property	Purpose	Example
`id`	Unique step identifier	`"COLLECT_NAME"`
`goal`	Brief description (shown to the agent)	`"Collect the user's name"`
`instructions`	Agent guidance (string or array)	`"Ask for the user's full name."`
`inputs`	Parameters to collect (JSON Schema)	`[{name: "user_name", type: "string"}]`
`on`	Lifecycle hooks for actions	`{enter: [...], submit: [...]}`
`next`	Transition routing	`["NEXT_STEP"]` or `[{if: "...", id: "..."}]`
`tools`	Tool visibility control	`{allow: [...], call: true}`

id

A unique string identifier for the step. Used in:

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

Best practice: Use SCREAMING_SNAKE_CASE for step IDs (e.g., COLLECT_EMAIL, VERIFY_DOB).

goal

A brief description of what this step accomplishes. This text becomes the submit tool’s description, helping the agent understand the purpose of the current step.

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

instructions

Guidance for the agent on how to execute this step. Can be a string or array of strings:

{
  "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 support template substitution for dynamic content:

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

inputs

Defines the parameters the agent should collect before advancing. See Inputs Schema for full details.

{
  "inputs": [
    {"name": "first_name", "type": "string", "required": true},
    {"name": "email", "type": "string", "format": "email", "required": true},
    {"name": "phone", "type": "string", "required": false}
  ]
}

Controls workflow routing after successful submission. See Step Transitions for full details.

{
  "next": ["CONFIRM"]
}

{
  "next": [
    {"if": "inputs.contact_preference == 'phone'", "id": "SCHEDULE_CALL"},
    {"if": "inputs.contact_preference == 'email'", "id": "SCHEDULE_EMAIL"},
    {"id": "DEFAULT_FOLLOWUP"}
  ]
}

tools

Controls which tools the agent can access during this step. See Tool Configuration for full details.

{
  "tools": {
    "allow": ["submit_contact_form", "validate_email"],
    "call": true
  }
}

Lifecycle Hooks

Lifecycle hooks execute actions at specific points during step execution. Define them in the on property:

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

Event Summary

Event	When Triggered	Allowed Actions	Primary Use Cases
`on.enter`	Entering a step (before input collection)	`get`, `set`, `inc`, `say`, `call`	Step welcome messages, pre-populate inputs
`on.presubmit`	After agent submits, before validation	`get`, `set`, `inc`, `save`	Default missing values, data transformation
`on.submit`	After validation passes	`set`, `inc`, `say`, `save`, `call`	Persist data, trigger side effects

on.enter

Executes when the workflow enters this step, before the agent begins input collection. Common uses:

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

Executes after the agent calls the submit tool, but before input validation runs. Restriction: No say or call actions (data mutation only). This prevents confusing UX where the agent says “Saved!” but validation then fails. Common uses:

Default missing optional fields
Transform input values before validation

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

on.submit

Executes after validation passes, before evaluating transitions. Common uses:

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!"}
    ]
  }
}

Actions Reference

Actions are the operations executed during lifecycle events. All actions support an optional if condition.

Action Summary

Action	Description	Key Parameters	Available In
`say`	Queue a verbatim message	`text`, `role`	`on.enter`, `on.submit`
`set`	Set a variable value	`name`, `value` or `value_from`	all events
`inc`	Increment a counter	`name`, `by`	all events
`get`	Pre-populate inputs from variables	`inputs`, `overwrite`	`on.enter`, `on.presubmit`
`save`	Persist inputs to global variables	`name`, `inputs`	`on.presubmit`, `on.submit`
`call`	Queue a tool call	`name`, `arguments`	`on.enter`, `on.submit`

say

Queues text that the agent must include verbatim in its response.

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

Parameter	Type	Default	Description
`text`	string	required	Verbatim text to include
`role`	string	`"assistant"`	Message role
`if`	string	-	Optional condition

Note: Agent compliance with say text is approximately 95%. The agent may occasionally add minor variations.

set

Sets a variable to a static value or computed expression.

{"action": "set", "name": "local.counter", "value": 0}
{"action": "set", "name": "user_status", "value_from": "inputs.status"}
{"action": "set", "name": "full_name", "value_from": {"type": "cel", "expression": "first + ' ' + last"}}

Parameter	Type	Description
`name`	string	Target variable path (e.g., `local.x`, `user_name`)
`value`	any	Static value to set
`value_from`	Expression	Dynamic value from expression (mutually exclusive with `value`)
`if`	string	Optional condition

inc

Increments a numeric variable. Creates the variable with value 0 if it doesn’t exist.

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

Parameter	Type	Default	Description
`name`	string	required	Variable to increment
`by`	number	1	Amount to increment by
`if`	string	-	Optional condition

get

Copies values from existing variables into step inputs. Useful for pre-filling forms with known data.

{"action": "get", "inputs": ["user_email", "user_phone"]}
{"action": "get", "inputs": ["user_name"], "overwrite": true}

Parameter	Type	Default	Description
`inputs`	list[string]	all inputs	Which inputs to populate
`overwrite`	boolean	false	If true, overwrite existing input values
`if`	string	-	Optional condition

save

Saves step inputs to global variables for use in later steps or after workflow completion.

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

Parameter	Type	Default	Description
`inputs`	list[string]	all inputs	Which inputs to save
`name`	string	input name	Target variable name (for single input)
`if`	string	-	Optional condition

Without parameters: Saves all step inputs to global variables with matching names.

call

Queues a tool call to be executed. The call is injected into the conversation.

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

Parameter	Type	Description
`name`	string	Tool name to call
`arguments`	object	Template-rendered arguments
`if`	string	Optional condition

Note: The call action queues the tool call; it doesn’t execute immediately. The call is processed in the next middleware pass.

Conditional Actions

All actions support an optional if field for conditional execution:

{
  "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"
}

The if condition is evaluated as a JMESPath expression by default. See Expressions for syntax details.

Expressions

Expressions are used in conditions (if fields), computed values (value_from), and step transitions (next[].if).

JMESPath (Default)

JMESPath is the default expression language. When you write a string condition, it’s evaluated as JMESPath. Common Patterns:

// 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

Gotchas:

Issue	Wrong	Correct
Boolean literals need backticks	`flag == true`	`flag == \`true“
Number literals need backticks	`count > 3`	`count >= \`3“
String quotes	`name == morning`	`name == 'morning'`

CEL (Common Expression Language)

CEL is useful when you need features JMESPath doesn’t support: arithmetic, string concatenation, or ternary operators. Syntax:

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

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

CEL Capabilities:

// 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"

CEL Limitation: CEL doesn’t support nested dict access (inputs.address.city). Use JMESPath for nested structures.

When to Use Which

Use Case	Recommended	Why
Simple condition checks	JMESPath	Default, no syntax overhead
String comparisons	JMESPath	Cleaner syntax
Nested property access	JMESPath	CEL doesn’t support it
Arithmetic	CEL	JMESPath can’t compute
String building	CEL	JMESPath can’t concatenate
Ternary logic	CEL	Clean conditional values

Inputs Schema

Each step can define inputs—parameters that the agent should collect before advancing.

Input Parameters

The inputs array defines parameters that become the submit tool’s function 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

Field	Type	Required	Description
`name`	string	Yes	Parameter name
`type`	string	No	JSON Schema type: `string`, `number`, `integer`, `boolean`, `object`, `array`. Defaults to `string`
`description`	string	No	Human-readable description shown to agent
`required`	boolean	No	Whether parameter must be collected. Defaults to `true`
`enum`	list[str]	No	Allowed values (agent constrained to these options)
`format`	string	No	Format hint: `date`, `time`, `date-time`, `email`, `uri`, etc.
`pattern`	string	No	Regex pattern for validation

Accumulation Behavior

Inputs accumulate across multiple submissions until all required fields are collected:

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

Key behaviors:

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

Reset on Transition

Important: Input variables (inputs.*) are cleared when transitioning to a new step. To preserve values across steps, use the save or set actions:

{
  "on": {
    "submit": [
      {"action": "save", "inputs": ["first_name", "email"]}
    ]
  }
}

Templates

Template substitution lets you inject dynamic values into text fields using variable placeholders.

Supported Syntax

Syntax	Behavior	Example
`{{var}}`	Replace with value, or empty string if missing	`{{user_name}}` → `"Alice"` or `""`
`${var}`	Replace with value, or empty string if missing	`${user_name}` → `"Alice"` or `""`
`${var=default}`	Replace with value, or default if missing	`${name=Guest}` → `"Alice"` or `"Guest"`

Recommendation: Use {{var}} (handlebars style) for most cases.

Where Templates Are Expanded

Field	Template Expansion	Notes
`instructions[]`	Yes	Step instructions are rendered with current context
`say` action `text`	Yes	Message text is rendered before queuing
`set` action `value`	Yes (if string)	Static string values are rendered
`call` action `arguments`	Yes (recursive)	All string values in arguments are rendered
`goal`	No	Used as-is
`if` conditions	No	Use expression evaluation instead
`value_from`	No	Use expression evaluation (JMESPath/CEL)

Available Variables

Scope	Access Pattern	Example
Global variables	`{{variable_name}}`	`{{user_name}}`
Task-local state	`{{local.key}}`	`{{local.retry_count}}`
Step inputs	`{{inputs.field}}`	`{{inputs.provided_dob}}`
Nested values	`{{scope.path.to.value}}`	`{{inputs.address.city}}`

Examples

In instructions:

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

In say action:

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

In call action:

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

Step Transitions

The next field controls workflow routing after a step is successfully submitted.

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

Transitions are evaluated in order. The first matching entry wins:

Iterate through next array from first to last
For each entry: if it has an if condition, evaluate it
If condition is true (or no condition), transition to that step
If no entries match, the workflow cannot proceed (error state)

Best Practice: Always include a fallback entry without if as the last item:

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

Terminal Steps

A step is terminal if:

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

When a terminal step is submitted:

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

Loop-Back Transitions

Steps can transition back to themselves or earlier steps for retry patterns:

{
  "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"}  // Loop back for retry
  ]
}

Tool Configuration

The tools field on a step controls which tools the agent can access and whether to force specific tool behavior.

Configuration Options

Field	Type	Default	Description
`tools.allow`	list[string]	null (all)	Whitelist of allowed tool names
`tools.call`	boolean	false	Force immediate tool call
`tools.allow_go_to_step`	boolean	false	Expose manual step navigation

tools.allow

Restricts which tools the agent can see during this step. The submit tool is always available regardless of this setting.

{
  "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
  }
}

Use cases:

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

tools.call

When true, forces the agent to make a tool call before responding to the user. Typically used with on.enter call actions.

{
  "id": "FETCH_DATA",
  "tools": {"call": true},
  "on": {
    "enter": [
      {"action": "call", "name": "get_patient_info", "arguments": {"id": "{{patient_id}}"}}
    ]
  }
}

Behavior:

Sets tool_choice: required in the agent request
Combined with queued call actions, ensures specific tools are called
Useful for fetching data before proceeding

tools.allow_go_to_step

When true, adds a go_to_step parameter to the submit tool schema, allowing the agent to manually jump to a specific step.

{
  "id": "MENU",
  "goal": "Present options to the user",
  "tools": {
    "allow_go_to_step": 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"
  ]
}

Generated schema includes:

{
  "go_to_step": {
    "type": "string",
    "description": "Step ID to transition to",
    "enum": ["CHECK_BALANCE", "MAKE_PAYMENT", "TRANSFER", ...]
  }
}

Notes:

The agent chooses the step by name
Invalid step IDs return a validation error
Bypasses normal next evaluation when used

Variables

Step Workflows use multiple variable scopes for different purposes.

Variable Scopes

Scope	Prefix	Lifetime	Use Case
Global	(none) or `vars.*`	Conversation	Shared data, final outputs
Task-local	`local.*`	Workflow	Counters, flags, intermediate state
Step inputs	`inputs.*`	Current step	Collected input parameters

Global Variables

Global variables persist for the entire conversation and are accessible to all tools and workflows.

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

Use global variables for:

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

Task-Local Variables

Task-local variables (local.*) are scoped to a single workflow instance.

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

Use task-local variables for:

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

Step Inputs

Step inputs (inputs.*) contain the current step’s collected parameters. Key behaviors:

Cleared when transitioning to the next step
Accumulated across multiple submissions
Read-only in expressions; use set to modify

Context	Available Inputs
`on.enter`	Empty (step just started)
`on.presubmit`	Values from current submit call
`on.submit`	Validated values (all required present)
`if` conditions	Current accumulated values
Templates	Current accumulated values

When to Use Which Scope

Scenario	Scope	Why
Data needed after workflow completes	Global	Persists beyond workflow
Retry counter within workflow	`local.*`	Workflow-specific state
Sharing between concurrent workflows	Global	Task-local is isolated
Sensitive intermediate data	`local.*`	More contained scope

Introduction to Syllable

Tutorials

Account

Workspaces

Resources

​Step Configuration

​id

​goal

​instructions

​inputs

​next

​tools

​Lifecycle Hooks

​Event Summary

​on.enter

​on.presubmit

​on.submit

​Actions Reference

​Action Summary

​say

​set

​inc

​get

​save

​call

​Conditional Actions

​Expressions

​JMESPath (Default)

​CEL (Common Expression Language)

​When to Use Which

​Inputs Schema

​Input Parameters

​Available Fields

​Accumulation Behavior

​Reset on Transition

​Templates

​Supported Syntax

​Where Templates Are Expanded

​Available Variables

​Examples

​Step Transitions

​Transition Basics

​Evaluation Order

​Terminal Steps

​Loop-Back Transitions

​Tool Configuration

​Configuration Options

​tools.allow

​tools.call

​tools.allow_go_to_step

​Variables

​Variable Scopes

​Global Variables

​Task-Local Variables

​Step Inputs

​When to Use Which Scope