Example 2: Collect Input

Building on the Hello World example, this workflow collects and validates user information.

Objective

In this example, you'll learn:

• How to define input parameters for a step
• How the submit tool schema adapts to include inputs
• How validation works for required fields
• How to access collected inputs

The Scenario

You want to collect the user's name before proceeding. The workflow should:

1. Ask for the user's name
2. Validate that a name was provided
3. Complete once the name is collected

This pattern forms the basis for all data collection in Step Workflows.

Implementation

Here's the complete tool definition:

{
  "type": "context",
  "context": {
    "task": {
      "type": "steps",
      "version": "v1alpha",
      "id": "collect-input",
      "tool": {
        "name": "submit_user_info",
        "description": "Submit user information"
      },
      "steps": [
        {
          "id": "COLLECT_NAME",
          "goal": "Collect the user's name",
          "instructions": [
            "Ask the user for their name.",
            "Once you have their name, call the submit_user_info tool with the user_name parameter."
          ],
          "inputs": [
            {
              "name": "user_name",
              "type": "string",
              "description": "The user's name",
              "required": true
            }
          ]
        }
      ]
    }
  },
  "tool": {
    "type": "function",
    "function": {
      "name": "collect_name_workflow",
      "description": "Collecting one required input with validation",
      "parameters": {
        "type": "object",
        "properties": {},
        "required": []
      }
    }
  }
}

Key Concepts

Input Parameters

The inputs array defines what data the agent should collect:

"inputs": [
  {
    "name": "user_name",
    "type": "string",
    "description": "The user's name",
    "required": true
  }
]

Each input has:

Dynamic Tool Schema

When inputs are defined, the submit tool's schema automatically includes them:

{
  "name": "submit_user_info",
  "description": "Collect the user's name",
  "parameters": {
    "type": "object",
    "properties": {
      "user_name": {
        "type": "string",
        "description": "The user's name"
      }
    },
    "required": ["user_name"]
  }
}

The agent sees this schema and knows exactly what to collect.

Automatic Validation

When the agent calls the submit tool:

1. Check required fields: All required: true inputs must be present
2. Type validation: Values must match their declared types
3. Retry on failure: If validation fails, the step remains active

If the agent tries to submit without providing user_name, the workflow rejects the submission and the agent must try again.

Accessing Inputs

After the agent submits valid data, the collected inputs are available at inputs.*:

• inputs.user_name — The value the agent provided

These are accessible in:

• Step instructions (via templates): "Welcome, {{inputs.user_name}}!"
• Conditions: "if": "inputs.user_name == 'Admin'"
• Actions: {"action": "set", "name": "name", "valueFrom": "inputs.user_name"}

How It Works

Here's the conversation flow:

User: "Hello"

[Platform initializes workflow]
  → Current step: COLLECT_NAME
  → Agent receives instructions to ask for name
  → Submit tool schema includes user_name parameter

Agent: "What is your name?"

User: "My name is Alice"

[Agent calls submit_user_info(user_name="Alice")]
  → Validation passes: user_name is present
  → No next step (terminal)
  → Workflow completes

Agent: "Thank you, Alice! How can I assist you today?"

State Changes

After initialization:

{
  "current_step_id": "COLLECT_NAME",
  "current_step_inputs": {},
  "completed_steps": [],
  "workflow_completed": false
}

After agent submits:

{
  "current_step_id": "COLLECT_NAME",
  "current_step_inputs": {
    "user_name": "Alice"
  },
  "completed_steps": ["COLLECT_NAME"],
  "workflow_completed": true
}

What Happens Without a Name?

If the agent calls submit_user_info({}) without providing user_name:

1. Validation fails (required field missing)
2. The workflow returns an error response
3. The step remains active
4. The agent should ask the user again

The workflow enforces data collection—the agent can't skip required inputs.

Try It

To test this workflow in the Syllable Console:

1. Create a new tool with the JSON above
2. Assign it to an agent
3. Start a conversation and say "hello"
4. Observe the agent asking for your name
5. Provide your name and watch the workflow complete

Test validation: Try saying something that doesn't include a name and see how the agent responds.

What's Next

This example collected a single input. In Example 3: Multi-Step Flow, you'll learn how to:

• Chain multiple steps together with transitions
• Persist data across steps using variables
• Build a complete contact form workflow