客户端函数工具

如果您有客户端代码可访问但托管工具（例如 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"
          },
        }
      ]
    }
  }
]