构建 API 工作流

Build a Monster Query API Workflow that calls the 5e SRD and returns structured monster data.

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

An API Workflow is a lightweight workflow published as an API endpoint. You build one that wraps the Open5e 5e SRD monster search: one input, one HTTP request, one output. Once published, it appears in the agent builder as a tool your agent can call.

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

新建 API 工作流项目

Select Create New from your Cloud Workspace. In the Start building dialog, choose API Workflow under Task automation.

Selecting the type creates the project immediately, with no name prompt, so you rename it in the next step.

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

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

配置输入和输出

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

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

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

添加一个输出参数：

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

添加 HTTP 请求

1. In the workflow canvas, select + between activities to open the activity menu. Select HTTP. The activity appears on the canvas as HTTP Request.
2. 打开活动上下文菜单，然后选择“重命名” 。将其命名为HTTP Request - Open5e Monster Query 。
3. In the Properties pane, confirm Authentication is Manual authentication and Method is GET. Both are the defaults on a new activity, so there is normally nothing to change.
4. 将URL设置为https://api.open5e.com/v2/creatures/ 。
5. 将活动输出重命名为searchResults 。

Set the Query parameters property:

Open the Query parameters property, which opens a Dictionary editor with Key and Value columns, and add the following fields:

密钥	值
name__icontains	the searchName input argument - see the warning below
document__key	srd-2014
limit	10
fields	key,name,type,size,challenge_rating,alignment

警告：

name__icontains takes the searchName variable, and you must pick it from the variable picker rather than typing it. In the value field, start by typing @ to open the picker and select searchName - not using the picker will send the input as a literal string, and the API will return HTTP 200 with no results. The field then renders the value as a chip, and the stored value is $input.searchName.

每个参数的作用：

• name__icontains ：不区分大小写的部分匹配； dragon将返回“Red Robot 成体”、“ Blue Robot 刚体”等
• document__key: srd-2014: filters to the official 5e SRD; without it, results include every publisher in the database, third-party content included
• limit: 10 ：候选对象的上限为 10；足以使智能体在不会淹没其上下文的情况下进行推理
• fields: limits the response to only the fields the agent needs; the full v2 creature object is much larger and would waste token budget

警告：

Open5e ignores query parameters it does not recognize, and returns HTTP 200 anyway. Misspell document__key, or use the v1 spelling document__slug, and the filter is silently dropped: the call succeeds, the run is green, and the agent receives creatures from every publisher instead of the SRD. A goblin search returns 2 results with the filter applied and 29 without it, so check that the result count looks like a handful rather than a catalogue.

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 中携带参数。
• Query parameters: key/value pairs appended to the URL. To reference a workflow argument, enter @ to open the variable picker and select the argument - the field stores $input.<name> and displays it as a chip. @ is the picker's trigger character, not a reference syntax you can type out. See configuring activities for more on variables and expressions in Studio Web.
• Output (renamed to searchResults): receives the full HTTP response including status code, headers, and body. Renaming from the default keeps the Response expression readable.

添加响应

1. In the workflow canvas, select + after the HTTP Request and select Response.

   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). Whatever you put in the response body here becomes the tool output the agent reasons over.

2. 将响应正文设置为：

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

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

测试工作流

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

A successful response contains up to 10 entries, each with key, name, alignment, and challenge_rating, plus nested type and size objects. Searching goblin returns Goblin and Hobgoblin. If you see an empty array, try a different search term; not every creature name has an exact match in the SRD.

发布到您的订阅源

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

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

备注：

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

---

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