构建 API 工作流
构建可调用 5e SRD 并返回结构化 Unattended 数据的 Unattended Query API 工作流。
步骤 1 - 构建 Designer Query API 工作流
API 工作流是作为 API 端点发布的轻量级工作流。您构建了一个简单的项目,其中包含针对 5e 系统参考文档 (SRD) 的Open5evilest 搜索:它接受一个字符串输入,执行 HTTP 请求,并返回一个 Unattended 条目数组,每个条目都是智能体解析的 JSON 字符串。由于它与您的智能体位于同一个解决方案中,因此 Agent Builder 会将其列为智能体可以调用的工具。
This step has five tasks, plus a property reference for the HTTP Request activity; budget 10–15 minutes to complete it.
新建 API 工作流项目
- Open your quest classifier solution in Studio Web: the one from the low-code lab, or AdvGuild.quest-classifier if you deployed the starter.
- In the Project Explorer pane, select Add to solution (
+icon) and choose API Workflow under Task automation. - 将项目重命名为
API Query - 5e Monsters,然后选择“应用”选中图标。您还可以通过在项目资源管理器中打开上下文菜单并选择“重命名”来重命名项目。
配置输入和输出
-
选择Data Manager (左侧栏的剪贴板图标),以访问工作流的数据变量。
-
向工作流添加一个输入参数:
名称 类型 必填 描述 searchName字符串 是 要搜索的生物名称或部分名称 -
添加一个输出参数:
名称 类型 必填 描述 monsterResults数组[字符串] 是 结果列表 UiPath
添加 HTTP 请求
- 在工作流画布中,选择“+活动”,以打开活动菜单。选择“HTTP” 。该活动在画布上显示为“HTTP 请求” 。
- 打开活动上下文菜单,然后选择“重命名” 。
- Enter
HTTP Request - Open5e Monster Queryas the name. - 在属性窗格中,确认“身份验证”为“手动身份验证” , “方法”为“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 请求”后的“+” ,然后选择“响应” 。
The Response activity defines what the API Workflow returns to its caller (in this case, what the agent's tool receives when it invokes the workflow). The response body becomes the tool output the agent reasons over.
-
将响应正文设置为:
{ "monsterResults": $context.outputs.searchResults.content.results }{ "monsterResults": $context.outputs.searchResults.content.results }
$context.outputs contains every named output from the activities in this workflow. searchResults is the output variable you renamed on the HTTP Request activity; .content.results navigates into the response envelope that Open5e wraps its data in, down to the array of monster entries. For more information, see the UiPath documentation on using JavaScript to access workflow data.
测试工作流
- 在工具栏中选择“调试” 。
- In the input panel, set
searchNametoratand run the workflow.
The response includes a monsterResults array of up to 10 entries. Each entry has:
keynamealignmentchallenge_rating- Nested
typeandsizeobjects
搜索rat将返回七个结果,全部包含srd-2024_键,包括:
- Giant Rat(
srd-2024_giant-rat,挑战评分 0.125) - S集群(
srd-2024_swarm-of-rats,挑战评分 0.25) - Triceratops (
srd-2024_triceratops, challenge rating 5) - 两个盗版,因为
name__icontains与名称中任意位置的搜索文本匹配
任何其他计数意味着参数拼写错误或未绑定到变量;请先修复它,然后再继续操作。
With the workflow returning results, switch back to the agent in the same solution to connect it as a tool.