User activity node

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 List
from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import (
    Flow, flow, UserNode, START, END
)
from ibm_watsonx_orchestrate.flow_builder.types import Assignment, UserFieldKind
from ibm_watsonx_orchestrate.flow_builder.data_map import DataMap

class 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 List
from pydantic import BaseModel, Field
from ibm_watsonx_orchestrate.flow_builder.flows import (
    Flow, flow, UserNode, START, END
)
from ibm_watsonx_orchestrate.flow_builder.types import Assignment, UserFieldKind
from ibm_watsonx_orchestrate.flow_builder.data_map import DataMap

class 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

Release Notes

Get Started

Build

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate ADK MCP Server

Reference

Legal notices

Multi-turn conversations

Forms (Public Preview)

​Multi-turn conversations

​Forms (Public Preview)

Multi-turn conversations

Forms (Public Preview)