构建 API 工作流

构建调用 D&D 5e SRD 并返回结构化小角色数据的小角色查询 API 工作流。

步骤 1 - 构建 Designer Query API 工作流

API 工作流是作为 API 端点发布的轻量级工作流。您构建一个包含Open5e D&D 5e SRD Monastery 搜索的应用程序：一个输入、一个 HTTP 请求、一个输出。发布后，它将显示在智能体构建器中，作为智能体可以调用的工具。

此步骤包含六个子步骤；预算 10–15 分钟来完成。

新建 API 工作流项目

从云端工作区中选择“新建” ，然后选择“API 工作流”作为项目类型。

重命名解决方案和默认工作流。在项目资源管理器中打开每个名称的上下文菜单，然后选择“重命名” ：

• 解决方案名称： Monster Query - 5e SRD
• 工作流名称： API Query - 5e Monsters

配置输入和输出

选择Data Manager （左侧栏的剪贴板图标），以访问工作流的数据变量。

向工作流添加一个输入参数：

名称	类型	必填	描述
searchName	字符串	是	要搜索的生物名称或部分名称

添加一个输出参数：

名称	类型	必填	描述
monsterResults	数组	是	结果列表 UiPath

添加 HTTP 请求

1. 在工作流画布中，选择“+活动”，以打开活动菜单。选择“HTTP 请求” 。
2. 打开活动上下文菜单，然后选择“重命名” 。将其命名为HTTP Request - Open5e Monster Query 。
3. 在“属性”窗格中，将“身份验证”设置为“手动身份验证” 。
4. 将“方法”设置为“GET” 。
5. 将URL设置为https://api.open5e.com/v1/monsters/ 。
6. 将活动输出重命名为searchResults 。

设置“查询参数”属性：

打开“查询参数”属性并添加以下字段：

密钥	值
name__icontains	@searchName
document__slug	wotc-srd
limit	10
fields	slug,name,desc,type,size,cr,challenge_rating,alignment,v2_converted_path

每个参数的作用：

• name__icontains ：不区分大小写的部分匹配； dragon将返回“Red Robot 成体”、“ Blue Robot 刚体”等
• document__slug: wotc-srd ：筛选官方 D&D 5e SRD；如无 ID，结果将包含第三方 Homebrew 内容
• limit: 10 ：候选对象的上限为 10；足以使智能体在不会淹没其上下文的情况下进行推理
• fields ：仅响应智能体所需的字段；完整的 Open5e Unattended 对象要大得多，并且会浪费令牌预算

HTTP 请求属性引用

该活动公开了标准 HTTP 构建模块。您将为调用的每个 API 配置大多数；对于公共 API，您可以跳过一些步骤，例如以下 API：

• 身份验证：OAuth 2.0、API 密钥和基本身份验证的预构建选项。此处设置为“手动身份验证”，因为 Open5e 不需要任何身份验证。对于经过身份验证的 API，请选择适当的选项并提供凭据。
• 标头：随每个请求发送的键/值对。常见用途： Authorization: Bearer <token>表示基于令牌的 API， Accept: application/json用于控制响应格式和 API 版本控制标头。
• 正文：与 POST、PUT 和 PATCH 请求一起使用，以发送 JSON、表单数据或原始内容。不适用于 GET 请求，此类请求通过查询参数在 URL 中携带参数。
• 查询参数：附加到 URL 的键/值对。@variableName语法按名称引用工作流参数； @searchName拉取在数据管理器中定义的searchName输入参数。有关在 Studio Web 中变量和表达式的更多信息，请参阅配置活动。
• 输出（重命名为searchResults ） ：接收完整的 HTTP 响应，包括状态代码、标头和正文。重命名默认值可使“设置响应表达式”可读。

添加响应

1. 在工作流画布中，选择“HTTP 请求”后的+ ，然后选择“设置响应” 。

   “设置响应”定义了 API 工作流返回给调用者的内容（在本例中，为智能体工具在调用工作流时收到的内容）。您在此处的响应正文中输入的任何内容都将成为智能体推理的工具输出。

2. 将响应正文设置为：

   {
     "monsterResults": $context.outputs.searchResults.content.results
   }
   

$context.outputs包含此工作流中活动的所有命名输出。searchResults是您在“HTTP 请求”活动中重命名的输出变量； .content.results导航到 Open5e 包含其数据的响应信封中，一直到实际的 Unattended 条目数组。有关更多信息，请查看关于使用 Javascript 访问工作流数据的 UiPath 文档。

测试工作流

1. 在工具栏中选择“调试” 。
2. 在输入面板中，将searchName设置为dragon或goblin ，然后运行工作流。
3. 请先验证响应是否包含包含巨大条目的monsterResults数组，然后再继续操作。

一个成功的响应最多包含 10 个条目，每个条目都包含name 、 type 、 cr和slug等字段。如果看到空数组，请尝试其他搜索词；并非每个生物名称在 SRD 中都有完全匹配项。

发布到您的订阅源

发布可以在 Orchestrator 中将工作流注册为可部署的流程。这使其可以在 Agent Builder 的“可用资源”列表中发现：构建器显示您工作区中已发布的工作流，而不是本地保存在 Studio Web 中的草稿。

1. 在工具栏中选择“发布” 。
2. 在发布对话框中，选择“对于我” ，以发布到您的个人工作区订阅源。个人工作区订阅源是与 Orchestrator 工作区绑定的私有包存储库；发布“属于我”后，此工作流仅对您可见，您正是开发和测试的作用域。有关详细信息，请参阅 UiPath 文档中的个人工作区。
3. 选择“发布”以确认。

备注：

工作流未出现在步骤 3 的“可用资源”中？工作流必须先发布（而不仅仅是保存），然后才能作为工具查看。如果未显示，请返回此处并确认已成功完成发布，然后刷新智能体构建器。

---

工作流发布后，下一部分将在 Agent Builder 中作为可连接的工具使用。