客户端工具

客户端工具在用户的浏览器或主机应用程序上执行，从而能够访问服务器端不可用的客户端本地数据和设备功能。

客户端工具在客户端（用户的浏览器或主机应用程序）上执行，而不是在 UiPath 服务器上执行。当智能体调用客户端工具时，Runtime 会暂停，将工具调用委派给客户端，并在客户端返回结果后继续。

当智能体需要访问仅存在于客户端的数据或功能（例如应用程序状态、本地数据或无法在服务器端执行的用户界面操作）时，请使用客户端工具。

何时使用客户端工具

当智能体需要执行以下操作时，请使用客户端工具：

• 访问客户端本地数据— 从主机应用程序中读取服务器无法使用的信息，例如任务板的内容、表单字段或特定于会话的状态。
• 触发客户端操作— 在主机应用程序中执行操作，例如导航到页面、打开对话框、在本地用户界面中创建记录或更新组件。
• 利用特定于客户端的功能— 使用无法从服务器访问的设备或浏览器功能，例如剪贴板访问、本地存储或地理位置。

备注：

客户端工具仅适用于通过支持客户端工具处理的界面（例如UiPath TypeScript SDK或任何实现 UiPath 对话协议的界面）部署的对话智能体。界面必须为每个客户端工具注册一个处理程序；未注册处理程序的工具会将错误返回给智能体。

配置客户端工具

要将客户端工具添加到您的对话智能体：

1. 在智能体设计器中，选择“添加工具”。

2. 选择“客户端工具”类别。

3. 填写以下字段：

   • 工具名称— 工具的唯一名称。必须以字母或下划线开头，并且只能包含字母、数字、空格和下划线。
   • 描述— 描述该工具的功能以及何时使用。此描述可指导智能体决定是否调用工具。
   • 输入架构— 一个 JSON 架构对象，定义智能体在调用工具时传递给客户端的参数。
   • 输出架构— 一个 JSON 架构对象，定义了客户端返回给智能体的结果的结构。

   

4. 选择“创建”。

创建工具后，您可以在工具属性面板中配置其他设置：

• 编辑工具名称、描述和架构。
• 应用防护机制以强制执行 runtime 策略。
• 启用工具调用确认，要求用户批准后执行。

输入和输出架构

两个架构都是必需的，并且必须是有效的 JSON 架构对象。它们定义了智能体和客户端之间的合同：

• 输入架构指定智能体在调用工具时会向客户端发送哪些数据。智能体会根据对话上下文和架构定义填充输入值。
• 输出架构指定客户端在执行工具后返回给智能体的数据。智能体使用此结果继续推理。

架构示例

对于从项目板读取任务的工具：

输入架构：

{
  "type": "object",
  "properties": {
    "boardId": {
      "type": "string",
      "description": "The ID of the task board to read from"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in-progress", "done"],
      "description": "Filter tasks by status"
    }
  },
  "required": ["boardId"]
}

输出架构：

{
  "type": "object",
  "properties": {
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string" },
          "assignee": { "type": "string" }
        }
      }
    }
  }
}

预构建表面上的行为

在预构建的界面（如“实例管理”和iFrame 嵌入）上，客户端工具会根据输出架构向用户显示表单。用户手动填写字段，并将结果提交回智能体。

客户端工具的全部价值在使用UiPath TypeScript SDK构建的自定义界面上实现，其中主机应用程序以编程方式处理工具调用，读取数据、触发操作或与本地系统交互，无需用户手动输入。

客户端工具在运行时的工作方式

当智能体在对话中调用客户端工具时：

1. 智能体会根据对话上下文和工具描述决定使用该工具。
2. 如果启用了工具调用确认，则用户会在工具继续之前审核并批准建议的输入。
3. 运行时将工具调用（包括工具名称、输入值和输入/输出架构）发送到客户端界面。
4. 客户端界面使用提供的输入执行其为工具注册的处理程序。
5. 客户端将结果返回给运行时。
6. 智能体接收结果并继续推理。

工具调用确认

您可以要求用户确认，然后再执行客户端工具。这对于执行具有可见副作用的操作的工具非常有用，例如创建任务、更新记录或离开当前页面。

要为客户端工具启用确认：

1. 在智能体设计器中选择客户端工具。
2. 在工具属性中，启用“需要确认” 。

启用后，智能体会在执行工具之前暂停，向用户显示建议的输入参数。用户可以批准、修改输入或拒绝工具调用。

示例: 项目规划助手

考虑在任务管理应用程序中嵌入一个项目规划助手。该智能体有两个客户端工具：

• Read_board_tasks — 从主机应用程序的用户任务板读取当前任务。
• create_task — 在用户看板上创建新任务。

从客户端读取数据：当用户询问“接下来应该处理什么？”时，智能体会调用read_board_tasks 。主机应用程序读取看板状态并返回任务数据。然后，智能体会分析任务，并根据状态、截止日期和依赖项建议优先级顺序。

将数据写入客户端：当用户要求“添加任务以在星期五之前审核第三季度报告”时，智能体会调用create_task ，并提供标题、说明和到期日期。如果启用了确认，用户会首先查看建议的任务详细信息。主机应用程序在看板上创建任务，智能体确认已创建任务。

限制

• 客户端工具执行取决于客户端界面的可用性和响应能力。如果客户端在工具执行期间断开连接，则工具调用可能会失败。
• 客户端界面必须为智能体定义的每个客户端工具注册一个处理程序。如果缺少处理程序，工具调用将向智能体返回错误。