Creating agentic workflows

Edit agentic workflow details

To edit agentic workflow details:

1. Click Edit details.
2. In the Overview field, update the name.
3. Enter a description for the tool.
4. Click Parameters to configure inputs and outputs for the tool.
5. Click Add inputs to define the input. For detailed instruction, see Adding inputs
6. Click Add outputs to define the output. For the detailed instruction, see Adding outputs
7. Click Done.

Adding tools that use member credentials to agentic workflows

You can add tools to agentic workflows that use member credentials for their connections. For more information about member credentials, see Credential types.

If member credentials are not available at runtime, the system prompts you to enter the credentials in the chat. If a tool uses multiple connections that require credentials, the system prompts you for each set of credentials as needed during runtime.

After a connection is successfully established with member credentials, the system saves the credentials on the Manage > Connections > Credentials tab. You are not prompted for the credentials again after the connection succeeds. However, tools that use time-based authorization for connections might prompt you to reenter the credentials in the chat after a specified time interval.

Manage error handling

Error handling allows you to customize the error message that is shown to the user if the tool fails. You can also optionally configure the flow to retry the call the tool if it fails.

To define error handling for a tool:

1. Open the tool and click next to Error handling.

2. In the Error handling window, Modify the Error message if necessary.

3. If you want, you can configure the tool to retry on error. To configure:

   1. Enable Retry on error.

   The following error codes are supported:

   • 408 Request Timeout: The client took too long; retry may succeed.
   • 409 Conflict: Often used for version conflicts; retry after resolving the conflict.
   • 425 Too Early: Request was sent too soon; retry later.
   • 429 Too Many Requests: Throttling; retry after waiting for Retry-After header.
   • 500 Internal Server Error: Generic server error; may be transient.
   • 502 Bad Gateway: Temporary proxy/server issue; retry may succeed.
   • 503 Service Unavailable: Server that is temporarily overloaded or down for maintenance.
   • 504 Gateway Timeout: Upstream server didn’t respond in time; retry may succeed.
   2. Enter the Maximum number of retries (between 1 and 5).
   3. Adjust the Wait time between retries in milliseconds (between 1000 and 60000). The default value is 1000 ms.

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.

Code blocks

You can use code block to add custom Python code directly within an agentic workflow. For more information, see Adding code 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 have selected 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 have selected 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 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.

4. After assigning 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 wxO tenants 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.

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.

Using the chat session context in automapping

Previously, agentic workflows did not automatically have access to the information entered into the chat prior to the workflow being triggered. To make the information available to the workflow, you had to define flow inputs and instruct the agent to populate them from the chat context. That process is no longer necessary and workflows can now easily be granted access to the most recent information in the chat context.

Enabling chat session context includes the last 5 conversation turns from a chat history. A conversation turn refers to a single exchange between a user and the agent in a chat.

Agentic workflows have this capability by default. If you want to turn it off, or want to check if it is enabled for your specific workflow:

1. Open the agentic workflow.
2. Click the Settings icon .
3. Use the Auto-map chat history to inputs switch to turn the feature on or off.

If automapping is unsuccessful, you can prompt the user to provide the required input in a chat. To enable this behavior, set the Ask user for input if auto-mapping is unsuccessful switch to on when automapping data.

• Blank parameters: To leave a parameter blank, close the Auto-map option for the node parameter. If input parameters for a node in an agentic workflow are left empty or blank, then no value is passed to the input parameter throughout the agentic workflow.

• Python expressions: You can add Python expressions for node parameters in an agentic workflow.

• Variables: You can add variables for node parameters in an agentic workflow.

• Literal values: You can add a specific literal value for agentic workflow runtime, such as a number or a date, to node parameters in an agentic workflow. To add a literal value, close the Auto-map option for the node parameter. The option to set a default value is not available for parameters that are mapped to literal values.

• Default values: You can add a specific default value to node parameters in an agentic workflow. The option to set a default value is not available for parameters that are mapped to literal values.

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 code blocks

  A code blocks adds custom logic as Python code 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.