构建 API 工作流
构建可调用 5e SRD 并返回结构化 Unattended 数据的 Unattended Query API 工作流。
步骤 1 - 构建 Designer Query API 工作流
API 工作流是作为 API 端点发布的轻量级工作流。您构建了一个简单的项目,其中包含针对 5e 系统参考文档 (SRD) 的Open5evilest 搜索:它接受一个字符串输入,执行 HTTP 请求,并返回一个 Unattended 条目数组,每个条目都是智能体解析的 JSON 字符串。由于它与您的智能体位于同一个解决方案中,因此 Agent Builder 会将其列为智能体可以调用的工具。
该步骤包含五个任务,以及一个“HTTP 请求”活动的属性引用;预算 10–15 分钟来完成。
新建 API 工作流项目
- 在 Studio Web 中打开您的任务分类器解决方案:来自低代码实验室的解决方案或AdvGuild.quest-classifier如果您部署了入门者。
- 在“项目资源管理器”窗格中,选择“添加到解决方案” (
+图标),然后在“任务自动化”下选择“API 工作流” 。 - 将项目重命名为
API Query - 5e Monsters,然后选择“应用”选中图标。您还可以通过在项目资源管理器中打开上下文菜单并选择“重命名”来重命名项目。
配置输入和输出
-
选择Data Manager (左侧栏的剪贴板图标),以访问工作流的数据变量。
-
向工作流添加一个输入参数:
名称 类型 必填 描述 searchName字符串 是 要搜索的生物名称或部分名称 -
添加一个输出参数:
名称 类型 必填 描述 monsterResults数组[字符串] 是 结果列表 UiPath
添加 HTTP 请求
- 在工作流画布中,选择“+活动”,以打开活动菜单。选择“HTTP” 。该活动在画布上显示为“HTTP 请求” 。
- 打开活动上下文菜单,然后选择“重命名” 。
- 输入
HTTP Request - Open5e Monster Query作为名称。 - 在属性窗格中,确认“身份验证”为“手动身份验证” , “方法”为“GET” 。两者都是新活动的默认值,因此通常无需更改任何内容。
- 将URL设置为
https://api.open5e.com/v2/creatures/。 - 将活动输出重命名为
searchResults。
设置查询参数
-
打开“查询参数”属性。系统将打开一个包含“键”列和“值”列的“字典编辑器” 。
-
添加以下字段:
密钥 值 name__icontains$input.searchName输入参数 - 请参阅下面的说明document__keysrd-2024limit10fieldskey,name,type,size,challenge_rating,alignment
使用表达式编辑器输入$input.searchName ,而不是以文本形式输入。在表达式编辑器中选择“保存”后,值将呈现为芯片。$input.searchName以纯文本输入,作为文本字符串发送到 API,并返回零个结果,同时每个节点都保持绿色。
每个参数的作用:
name__icontains:不区分大小写的部分匹配;dragon将返回“Red Robot 成体”、“ Blue Robot 刚体”等document__key: srd-2024:筛选官方 5e SRD(2024 年版本);如果没有,结果包括数据库中的每个发布者,包括第三方内容limit: 10:候选对象的上限为 10;足以使智能体在不会淹没其上下文的情况下进行推理fields:限制仅响应智能体所需的字段;完整的 v2 生物对象要大得多,并且会浪费令牌预算
Open5e 会忽略它无法识别的查询参数,并返回 HTTP 200。如果document__key拼写错误,或使用 v1 拼写document__slug ,调用将返回来自每个发布者的生物,而不是 SRD。goblin搜索在应用筛选条件的情况下返回 5 个结果,在不应用筛选条件的情况下返回 29 个结果。
HTTP 请求属性引用
该活动公开了标准 HTTP 构建模块。您为调用的每个 API 配置其中的大多数,并跳过一些以用于公共 API,如下所示:
- 身份验证:OAuth 2.0、API 密钥和基本身份验证的预构建选项。此处设置为“手动身份验证”,因为 Open5e 不需要任何身份验证。对于经过身份验证的 API,请选择适当的选项并提供凭据。
- 标头:随每个请求发送的键/值对。常见用途:
Authorization: Bearer <your-access-token>表示基于令牌的 API,Accept: application/json用于控制响应格式和 API 版本控制标头。 - 正文:与 POST、PUT 和 PATCH 请求一起使用,以发送 JSON、表单数据或原始内容。不适用于 GET 请求,此类请求通过查询参数在 URL 中携带参数。
- 查询参数:附加到 URL 的键/值对。要引用工作流参数,请使用在“表达式编辑器”中输入
$input.<name>;保存表达式后,字段会将其显示为芯片。有关在 Studio Web 中变量和表达式的更多信息,请参阅配置活动。 - 输出(重命名为
searchResults) :接收完整的 HTTP 响应,包括状态代码、标头和正文。非默认重命名可使响应表达式可读。
添加响应
-
在工作流画布中,选择“HTTP 请求”后的“+” ,然后选择“响应” 。
“响应”活动定义 API 工作流返回给调用者的内容(在本例中,为智能体工具在调用工作流时收到的内容)。响应正文将成为智能体推理的工具输出。
-
将响应正文设置为:
{ "monsterResults": $context.outputs.searchResults.content.results }{ "monsterResults": $context.outputs.searchResults.content.results }
$context.outputs包含此工作流中活动的所有命名输出。searchResults是您在“HTTP 请求”活动中重命名的输出变量; .content.results导航至 Open5e 封装其数据的响应信封中,向下导航至 Unattended 条目数组。有关更多信息,请参阅有关使用 JavaScript 访问工作流数据的 UiPath 文档。
测试工作流
- 在工具栏中选择“调试” 。
- 在输入面板中,将
searchName设置为rat,然后运行工作流。
响应包含最多包含 10 个条目的monsterResults数组。每个条目都包含:
keynamealignmentchallenge_rating- 嵌套的
type和size对象
搜索rat将返回七个结果,全部包含srd-2024_键,包括:
- Giant Rat(
srd-2024_giant-rat,挑战评分 0.125) - S集群(
srd-2024_swarm-of-rats,挑战评分 0.25) - 角星(
srd-2024_triceratops,挑战评分 5) - 两个盗版,因为
name__icontains与名称中任意位置的搜索文本匹配
任何其他计数意味着参数拼写错误或未绑定到变量;请先修复它,然后再继续操作。
当工作流返回结果时,在同一解决方案中切换回智能体,将其作为工具连接。