Creating agentic workflows

Edit agentic workflow details

To edit agentic workflow details:

1. From the menu , navigate to Build.

2. Navigate to All tools.

   On IBM Cloud environment, select the workspace associated with the workflow from the workspace list.

3. Select the workflow, and click the Options icon , and select Edit details.

4. In the Overview tab, update the name and enter a description for the tool.

5. Click the Parameters tab to configure inputs and outputs for the tool.

6. Click Add inputs to define the input. For detailed instruction, see Adding inputs

7. Click Add outputs to define the output. For the detailed instruction, see Adding outputs

8. Click Done.

Add paths

To add a path to a branch:

1. Click the branch.

2. In the branch window, select Add path.

Add path conditions

To add a condition to a path:

1. Click the branch.

2. Find the path and select Edit condition. Choose one of the following options to define a condition:

   • To build a condition by using Condition builder:

     1. In the Condition builder window, click and select a variable from the Available variables drop-down list.

     2. Click and select an Operator from the drop-down list.

     3. Click and Enter a Value.

     4. Press enter. To add more than one condition, select Add condition.

   • To build a condition by using Expression editor:

     1. Select Expression editor .

     2. Click Enter expression and enter the Python expression.

3. Click back.

Edit or delete a condition

To edit the conditions of a path:

1. Click the branch.

2. Find the path and select Edit condition. Choose one of the following options to edit a condition:

   • To edit a condition by using Condition builder:

     1. Update the variable, operator, and value.

     2. Click enter.

   • To edit a condition by using Expression editor:

     1. Select expression editor .

     2. Click the expression to open the editor window and update the Python expression.

To delete the condition of a path:

1. Click the branch.

2. Find the path and select Edit condition.

3. Click delete condition .

Edit paths

You can manage the paths in your branch by changing the order, renaming a path, or deleting a path.

To change the order of the paths:

1. Click the branch.

2. Click more actions .

3. Select Move up or Move down from the list to change the order.

You can also reorder the paths by clicking and dragging the icon next to the path.

To edit a path:

1. Click the branch.

2. Click more actions .

3. Select Edit path name and enter the new name.

To delete a path:

1. Click the branch.

2. Click more actions .

3. Select Delete.

Select list

To select a list for the For each control:

1. Click the For each control.

2. Use one of the following options to select a list:

   • By default, auto-map is enabled, which select a list object form the agentic workflow input.

However, you can change this default behavior and configure list object by choosing variable or expression options.

• To configure list object by using a variable, Select and choose a variable from the Available variables list.

• To configure list object by using an expression, Select and click Enter expression under Select a list field to open the editor window and update the Python expression.

Once the list object is selected, the iterator and index variables are automatically provided.

Add local variables

Local variables are used only within a For each control and are not accessible outside of it. Each iteration of the For each can store intermediate results specific to that iteration. These values are stored within them and cannot be shared between different iterations.

To add local variables to the For each control:

1. Click the For each control.

2. Click in the Local variables section.

3. Select Add in the Local variables window.

4. Choose the variable type from the drop-down list.

5. Enter the Name and Description.

6. Select the List of {object type} checkbox if you want to store a list of values in the variable.

7. Click Add.

To add more than one local variables, click Add.

Edit or delete local variable

To edit a local variable:

1. Click the For each control.

2. Click in the Local variables section.

3. Hover over the variable and select .

4. Update the name and description in the Update output window.

5. Click Save.

To delete a local variable:

1. Click the For each control.

2. Click in the Local variables section.

3. Hover over the variable and select .

User activities

You can use user activity to create chat-based interaction to collect input and display the result within an agentic workflow. For more information, see Adding user activities.

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

Logic blocks

You can use logic block to add custom Python logic directly within an agentic workflow. For more information, see Adding logic blocks.

Generative prompts

You can use a generative prompt when you need help with tasks that involve natural language understanding. It works by using a large language model (LLM) to generate text or structured content. For generative prompts in agentic workflows, you can add new models through the AI Gateway. For more information, see Adding generative prompts.

For an example video on how to add generative prompts, see Building an agentic workflow with generative prompts in watsonx Orchestrate in Videos.

Document classifiers

You can add document classifiers to agentic workflows to automatically identify document types. For more information, see Adding document classifiers.

Document extractors

You can add document extractors to agentic workflows to extract fields or entities such as date, names, and others from documents. For more information, see Adding document extractors.

Text extractors

You can use a text extractor in an agentic workflow to extract text from a document. For more information, see Adding text extractors.

Adding inputs

To add agentic workflow inputs:

1. Click start node.

2. In the Inputs window, click Add.

3. Select an input type from the list.

4. Enter a Name and Description.

5. Optional: Select the List of {data type} checkbox to store a list of values in the input.

6. Optional: Turn on the Set default values toggle switch to set the input with a default value.

7. Enter a value and click in the default value field.

8. Click Add.

   • If you select the List of {data type} checkbox, you can add more than one default value in the List of default values field.

   • The List of {data type} checkbox is not available for file inputs, and the Set default value option is not available for file and object inputs.

   • For object data type, you can choose between Simple view and JSON view to view the object properties.

Adding outputs

To add agentic workflow outputs:

1. Click the end node.

2. In the Outputs window, click Add.

3. Select the output type from the list.

4. Optional: Select the List of {data type} checkbox to generate a list of values as output.

5. Click Add.

   • The List of {data type} checkbox is not available for file inputs.

   • For object data type, you can choose between Simple view and JSON view to view the object properties.

Adding flow variables

To add flow variables:

1. Click icon on the left side of the agentic workflow window.

2. Click Add and select the variable type from the list.

3. Enter a Name and Description.

4. Optional: Select the List of {data type} checkbox to store a list of values in the variable.

5. Optional: Turn on the Set default values toggle switch to set the variable with a default value.

6. Enter a value and click in the default value field.

7. Click Add.

   • If you select the List of {data type} checkbox, you can add more than one default value in the List of default values field.

   • The Set default value option is not available for file, object, and user variables.

   • For object data type, you can choose between Simple view and JSON view to view the object properties.

Prerequisites for using user data type in an agentic workflow

You can use the user data type to define variables that hold tenant user details. Before you can list tenant users in an agentic workflow, you must configure access to the IBM Cloud platform APIs.

As a tenant administrator, complete the following steps to configure the access:

1. Create a service ID or user that represents your application or workflow. For more information, see the Managing service IDs.

2. Generate an API key for the Service ID. For more information, see Managing service ID API keys.

3. Assign the following roles to the Service ID or user:

   • Administrator role, scoped to the target wxO tenant as a resource

   • Viewer role for all IAM Account Management services

For more information on assigning roles, see Managing access to resources. After you assign these roles, register the API key of the Service ID or user as a connection with the predefined application ID WXO_PLATFORM_USER_API.

This prerequisite is only required for watsonx Orchestrate tenants that are hosted on IBM Cloud.

Adding properties to an object data type

You can add properties to an object data type for inputs, outputs, and variables.

To add properties to an object data type:

1. Select Object data type from the list.

2. Enter a Name and Description.

3. Optional: Select the List of objects checkbox to store a list of values in the object data type.

4. Click next to the object name in the object tree or click Add + in the Object properties section.

5. Select a property from the list.

6. Enter a Name and Description.

7. Optional: Select the List of {data type} checkbox to store a list of values in the object property.

8. Optional: Turn on the Set default values toggle switch to set the properties with a default value.

9. Enter a value and click in the default value field.

10. You can choose between Simple view and JSON view to view the object properties.

11. Click Save.

Object data types

When you define an object, consider the following elements. An object includes a name, an optional description, and a set of properties defined by using a simplified subset of the JSON schema standard. For more information, see the JSON schema documentation.

Properties can themselves be objects with their own nested properties. They can also be lists, which are defined by using the JSON schema array type.

Here is an example that shows the properties of an Employee object that is defined by using JSON schema

{
    "id": {
        "type": "integer",
        "description": "Unique identifier for the employee"
    },
    "firstName": {
        "type": "string",
        "description": "Employee's first name"
    },

    "lastName": {
        "type": "string",
        "description": "Employee's last name"
    },
    "email": {
        "type": "string",
        "description": "Employee's email address"
    },
    "department": {
        "type": "string",
        "description": "Employee's department"
    },
    "salary": {
        "type": "number",
        "description": "Employee's salary"
    },
    "isActive": {
        "type": "boolean",
        "description": "Whether the employee is currently active"
    },
    "startDate": {
        "type": "string",
        "format": "date",
        "description": "Employee's start date"
    },
    "badges": {
        "type": "array",
        "items": {
            "type": "string"
        },
        "description": "Employee's badges"
    },
    "address": {
        "type": "object",
        "properties": {
            "street": {
                "type": "string"
            },
            "city": {
                "type": "string"
            },
            "zipCode": {
                "type": "string"
            }
        }
    }
}

The employee object schema includes the following properties:

• id, email, salary, isActive, and startDate are simple properties that hold integer, string, decimal, boolean, and date values.

• address is an object property with nested properties: street, city, and zipCode.

• badges is a list, expressed as a JSON Schema array of string values.

You can download an example agentic workflow that is related to the Object data type from https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/examples/flow_builder/Employee_information. For more information, see Example agentic workflows.

Mapping data

Nodes within an agentic workflow might require data as input. This data can come from the inputs into the agentic workflow, from the outputs of upstream nodes, and from chat session context.

When an agentic workflow completes, it might also produce data as output. The data that is produced by the agentic workflow might come from the agentic workflow inputs or from nodes within the agentic workflow.

By default, when a node requires data as input, the agentic workflow engine attempts to identify potential data sources. If the agentic workflow engine locates a source, it automatically maps that data into the node. However, you can override this default behavior and provide a mapping on nodes or the agentic workflow output. To override the mapping behavior for the agentic workflow output, select the End node of the agentic workflow.

To edit data mapping in an agentic worklow, select the node and then click Edit data mapping.

The following data-mapping options are available:

• Automapping: An agentic workflow automatically maps data between steps by connecting node inputs to other nodes' outputs or to the agentic workflow’s own inputs. If a required piece of data isn’t produced by any node within the agentic workflow, you can define an agentic workflow-level input with the same name and type. The agentic workflow engine then maps it automatically, which can ensure seamless data transfer throughout the agentic workflow.

Date/time format for code blocks and expressions

When you define date and time values in code blocks or data map expressions, use the ISO 8601 standard format with IANA timezone support:

ISO 8601 format: YYYY-MM-DDThh:mm:ss±hh:mm[timezone/location]

Example: 2026-02-19T07:15:00+05:00[Europe/London]

Format breakdown:

• Date: YYYY (Year), MM (Month), DD (Day)

• Time: hh (Hour), mm (Minutes), ss (Seconds)

• Separator: A 'T' divides the date and time components

• Time Zone: 'Z' (UTC) or a ±hh:mm offset

• Timezone location: IANA timezone identifier in square brackets (for example, [Europe/London])

The timezone location is recommended but can be omitted. This format ensures logical sorting, eliminates ambiguity, and provides international recognition.

What to do next

Your agentic workflow is now created. You can use the Chat preview to test your agentic workflow.

• Adding user activities

A user activity consists of one or more chat-based interactions to collect input and display results within an agentic workflow.

• Adding logic blocks

A logic blocks adds custom logic as Python logic within your agentic workflow.

• Adding generative prompts

A generative prompt uses the capabilities of large language models (LLMs) for tasks.

• Adding document classifiers

A document classifier automatically identifies document types.

• Adding document extractors

A document extractor gets fields and entities from documents.

• Adding text extractors

A text extractor obtains text from a document.