用戶端功能工具

如果用戶端程式碼可存取某項功能，但託管工具無法存取，例如 OpenAPI 或 MCP，您可以使用用戶端函式工具。用戶端函式工具一律在用戶端執行，而非由代理程式執行。

運作方式

當代理觸發用戶端函式工具時：

  1. 工作階段封鎖：對話工作階段會在伺服器端「封鎖」。
  2. 用戶端執行：用戶端應用程式必須識別工具呼叫，並在本機環境中執行對應的邏輯。
  3. 提供回應：執行完成後，用戶端應用程式必須使用 toolResponses 欄位將回應傳回給代理程式。

服務專員會等待這項回覆，再繼續對話。

設定

建立用戶端函式工具時，請定義代理程式瞭解及與用戶端程式碼互動的方式：

  • 名稱：工具的專屬 ID (例如：open_settings)。
  • 說明：簡要說明工具的用途。代理程式模型會根據這項說明，判斷何時呼叫函式。
  • 輸入/輸出結構定義：以 OpenAPI 格式定義。這會決定代理程式傳送及預期接收的資料結構。

用途

用戶端函式工具適合用於：

  • UI/UX 動作：觸發應用程式介面中的變更 (例如「前往支援畫面」)。
  • 本機裝置資料：存取僅在應用程式環境中可用的資訊 (例如「取得目前的電池電量」)。
  • 私有 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"
          },
        }
      ]
    }
  }
]