构建 API 工作流

构建可调用 5e SRD 并返回结构化 Unattended 数据的 Unattended Query API 工作流。

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

An API workflow is a lightweight workflow published as an API endpoint. You build a simple one that wraps the Open5e monster search for the 5e System Reference Document (SRD): it takes a string input, does an HTTP request, and returns an array of monster entries, each a JSON string that the agent parses. Because it lives in the same solution as your agent, the agent builder lists it as a tool your agent can call.

This step has five tasks, plus a property reference for the HTTP Request activity; budget 10–15 minutes to complete it.

新建 API 工作流项目

1. Open your quest classifier solution in Studio Web: the one from the low-code lab, or AdvGuild.quest-classifier if you deployed the starter.
2. In the Project Explorer pane, select Add to solution (+ icon) and choose API Workflow under Task automation.
3. Rename the project to API Query - 5e Monsters and select the Apply check icon. You can also rename the project by opening the context menu in the project explorer and selecting Rename.

配置输入和输出

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

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

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

3. 添加一个输出参数：

   名称	类型	必填	描述
   monsterResults	Array[String]	是	结果列表 UiPath

添加 HTTP 请求

1. 在工作流画布中，选择“+活动”，以打开活动菜单。选择“HTTP” 。该活动在画布上显示为“HTTP 请求” 。
2. Open the activity context menu and select Rename.
3. Enter HTTP Request - Open5e Monster Query as the name.
4. 在属性窗格中，确认“身份验证”为“手动身份验证” ， “方法”为“GET” 。两者都是新活动的默认值，因此通常无需更改任何内容。
5. 将URL设置为https://api.open5e.com/v2/creatures/ 。
6. 将活动输出重命名为searchResults 。

Set the query parameters

1. Open the Query parameters property. It opens a Dictionary editor with Key and Value columns.

2. Add the following fields:

   密钥	值
   name__icontains	the $input.searchName input argument - see the note that follows
   document__key	srd-2024
   limit	10
   fields	key,name,type,size,challenge_rating,alignment

重要提示：

Use the Expression Editor to enter $input.searchName, instead of entering it as text. After you select Save in the expression editor, the value renders as a chip. Entered as plain text, $input.searchName goes to the API as a literal string and returns zero results while every node stays green.

每个参数的作用：

• name__icontains ：不区分大小写的部分匹配； dragon将返回“Red Robot 成体”、“ Blue Robot 刚体”等
• document__key: srd-2024: filters to the official 5e SRD (the 2024 edition); without it, results include every publisher in the database, third-party content included
• limit: 10 ：候选对象的上限为 10；足以使智能体在不会淹没其上下文的情况下进行推理
• fields：限制仅响应智能体所需的字段；完整的 v2 生物对象要大得多，并且会浪费令牌预算

重要提示：

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 call returns creatures from every publisher instead of the SRD. A goblin search returns 5 results with the filter applied and 29 without it.

HTTP 请求属性引用

The activity exposes the standard HTTP building blocks. You configure most of them for every API you call, and skip some for public APIs like this one:

• 身份验证：OAuth 2.0、API 密钥和基本身份验证的预构建选项。此处设置为“手动身份验证”，因为 Open5e 不需要任何身份验证。对于经过身份验证的 API，请选择适当的选项并提供凭据。
• 标头：随每个请求发送的键/值对。常见用途： Authorization: Bearer <your-access-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, use the Expression Editor to enter $input.<name>; after you save the expression, the field displays it as a chip. See configuring activities for more on variables and expressions in Studio Web.
• 输出（重命名为searchResults ） ：接收完整的 HTTP 响应，包括状态代码、标头和正文。非默认重命名可使响应表达式可读。

添加响应

1. 在工作流画布中，选择“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.

2. 将响应正文设置为：

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

测试工作流

1. 在工具栏中选择“调试” 。
2. In the input panel, set searchName to rat and run the workflow.

The response includes a monsterResults array of up to 10 entries. Each entry has:

• key
• name
• alignment
• challenge_rating
• Nested type and size objects

Searching rat returns exactly seven results, all with srd-2024_ keys, including:

• Giant Rat (srd-2024_giant-rat, challenge rating 0.125)
• Swarm of Rats (srd-2024_swarm-of-rats, challenge rating 0.25)
• Triceratops (srd-2024_triceratops, challenge rating 5)
• Two pirates, because name__icontains matches the search text anywhere in the name

Any other count means a parameter is misspelled or not bound to the variable; fix it before you continue.

---

With the workflow returning results, switch back to the agent in the same solution to connect it as a tool.