客户端函数工具

如果您有客户端代码可以访问但托管工具（例如OpenAPI或MCP）无法访问的功能，则可以使用客户端函数工具。客户端函数工具始终在客户端执行，而不是由代理执行。

工作原理

当代理触发客户端函数工具时：

  1. 会话阻止：对话会话在 服务器端被有效“阻止”。
  2. 客户端执行：您的客户端应用必须识别工具调用 并在本地环境中执行相应的逻辑。
  3. 提供响应：执行完成后，您的客户端 应用必须使用 toolResponses 字段将响应提供给代理。

代理会等待此响应，然后再继续对话。

配置

创建客户端函数工具时，您可以定义代理如何理解客户端代码并与之互动：

  • 名称：工具的唯一标识符（例如：open_settings）。
  • 说明：对工具用途的简要说明。代理模型使用此说明来确定何时调用函数。
  • 输入/输出架构：以 OpenAPI 格式定义。这决定了代理发送和期望接收的数据的结构。

使用场景

客户端函数工具非常适合以下情况：

  • 界面/用户体验操作：触发应用界面中的更改（例如，“前往支持界面”）。
  • 本地设备数据：访问仅在 应用上下文中提供的信息（例如，“获取当前电池电量”）。
  • 私有 API：与只能从 客户端环境访问的服务集成。

示例

以下示例是一个会话响应，表明客户端应用应调用函数：

"outputs": [
  {
    "toolCalls": {
      "toolCalls": [
        {
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "args": {
            "zip_code": "92031"
          },
          "displayName": "get_nearest_store"
        }
      ]
    },
    "turnCompleted": true,
  }
]

以下示例是后续会话运行，其中工具输出附加到请求中。客户端应用必须填充这些字段，并放置与上一条消息中相同的 id、tool 和 display_name 值。

"inputs": [
  {
    "toolResponses": {
      "toolResponses": [
        {
          "displayName": "get_nearest_store",
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "response": {
            "name": "Alibaba",
            "address": "43 Alpha Road, Mountain View, CA 92039, USA"
          },
        }
      ]
    }
  }
]