> ## 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.

# Example 2: Collect Input

> Add input parameters with automatic validation to your workflow

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:

```json theme={null}
{
  "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:

```json theme={null}
"inputs": [
  {
    "name": "user_name",
    "type": "string",
    "description": "The user's name",
    "required": true
  }
]
```

Each input has:

| Field         | Purpose                                                |
| ------------- | ------------------------------------------------------ |
| `name`        | Parameter name (used in tool schema and variables)     |
| `type`        | JSON Schema type (`string`, `number`, `boolean`, etc.) |
| `description` | Help text shown to the agent                           |
| `required`    | Whether the field must be provided                     |

### Dynamic Tool Schema

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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "current_step_id": "COLLECT_NAME",
  "current_step_inputs": {},
  "completed_steps": [],
  "workflow_completed": false
}
```

**After agent submits:**

```json theme={null}
{
  "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](./example-03-multi-step), you'll learn how to:

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