Adding user activities

A user activity consists of one or more chat-based interactions to collect input and display results within an agentic workflow. It supports mid-flow interaction, allowing users to view and respond to information directly in the chat interface. Examples include approving a request, choosing from a list, answering follow-up questions, or reporting an issue.

To add a user activity to an agentic workflow:

  1. From the menu Menu, go to Build.
  2. Select All tools and click Create tool.
  3. Select Agentic workflow.
  4. Use one of the following actions to add a user activity:
    • Click add tools add new, then click and drag User activity onto a connector line.
    • Hover over a connector line and click add add icon, then select User activity.

For an example video on how to add user activities, see "Building an agentic workflow with user activities in watsonx Orchestrate" in Videos.

Adding interactions

You can use interactions to customize the chat experience.

To add an interaction to your user activity:

  1. Hover over the connector line in the user activity and click add add icon.

  2. In the Interactions tab. Toggle between Collect from users or Display to user.

    • To add an interaction that gets information from a user, select one of the interaction types from Collect from users.
    Type Description
    Boolean choice Collect yes or no response
    Single choice Collect a single choice from the list
    Date Collect a date input
    File upload Collect a file
    Number Collect a numeric input
    Text Collect a text input
    • To add an interaction that displays information to a user, select one of the interaction types from Display to users.
    Type Description
    File download Display as downloadable file
    Message Display as text
    List Display as list

Editing interactions

To edit an interaction in your user activity:

  1. Click the interaction.

  2. Hover over the name and click edit edit.

  3. Enter the new name and click the checkmark check.

  4. For Display to user, you can configure variables to interactions:

    • Configure a Text interaction node, to display text in the chat.

      1. Enter the text to display in the Output message. If you wish to include a value from a variable in your message, Click variable variable, select the variable from the list.

    • Configure a List interaction node, to display list in the chat.

      1. Click the Select source field.
      2. Click the variable variable and choose the variable that provides the list of values to display in the chat. To create a custom list, you can click the expressionExpression and enter a Python expression that produces a list.

    • Configure a File download interaction node, to display a downloadable file in the chat.

      1. Click the Select source field.
      2. Click the variable variable.
      3. Selecct a varibale that provides the provides the file to be downloaded.

Deleting interactions

To delete an interaction in your user activity:

  1. Click the interaction.
  2. Select delete delete.
Note:The title of this node is displayed to the user in the chat.

  • Creating agentic workflows

    An agentic workflow defines a set of linked activities and controls that are designed to achieve a specific business purpose or goal. Learn more about agentic workflows.

Forms in user activities

You can use forms in user activities to collect and display multiple pieces of information within a single turn of the conversation. For example, in an agentic workflow to book a flight, a form can collect travel dates, destinations, class preferences, and other details. The chat can then display a list of available flights based on the user's input.

Adding forms

To add a form to a user activity in an agentic workflow:

  1. In the user activity, hover over a connector line and click the Add icon add icon.

Example showing a user activity with forms
Figure 1: Example showing a user activity with forms.

In the previous example, a user clicks the Add icon add icon to add a form to an existing agentic workflow.

  1. Click Form. A dialog to add a form is displayed.

    By default, in the General settings for the form, the Instructions toggle switch, which is used to add instructions that are displayed in a chat for the user, is set to on. If you prefer not to provide any instructions to the user, set the switch to off.

  2. In the Submission options settings for the form, you can enter a text of your choice to rename the submit and cancel buttons.

    By default, the Cancel button toggle switch, which is used to add a cancel button to the form, is set to on. If you prefer not to provide a cancel button on the form, set the switch to off.

  3. Click Add field or the Add icon add icon to add the fields (user interaction types) to the form.

You can add fields to collect information and display information to the user in a chat. For more information, see Collect information and Display information.

Collect information

To collect information from users in a form, you can add any of the following fields:

Boolean

Boolean options allow a user to specify a boolean option in a chat. You can add boolean fields to a form to pass user-specified data to downstream nodes, which are then used by the agentic workflow. To add a boolean field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.
  2. Select Boolean.
  3. In General > Label, enter the text for this field that is displayed to a user in a chat.
  4. In Appearance > Display as, select how the boolean fields are displayed in a chat either as a single checkbox or as radio buttons.
  5. In the True label and False label options for radio buttons, you can modify the text that is displayed to a user in a chat for the boolean options.
  6. In Behavior, you can specify an initial value for the boolean field by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

If you want to specify an initial value for true or false, close auto-mapping and specify a value.

A boolean field is now added to your form. The following example shows how it is displayed in the chat.

Boolean toggle
Figure 2: Example showing a boolean field in the chat window as a toggle option in a form.


Date

You can add a date field to a form so that a user can provide a date, which can be used by the agentic workflow. Date fields allow users to select a date such as start or end dates for tasks, birthdays, and others in a chat.

To add a date field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select Date.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

    Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.

  4. In Behavior, you can specify an initial value for the date field by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

    If you want to specify a date to use as the initial value, close auto-mapping and select a date.

A date field is now added to your form. The following example shows how it is displayed in the chat.

Date
Figure 3: Example showing a date field in the chat window for selecting a date in a form.


Date range

You can add a date range field to a form so that a user can specify a start date and end date in a chat. The user-specified start date and end date can be used by the agentic workflow. For example, users can specify a start date and end date in a chat, which is essential for agentic workflows that are related to time offs, event scheduling, and others.

To add a date range field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select Date range.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

    Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.

  4. In the Start date label and End date label options, you can modify the text that is displayed to a user in a chat for the start date and end date options.

  5. In Behavior, you can specify an initial value for the start date and end date by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

    If you want to specify a date to use as the initial value, close auto-mapping and select a date.

A date range field is now added to your form. The following example shows how it is displayed in the chat.

Date range
Figure 4: Example showing a date range field in the chat window for selecting a start and end date in a form.

File upload

You can add a file upload field to a form. This field is useful for agentic workflows where users can upload files in a chat such as for document processing, collaboration, generating summaries, and others.

To add a file upload field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select File upload.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

    To allow multiple file uploads, set the Allow multiple files switch to on. To make this field selection mandatory in a chat, set the Required switch to on.

  4. In Appearance > Instructions, you can either enter instructions to help user upload files or click Generate instructions to auto-generate instructions based on the file size and file type selections in Behavior.

    In the Button label option, you can specify a label for the file upload field.

  5. In Behavior, you can specify the supported file types that the user can upload and the maximum file size limit.

A file upload field is now added to your form. The following example shows how it is displayed in the chat.

File upload
Figure 5: Example showing a file upload field in the chat window where users can upload one or more files in a form..

List

You can add a list field to a form when you need to collect a list of information from a user. List items can either be primitive data types, such as strings or dates, or object data types, such as flight details.

To add a list field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select List.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

  4. In the Source variable, you can specify a source for the list by using a variable or expression.

    If you specify a source variable which is a list of objects, then you can choose to display the data as a table. In the Appearance section, you can choose the columns to display to the user by using the Columns list. To edit the selected column labels, click Edit column labels and specify the labels for each item. You can also click Tidy labels to format the labels automatically.

  5. In the Behavior section, you can configure how users can interact with list.

    Set the Allow addition switch to on if you want users to add items to the list. Set the Allow deletion switch to on if you want users to remove items from the list.

Multi choice

You can add a multi-choice field to a form for collecting more than one option from a list in a chat. The user-specified options are then used by the agentic workflow. This field is useful for agentic workflows where users can select multiple options in a chat such as several departments for a report, multiple categories for a task, and others.

To add a multi-choice field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select Multi choice.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

    Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.

  4. In Select the source for your choice list, you can specify a source for the list by using a variable or expression.

    If you specify a source variable as an array object, which defines data, then you can choose to display the data as a drop-down list or as a table. To choose a display type, in Appearance > Display as, select Dropdown or table.

    If you select the Dropdown option, set the display name for each item in the list.

    If you select the Table option, you can choose the columns to display to the user by using the Columns list. To edit the selected column labels, click Edit column labels and specify the labels for each item. You can also click Tidy labels to format the labels automatically.

    In the Placeholder text option, you can also specify the text that is displayed to the user when the drop-down list is empty.

  5. In Behavior, you can specify an initial value for the list by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

    If you want to specify a particular value to use as the initial value, close auto-mapping and enter the value.

A multi choice field is now added to your form. The following example shows how it is displayed in the chat.

Multi choice
Figure 6: Example showing a multi-choice field in the chat window for selecting multiple options in a form.

Number

You can add a number field to a form for collecting numeric input from users in a chat. The numeric input is then used by the agentic workflow. For example, users can specify ticket IDs, item quantity, number of days, and others in a chat.

To add a number field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select Number.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

    Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.

  4. In Input type, specify either the integer or decimal type for the number.

  5. In Appearance, you can add the helper text for the number field. Set the Helper text switch to on to add helper text. Otherwise, set the switch to off.

  6. In Behavior, you can specify an initial value for the number by using a variable, expression, or auto-mapping options. Set the Initial value switch to on to add an initial value. Otherwise, set the switch to off. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

    If you want to specify a particular value to use as the initial value, close auto-mapping and enter the value.

    You can also specify a range for the number field, for example, a user can pick a number between 10 and 20. To add a range, set the Input range switch to on. Otherwise, set the switch to off. You can specify the minimum value and maximum value for a range by using a variable, expression, or auto-mapping options. To specify a particular value to use as the minimum or maximum value, close auto-mapping and enter the value.

A number field is now added to your form. The following example shows how it is displayed in the chat.

Number
Figure 7: Example showing a number field in the chat window for entering numeric input in a form.

Single choice

You can add a single-choice field to a form for collecting an option from a list in a chat. The user-specified option is then used by the agentic workflow. This field is useful for agentic workflows where users can select a single option in a chat such as a department, organization, and others.

To add a single-choice field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select Single choice.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

    Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.

  4. In Select the source for your choice list, you can specify a source for the list by using a variable or expression.

    If you specify a source variable as an array object, which defines data, then you can choose to display the data as a drop-down list or as a table. To display as a drop-down list, select Display as > Dropdown, and optionally specify the name for each list item in Set the display name for each list item. To display as a table, select Display as > Table, and optionally customize the columns to display in the Columns list.

    To edit the selected column labels, click Edit column labels and specify the labels for each item. You can also click Tidy labels to format the labels automatically.

    In the Placeholder text option, you can also specify the text that is displayed to the user when the drop-down list is empty.

  5. In Appearance, you can add a placeholder text that is displayed to a user in a chat when the list is empty.

  6. In Behavior, you can specify an initial value for the list by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

    If you want to specify a particular value to use as the initial value, close auto-mapping and enter the value.

A single choice field is now added to your form. The following example shows how it is displayed in the chat.

Single choice
Figure 8: Example showing a single-choice field in the chat window for selecting one option in a form.


Text

You can add a text field to a form to collect textual data from a user in a chat. The user-specified text is then used by the agentic workflow. For example, users can enter responses for comments or feedback, descriptions of issues or tasks, and others in a chat.

To add a text field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select Text.

  3. In General > Label, enter the text for this field that is displayed to a user in a chat.

    Set the Required switch to on to make this field selection mandatory in a chat. Otherwise, set the switch to off.

    In Input type, you can specify either the Single line or Multi line type for the text.

  4. In Appearance, you can add a placeholder text and helper text for the text field. Set the Placeholder text switch to on to add placeholder text, and set the Helper text switch to on to add helper text. Otherwise, set the switch to off.

  5. In Behavior, you can specify an initial value for the text field by using a variable, expression, or auto-mapping options. The initial value is used as the default value in the chat and helps users to complete a form quickly. Users can either accept or modify this value.

    If you want to specify a particular initial value, close auto-mapping and enter the value.

For more information about mapping data in agentic workflows, see Mapping data.

A text field is now added to your form. The following example shows how it is displayed in the chat.

Text
Figure 9: Example showing a text field in the chat window for entering textual input in a form.

Display information

To display information to the user in a form, you can use any of the following data types:

Field

You can add a field to a form to display data to users in a chat.

To add a field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.
  2. Select Field.
  3. In General > Label, enter the text for the field that is displayed to a user in a chat.
  4. In General > Source, you can specify the source for the data by using a variable or expression.

List

You can add a list to a form to display multiple information in an agentic workflow. For example, you can display priorities, statuses, and other information in a chat in an organized manner to the user.

To add a list to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.

  2. Select List.

  3. In General > Select the source for your choice list, specify a source for the list by using a variable or expression.

    If you specify a source variable as an array object, which defines data, then you can choose to display the data as a table. You can customize the columns to display in the Columns list.

    To edit the selected column labels, click Edit column labels and specify the labels for each item. You can also click Tidy labels to format the labels automatically.

Message

You can add a message to a form to display information in an agentic workflow. For example, you can display the outcome of an agentic workflow in a chat to help users understand the result.

To add a message to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.
  2. Select Message.
  3. In General > Output message, enter the message. You can also use a variable in the message.

File

You can add a file field to a form to allow users to download the file that is generated in an agentic workflow. For example, users can download reports or any other file in a chat.

To add a file download field to a form:

  1. In the form dialog, click Add field or click the Add icon add icon.
  2. Select File download.
  3. In General > Label, enter the text for this field that is displayed to a user in a chat.
  4. In General > Source file, you can specify the source file by using a variable or expression.