Use a user activity node to define interactive steps in your agentic workflow where users provide or receive information in one of two ways:
In a multi-turn conversation, where the user provides or receives one piece of data at a time
Through a form, which prompts the user for several pieces of data in a single conversational turn
To add a user activity node to your agentic workflow, start by creating a userflow() object.
Multi-turn conversations
To collect or deliver one piece of data at a time, call field() on the userflow() object. This method accepts the following input parameters:
Parameter
Type
Required
Description
name
string
Yes
Unique identifier for the node.
kind
UserFieldKind
Yes
Type of user activity. Supported types: Text, Date, DateTime, Time, Number, File, Boolean, Object, Choice.
display_name
string
No
Display name for the node.
description
string
No
Description of the node.
direction
string
Yes
Indicates whether the node is for input or output.
default
Any
No
Default value for the node.
text
string
No
Text used to ask a question. For example: “What is your name?“
option
UserFieldOption
No
List of predefined options with it labels and values.
is_list
bool
No
Indicates whether the node accepts multiple values.
min
Any
No
Minimum value or constraint.
max
Any
No
Maximum value or constraint.
input_map
DataMap
No
Define input mappings using a structured collection of Assignment objects.
custom
dictionary
No
Dictionary for additional metadata or configuration.
Here is an example that shows how to use field():
Python
from typing import Listfrom pydantic import BaseModel, Fieldfrom ibm_watsonx_orchestrate.flow_builder.flows import ( Flow, flow, UserNode, START, END)from ibm_watsonx_orchestrate.flow_builder.types import Assignment, UserFieldKindfrom ibm_watsonx_orchestrate.flow_builder.data_map import DataMapclass Name(BaseModel): """ This class represents a person's name. Attributes: name (str): The person's first name. """ first_name: str = Field(default="John Doe", description="First name")@flow( name ="user_flow_example", display_name="user_flow_example", description="Example user flow.", input_schema=Name,)def build_user_flow(aflow: Flow = None) -> Flow: # user_flow which is a subflow to be added to the aflow user_flow = aflow.userflow() # add file upload user_node1 = user_flow.field(direction="input",name="upload", display_name="File upload 1", kind=UserFieldKind.File) # add file download data_map = DataMap() data_map.add(Assignment(target_variable="self.input.value",value_expression="flow[\"userflow_1\"][\"File upload 1\"].output.value")) user_node2 = user_flow.field(direction="output",name="download", display_name="Download file", kind=UserFieldKind.File, input_map=data_map) # add a Display user text field user_node3 = user_flow.field(direction="output",name="display_first_name", display_name="Display first name", kind=UserFieldKind.Text, text="Display of first name is {flow.input.first_name}") # add a text input field user_node4 = user_flow.field(direction="input",name="last_name", display_name="Last name", kind=UserFieldKind.Text, text="Enter last name") # add a Number input field user_node5 = user_flow.field(direction="input",name="age", display_name="Age", kind=UserFieldKind.Number, text="Enter Age") # create a data map to build an array to be assigned to a user field of kind List data_map = DataMap() data_map.add(Assignment(target_variable="self.input.value",value_expression="[\"Alice\", \"Bob\", \"Charlie\", \"Diana\", \"Ethan\", \"Fiona\", \"George\"]")) user_node6 = user_flow.field(direction="output",name="Friends", display_name="List of friends", kind=UserFieldKind.List, input_map=data_map) # A user flow edges user_flow.edge(START, user_node1) user_flow.edge(user_node1, user_node2) user_flow.edge(user_node2, user_node3) user_flow.edge(user_node3, user_node4) user_flow.edge(user_node4, user_node5) user_flow.edge(user_node5, user_node6) user_flow.edge(user_node5, END) # add the user flow to the flow sequence to create the flow edges aflow.sequence(START, user_flow, END) return aflow
Forms (Public Preview)
To prompt for multiple pieces of data in a single turn, instantiate the form() object to create a form node. This method accepts the following input parameters:
Parameter
Type
Required
Description
name
string
Yes
The internal name of the form.
display_name
string
No
The display name shown on the form.
instructions
string
No
Instructions text for the form.
submit_button_label
string
No
The label for the submit button. Defaults to Submit if not set.
cancel_button_label
string
No
The label for the cancel button. If set to None, hides the button.
After instantiating the form object, add fields to it. Each field type requires its own configuration. Supported field types include:
text_input_field
Creates a text input field. Configure it as a single-line input or a multi-line text area.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
required
bool
No
Whether the field is required. Defaults to False.
single_line
bool
No
Whether the field uses a single line. If False, creates a multi-line text area. Defaults to True.
placeholder_text
string
No
Placeholder text for the field.
help_text
string
No
Help text for the field.
default
any
No
Default value for the field, passed as DataMap.
boolean_input_field
Creates a boolean input field. Render it as a checkbox or radio buttons.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
single_checkbox
bool
No
Whether to display as a single checkbox. If False, displays as radio buttons. Defaults to True.
default
any
No
Default value for the field, passed as input_map.
true_label
string
No
Label for the true option. Defaults to True.
false_label
string
No
Label for the false option. Defaults to False.
date_range_input_field
Creates a date range input field with start and end date pickers.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
required
bool
No
Whether the field is required. Defaults to False.
start_date_label
string
No
Label for the start date field.
end_date_label
string
No
Label for the end date field.
default_start
any
No
Default value for the start date, passed as DataMap.
default_end
any
No
Default value for the end date, passed as DataMap.
date_input_field
Creates a date input field.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
required
bool
No
Whether the field is required. Defaults to False.
default
any
No
Default value for the field, passed as DataMap.
number_input_field
Creates a number input field.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
required
bool
No
Whether the field is required. Defaults to False.
is_integer
bool
No
Whether the field accepts only integers. If False, accepts decimal numbers. Defaults to True.
help_text
string
No
Help text for the field.
default
any
No
Default value for the field, passed as DataMap.
minimum
any
No
Minimum allowed value, passed as DataMap.
maximum
any
No
Maximum allowed value, passed as DataMap.
file_upload_field
Creates a file upload field.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
instructions
string
No
Instructions for the file upload.
required
bool
No
Whether the field is required. Defaults to False.
allow_multiple_files
bool
No
Whether multiple files can be uploaded. Defaults to False.
file_max_size
int
No
Maximum file size in MB. Defaults to 10.
message_output_field
Creates a message output field to display static text.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
message
string
No
The message text to display.
field_output_field
Creates a field output to display dynamic values.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
value
any
No
The value to display, passed as DataMap.
list_output_field
Creates a list output field to display tabular data.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
choices
any
No
The list of items to display, passed in a DataMap.
columns
dict[string, str]
No
Mapping of source property names to table column labels. Only those columns appear if present.
file_download_field
Creates a file download field.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
value
any
No
The file to download, passed as DataMap.
single_choice_input_field
Creates a single-choice input field. Display options as a dropdown or as radio buttons.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
required
bool
No
Whether the field is required. Defaults to False.
choices
any
No
The list of available choices, passed as DataMap.
show_as_dropdown
bool
No
Whether to display options as a dropdown. If False, display as radio buttons. Defaults to True.
dropdown_item_column
string
No
Column name used for display text in dropdown.
placeholder_text
string
No
Placeholder text for the dropdown.
default
any
No
Default selected value, passed as DataMap.
columns
dict[string, str]
No
Mapping of source property names to display labels for complex choice objects.
multi_choice_input_field
Creates a multi-choice input field. Display options as a multi-select dropdown or as checkboxes.
Parameter
Type
Required
Description
name
string
Yes
The internal name of the field.
label
string
No
Display label for the field.
required
bool
No
Whether the field is required. Defaults to False.
choices
any
No
The list of available choices, passed as DataMap.
show_as_dropdown
bool
No
Whether to display options as a dropdown. If False, display as checkboxes. Defaults to True.
dropdown_item_column
string
No
Column name used for display text in dropdown.
placeholder_text
string
No
Placeholder text for the dropdown.
Here is an example that shows how to use form():
Python
from typing import Listfrom pydantic import BaseModel, Fieldfrom ibm_watsonx_orchestrate.flow_builder.flows import ( Flow, flow, UserNode, START, END)from ibm_watsonx_orchestrate.flow_builder.types import Assignment, UserFieldKindfrom ibm_watsonx_orchestrate.flow_builder.data_map import DataMapclass Name(BaseModel): """ This class represents a person's name. Attributes: name (str): The person's first name. """ first_name: str = Field(default="John", description="First name") last_name: str = Field(default="Doe", description="Last name")class StringListNames(BaseModel): listOfNames: List[Name] = Field( default=[{"John", "Doe"}, {"Jane", "Doe"}, {"Jean", "Doe"}], description="A list of string values." )class FlowInput(BaseModel): salutations: List[str] = Field( default=["Mr", "Mrs"], description="A list of string salutations." ) listOfLanguages: List[str] = Field( default=["java", "python", "typescript"], description="A list of languages." ) salary_expectation: int = Field( default=200000, description="Expected salary as an integer number." )@flow( name ="user_flow_application_form", display_name="Application form", description="Creates an application form.", input_schema=FlowInput,)def build_user_form(aflow: Flow = None) -> Flow: user_flow = aflow.userflow() user_flow.spec.display_name= "Application" user_node_with_form = user_flow.form(name="ApplicationForm", display_name="Application") data_map = DataMap() data_map.add(Assignment(target_variable="self.input.choices", value_expression="flow.input.salutations")) #Salutatiom user_node_with_form.single_choice_input_field(name="Salutation", label="Salutation", required=True, choices=data_map, show_as_dropdown=True, placeholder_text="Please enter your title") #Boolean married user_node_with_form.boolean_input_field(name="Married", label="Married", single_checkbox = True, true_label="Married", false_label="Not married") #Text fiels "lastName" user_node_with_form.text_input_field(name="LastName", label="Last name", required=True, placeholder_text="Enter your last name", help_text="Enter last name") #Number widget Age" user_node_with_form.number_input_field(name="Age", label="Age", required=True, help_text="Enter your age") data_map_salary = DataMap() data_map_salary.add(Assignment(target_variable="self.input.default", value_expression="flow.input.salary_expectation")) #Number widget salary" user_node_with_form.number_input_field(name="Salary", label="Desired salary", is_integer=False, help_text="Your dream salary is here", default=data_map_salary) data_map_desired_salary = DataMap() data_map_desired_salary.add(Assignment(target_variable="self.input.value", value_expression="flow.input.salary_expectation")) #Field widget salary" user_node_with_form.field_output_field(name="acknowledge", label="Desired salary", value = data_map_desired_salary) data_map_list_source = DataMap() data_map_list_source.add(Assignment(target_variable="self.input.choices", value_expression="flow.input.listOfLanguages")) # #List output widget" user_node_with_form.list_output_field(name="strength", label="Qualification", choices=data_map_list_source) #List output widget" user_node_with_form.message_output_field(name="success", label="Successful submision", message="Application successfully completed.") # A user flow edges user_flow.edge(START, user_node_with_form) user_flow.edge(user_node_with_form, END) # add the user flow to the flow sequence to create the flow edges aflow.sequence(START, user_flow, END) return aflow