创建代理工作流程

关于本任务

创建代理工作流程时，首先要有一个起始节点和一个结束节点。起始节点是代理工作流程的入口点。它定义了开始执行所需的输入，如用户或外部系统提供的值。它还会初始化代理工作流变量，这些变量会在代理工作流进行过程中使用。结束节点是代理工作流程的出口点。它定义了代理工作流执行完毕后返回的输出。

创建代理工作流程的顺序由您决定。如果您知道想在序列中包含哪些类型的活动，就可以开始添加这些活动。

异步运行的代理工作流，可以长期运行。在聊天中运行代理工作流工具时，您会提供代理工作流输入，但任何代理工作流输出都可能无法立即获得。使用提供的 " 获取流量状态 "实用工具，可随时检查工具的状态并检索工具的输出。

提示：

如果您添加了一个代理工作流输入，并且希望确保代理会提示用户提供该输入，请将该输入标记为必填项。如果有嵌套输入类型，请将输入标记为需要代理提示的嵌套属性。如果输入或属性有默认值，代理可能会使用默认值，而不是提示用户输入值。

创建代理工作流程

可为特定代理创建代理工作流程，或直接将其添加到系统中。

在系统中创建代理工作流程：

在菜单中，导航至 “构建 ”。
导航至所有工具。

在 IBM Cloud 环境中，从工作区列表中选择您要创建工作流的工作区。

您可以根据自己的角色和工作区级权限，选择全局工作区或私有工作区，或者创建一个新的工作区。您创建的所有工作流仅与所选工作区相关联，且仅在该工作区内可见。
选择现有工具，或单击 " 创建工具 +" 添加新工具。
选择代理工作流程。
为工作流输入一个有意义的名称。
点击开始构建。流程编辑器随即打开，您可以在这里开始创建您的代理工作流。

为代理创建代理工作流程：

在菜单中，导航至 “构建 ”。
导航至所有代理。

在 IBM Cloud 环境中，从工作区列表中选择与您的代理关联的工作区。
查找并点击您的代理。
在 " 工具集 "部分的代理工具集中，单击 " 添加工具 "。
单击代理工作流程。
为工作流输入一个有意义的名称。
点击开始构建。流程编辑器随即打开，您可以在这里开始创建您的代理工作流。

编辑代理工作流详细信息

编辑代理工作流程详情：

在菜单中，导航至 “构建 ”。
导航至所有工具。

在 IBM Cloud 环境中，从工作区列表中选择与该工作流相关联的工作区。
选择工作流，点击“选项”图标，然后选择 “编辑详细信息 ”。
在 “概述 ”选项卡中，更新名称并为该工具输入描述。
单击 “参数 ”选项卡，以配置该工具的输入和输出。
单击添加输入以定义输入。有关详细说明，请参阅添加输入
单击添加输出定义输出。有关详细说明，请参阅 " 添加输出"
单击完成。

示例代理工作流

您可以从 https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/examples/flow_builder 下载代理工作流示例。有关如何将工作流导入到您的 watsonx Orchestrate 环境中的信息，请参阅ADK文档中的 “构建基于代理的工作流”。

配置工作流程设置

通过工作流设置，您可以自动将聊天记录映射到节点输入，并自定义大型对话中数据的汇总方式。

要配置工作流设置：

在工作流构建器中，点击子标题右侧的。
自动将聊天记录映射到输入选项默认设置为 "开启"，这会自动将聊天记录中的最后五个对话回合映射为节点输入。
如果选择自定义摘要说明，则单击自定义摘要说明旁边的编辑。
1. 输入总结指令。请提供具体指导，例如必须保持不变的关键细节，以及为缩减篇幅可以安全省略的内容。
2. 单击保存。

添加工具

您可以向代理工作流中添加工具，以扩展代理的功能。有关更多信息，请参阅添加工具。

添加代理

您可以在代理式工作流中添加代理，以管理流程中的特定任务操作。有关更多信息，请参阅添加代理。

配置代理工作流程控制

代理工作流控件定义了代理工作流的执行路径。通过配置代理工作流控件，您可以设置条件、分支和循环，以确定数据如何在节点之间移动。

添加分支控制

分支控制着代理工作流程中的路径。路径根据指定条件定义。您可以为分支定义多个路径和路径条件。如果不满足任何条件，代理工作流程将遵循默认路径。

要在代理工作流程中添加一个分支：

要创建分支，要么
- 点击图标。在 “流节点 ”选项卡中，单击并拖动分支控件到画布上。您可以将控件直接放在连接线上或画布上的任何位置。
- 点击起始节点与终止节点之间的连接线。选择添加流程控制 > 分支。连接线上会自动插入一个分支。
该分支通过 if-else 语句预先配置。

添加路径

为分支添加路径

点击分支。
在分支窗口中，选择添加路径。

添加路径条件

为路径添加条件

点击分支。
找到路径并选择编辑条件。从以下选项中选择一个来定义条件：
- 使用条件创建器创建条件：
  1. 在“条件构建器 ”窗口中，单击，然后从 “可用变量 ”下拉列表中选择一个变量。
  2. 点击，然后从下拉列表中选择一个运算符。
  3. 点击并输入数值。
  4. 按 Enter 键。要添加多个条件，请选择添加条件。
- 使用表达式编辑器创建条件：
  1. 选择表达式编辑器 。
  2. 单击输入表达式 ，然后输入 Python 表达式。
点击返回。

编辑或删除条件

要编辑路径的条件：

点击分支。
找到路径并选择编辑条件。选择以下选项之一编辑条件：
- 使用条件生成器编辑条件：
  1. 更新变量、运算符和值。
  2. 点击输入。
- 使用表达式编辑器编辑条件：
  1. 选择表达式编辑器。
  2. 单击表达式打开编辑器窗口，更新 Python 表达式。

删除路径的条件：

点击分支。
找到路径并选择编辑条件。
点击“删除条件 ”。

编辑路径

您可以通过更改顺序、重命名路径或删除路径来管理分支中的路径。

更改路径顺序

点击分支。
点击“更多操作” 。
从列表中选择 “向上移动 ”或 “向下移动” 以更改顺序。

您还可以通过点击并拖动路径旁边的图标来重新排列路径的顺序。

编辑路径

点击分支。
点击“更多操作” 。
选择编辑路径名并输入新名称。

删除路径

点击分支。
点击“更多操作” 。
选择删除。

添加一个 For each 控件

A For each 控件针对列表中的每个项目运行一系列操作。迭代器变量表示列表中的当前项目，索引变量表示其位置，从 0 开始。您可以使用它们访问和处理列表中的每个项目。

要创建 For each 控件，请执行以下任一操作：

点击图标。在 “流程节点 ”选项卡中，点击并拖动 “对于每个 ”控件到画布上。您可以将控件直接放在连接线上或画布上的任何位置。
点击起始节点与终止节点之间的连接线。选择添加流程控制 > 对于每个。每个控制器都会自动插入连接线。

您可以从 https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/examples/flow_builder/recent_transactions 下载一个与 “For each ”控件相关的代理工作流示例。如需了解更多信息，请参阅 “代理工作流示例”。

选择列表

为每个控件选择列表：

单击对于每个控件。
使用以下选项之一选择列表：
- 默认情况下，自动映射功能处于启用状态，该功能会从 agentic 工作流的输入中选择一个列表对象。

不过，您可以通过选择变量或表达式选项来更改默认行为并配置列表对象。

若要使用变量配置列表对象，请单击，然后从 “可用变量 ”列表中选择一个变量。
若要使用表达式配置列表对象，请选择，然后在“选择列表字段 ”下点击 “输入表达式 ”以打开编辑器窗口，并更新 Python 表达式。

一旦选择了列表对象，就会自动提供迭代器和索引变量。

添加局部变量

局部变量仅在 For each 控件内使用，在该控件外无法访问。 For each 的每个迭代都可以存储该迭代的中间结果。这些值存储在它们内部，不能在不同的迭代中共享。

为每个控件添加局部变量：

单击对于每个控件。
在 “局部变量 ”部分中单击。
在本地变量窗口中选择添加。
从下拉列表中选择变量类型。
输入名称和描述。
如果您想在变量中存储值列表，请选中 {object type} 列表复选框。
单击添加。

若要添加多个局部变量，请单击 “添加”。

编辑或删除局部变量

编辑本地变量

单击对于每个控件。
在 “局部变量 ”部分中单击。
将鼠标悬停在变量上，然后选择。
在更新输出窗口中更新名称和说明。
单击保存。

删除本地变量

单击对于每个控件。
在 “局部变量 ”部分中单击。
将鼠标悬停在变量上，然后选择。

配置活动

活动定义了代理工作流可以执行的操作。您可以根据要完成的任务配置不同类型的 x。

用户活动

您可以使用用户活动创建基于聊天的交互，以收集输入并在代理工作流程中显示结果。如需了解更多信息，请参阅 “添加用户活动”。

有关如何添加用户活动的示例视频，请参阅“视频”部分中的《在 watsonx Orchestrate 中使用用户活动构建主动工作流》。

逻辑模块

您可以在代理式工作流中直接使用逻辑块添加自定义 Python 逻辑。如需更多信息，请参阅 “添加逻辑块”。

生成提示

当您需要帮助完成涉及自然语言理解的任务时，可以使用生成式提示。它通过使用大型语言模型（LLM）来生成文本或结构化内容。对于代理工作流程中的生成提示，您可以通过人工智能网关添加新模型。如需了解更多信息，请参阅 “添加生成式提示词 ”。

有关如何添加生成式提示词的示例视频，请参阅“视频”栏目中的《在 watsonx Orchestrate 中使用生成式提示词构建自主工作流》。

文件分类器

您可以在代理工作流程中添加文档分类器，以自动识别文档类型。如需了解更多信息，请参阅 “添加文档分类器 ”。

文件提取器

您可以在代理工作流中添加文档提取器，以便从文档中提取日期、姓名等字段或实体。如需更多信息，请参阅 “添加文档提取器 ”。

文本提取器

您可以在代理工作流程中使用文本提取器从文档中提取文本。如需更多信息，请参阅 “添加文本提取器 ”。

流检查器

Flow Inspector 提供了一个汇总的代理工作流执行历史视图，帮助您查看工作流从开始到结束的运行过程。您可以检查执行序列，分析各步骤之间交换的数据，并诊断错误或异常行为。有关流程检查器功能和性能的详细信息，请参阅《检查代理工作流》。

输入和输出

输入是指在运行时传递给代理工作流的外部值。它们提供了启动代理工作流执行所需的初始信息。输入可以包括用户提供的值、系统值或从其他进程接收的数据。

输出是指代理工作流执行完成后生成的结果。它们定义了代理工作流返回的信息，例如处理后的数据或针对上游节点的响应。输出使代理工作流的结果能够在其他流程、工具或工作流中被重复利用。

添加输入

添加代理工作流程输入：

单击启动节点。
在输入窗口中，单击添加。
从列表中选择输入类型。
输入名称和描述。
可选：勾选 “ {data type} 列表 ”复选框，可在输入框中存储一组值。
可选：开启 “设置默认值 ”切换开关，为输入项设置默认值。
在默认值字段中输入一个值，然后单击。
单击添加。
- 如果选中 “ {data type} 列表 ”复选框，您可以在 “默认值列表 ”字段中添加多个默认值。
- 文件输入框不支持勾选 {data type} 选项，文件和对象输入框不支持设置默认值选项。
- 对于对象数据类型，您可以选择 “简易视图 ”或 “JSON视图 ”来查看对象的属性。

添加输出

添加代理工作流程输出：

单击“结束”节点。
在输出窗口中，单击添加。
从列表中选择输出类型。
可选：勾选 “ {data type} 列表 ”复选框，以生成值列表作为输出。
单击添加。
- {data type} 复选框列表不适用于文件输入。
- 对于对象数据类型，您可以选择 “简易视图 ”或 “JSON视图 ”来查看对象的属性。

代理工作流程中的流程变量

代理工作流运行时使用流量变量。您可以从可用选项中进行选择，也可以定义自定义变量。它们允许节点之间共享数据，并在不同步骤中保留和提供中间值。整个代理工作流程都可以访问流量变量，节点之间可以共享和更新流量变量。

添加流变量

添加流量变量：

点击代理工作流窗口左侧的图标。
单击添加，然后从列表中选择变量类型。
输入名称和描述。
可选：选中 “ {data type} 列表 ”复选框，将值列表存储在该变量中。
可选：开启 “设置默认值 ”切换开关，为该变量设置默认值。
在默认值字段中输入一个值，然后单击。
单击添加。
- 如果选中 “ {data type} 列表 ”复选框，您可以在 “默认值列表 ”字段中添加多个默认值。
- “设置默认值 ”选项不适用于文件、对象和用户变量。
- 对于对象数据类型，您可以选择 “简易视图 ”或 “JSON视图 ”来查看对象的属性。

输入、输出和变量类型

下表列出了代理工作流程中可用的输入、输出和变量类型：


Type	描述
布尔值	定义需要真假值的输入、输出或变量
日期/时间	用于定义日期、时间或日期与时间的组合值。日期值采用 mm/dd/yyyy 格式。时间值采用 hh:mm 格式，并带有上午/下午选项。对于日期和时间，您还可以从提供的列表中选择时区。
Decimal	定义包含小数点的数值
文件	定义一个可传递进出流程的文件。它可用于上传或下载文件、文档处理，或在流程中将文件传入或传出某个工具。
整数	定义整数值
对象	使用 JSON 模式定义输入、输出或变量对象属性
字符串	定义基于文本的输入、输出或变量
用户	定义用于存储用户相关信息的变量

提示：

用户数据类型仅适用于流量变量，目前不支持流量输入或流量输出。

在代理工作流中使用用户数据类型的先决条件

您可以使用用户数据类型来定义存储租户用户详细信息的变量。在代理式工作流中列出租户用户之前，必须先配置对 IBM Cloud 平台API的访问权限。

作为租户管理员，请完成以下步骤来配置访问权限：

创建一个代表您的应用程序或工作流的服务ID或用户。如需更多信息，请参阅 “管理服务 ID ”。
为服务ID生成API密钥。如需了解更多信息，请参阅《管理服务 ID API 密钥》。
为服务ID或用户分配以下角色：
- 管理员角色，作用域限定为目标 wxO 租户作为资源
- 所有IAM账户管理服务的查看者角色

有关分配角色的更多信息，请参阅 “管理资源访问权限 ”。分配完这些角色后，请将服务 ID 或用户的 API 密钥注册为与预定义应用程序 ID 的连接 WXO_PLATFORM_USER_API。

此先决条件仅适用于托管在 IBM Cloud 上的 watsonx Orchestrate 租户。

设置连接

完成先决条件后，请按照以下步骤配置连接：

激活您的租户环境。
orchestrate env activate
添加连接。
orchestrate connections add -a WXO_PLATFORM_USER_API
配置草稿环境和生产环境的连接。
orchestrate connections configure -a WXO_PLATFORM_USER_API --env draft -t -k <api_key> orchestrate connections configure -a WXO_PLATFORM_USER_API --env live -t -k <api_key>
设置 API 密钥凭证。
orchestrate connections set-credentials -a WXO_PLATFORM_USER_API --env draft --api-key <api_key> orchestrate connections set-credentials -a WXO_PLATFORM_USER_API --env live --api-key <api_key>

完成设置后，您的代理工作流即可通过使用用户数据类型安全地访问租户用户详细信息。

为对象数据类型添加属性

您可以为输入、输出和变量对象数据类型添加属性。

要为对象数据类型添加属性：

从列表中选择对象数据类型。
输入名称和描述。
可选：选中“对象列表 ”复选框，可在对象数据类型中存储值的列表。
在对象树中单击对象名称旁边的“下一步”，或在 “对象属性 ”部分单击 “添加 + ”。
从列表中选择一个属性。
输入名称和描述。
可选：选中 “ {data type} 列表 ”复选框，可在对象属性中存储值列表。
可选：开启 “设置默认值 ”切换开关，为属性设置默认值。
在默认值字段中输入一个值，然后单击。
您可以选择简易视图或 JSON 视图来查看对象属性。
单击保存。

对象变量不支持设置默认值选项。

对象数据类型

定义对象时，请考虑以下要素。对象包含名称、可选描述以及一组属性，这些属性通过简化版的JSON模式标准子集进行定义。如需更多信息，请参阅 JSON 模式文档。

属性本身可以是具有自身嵌套属性的对象。它们也可以是列表，通过使用JSON模式数组类型来定义。

以下是一个示例，展示了使用JSON模式定义的Employee对象的属性

{
    "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"
            }
        }
    }
}

员工对象模式包含以下属性：

id, email, salary, isActive, 和 startDate 是简单属性，分别存储整数、字符串、十进制数、布尔值和日期值。
address 是一个具有嵌套属性的对象属性：街道、城市和 zipCode。
badges 是一个列表，以JSON Schema字符串数组的形式表示。