Skip to Content
API 參考自訂 API 工具

自訂 API 工具

定義、測試、檢視、啟用及稽核聊天室層級、可供 AI 代理呼叫的 HTTP 工具。

POST
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}

建立自訂 API 工具

用途

為聊天室建立可由 AI 代理呼叫的 HTTP API 定義、輸入參數與回應擷取規則。

適用時機

當代理需要以受控參數呼叫外部庫存、CRM 或其他服務時使用。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid工具所屬的聊天室 UUID。

請求結構

CreateCustomApiToolPayload
欄位型別必填說明
descriptionstringShort one-liner for the agent
headersRecord<string, string> | nullCustom HTTP headers, supports {{@param}} and {{sys_var}} templates
json_bodyobject | nullJSON body template with {{@param}}, {{sys_var}}, and constants
method"GET" | "POST" | "PUT" | "PATCH" | "DELETE"HTTP method
namestringProvider-safe tool name, unique per chatroom. Use only ASCII letters, numbers, underscores, and hyphens.
parametersCustomApiToolParameterPayload[] | nullAgent input parameter definitions
query_paramsobject | nullQuery param template with {{@param}}, {{sys_var}}, and constants
response_descriptionstring | nullDescribes what the API response means and how to interpret it
response_extractstring | nullJMESPath expression to extract relevant fields from the API response. If set, only the extracted result is passed to the agent. Full response is still logged. Example: 'results[*].{name: product_name, price: unit_price}'
urlstringURL template, may contain system vars like {{chatroom_id}}
usage_hintstring | nullDetailed guidance on when/how the agent should use this tool

回應結構

CustomApiToolInfo
欄位型別必填說明
chatroom_idstring未指定
created_atstring (date-time)未指定
descriptionstring未指定
enabledboolean未指定
headersRecord<string, string> | null未指定
idstring未指定
json_bodyobject | null未指定
methodstring未指定
namestring未指定
parametersobject[] | null未指定
query_paramsobject | null未指定
response_descriptionstring | null未指定
response_extractstring | null未指定
updated_atstring (date-time)未指定
urlstring未指定
usage_hintstring | null未指定
versioninteger未指定
version_notestring | null未指定

範例

建立庫存查詢工具

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "body": {
    "name": "check_inventory",
    "description": "查詢倉庫庫存",
    "usage_hint": "客戶詢問商品是否有庫存時使用。",
    "response_description": "quantity 是可出貨數量。",
    "method": "GET",
    "url": "https://inventory.example.com/items/{{@sku}}",
    "parameters": [
      {
        "name": "sku",
        "type": "string",
        "description": "要查詢的商品編號",
        "required": true,
        "default": null,
        "options": null,
        "min": null,
        "max": null,
        "pattern": "^[A-Z0-9-]+$"
      }
    ],
    "query_params": {
      "source": "teamsync"
    },
    "response_extract": "{sku: sku, quantity: quantity}"
  }
}
回應200
{
  "id": "22222222-2222-4222-8222-222222222222",
  "chatroom_id": "11111111-1111-4111-8111-111111111111",
  "name": "check_inventory",
  "description": "查詢倉庫庫存",
  "usage_hint": "客戶詢問商品是否有庫存時使用。",
  "response_description": "quantity 是可出貨數量。",
  "method": "GET",
  "url": "https://inventory.example.com/items/{{@sku}}",
  "headers": null,
  "parameters": [
    {
      "name": "sku",
      "type": "string",
      "description": "要查詢的商品編號",
      "required": true,
      "default": null,
      "options": null,
      "min": null,
      "max": null,
      "pattern": "^[A-Z0-9-]+$"
    }
  ],
  "query_params": {
    "source": "teamsync"
  },
  "json_body": null,
  "response_extract": "{sku: sku, quantity: quantity}",
  "enabled": true,
  "version": 1,
  "version_note": null,
  "created_at": "2026-07-19T03:00:00",
  "updated_at": "2026-07-19T03:05:00"
}

錯誤

狀態發生條件錯誤本文
400同一聊天室已有同名工具,或參數、範本及 JMESPath 驗證失敗。
{
  "detail": "Tool name 'check_inventory' already exists in this chatroom"
}
403呼叫者不是聊天室建立者或管理者。
{
  "detail": "Insufficient permissions, not the creator. (Required department manager)"
}
GET
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}

列出自訂 API 工具

用途

列出聊天室全部工具定義、版本與 enabled 狀態。

適用時機

適合工具管理頁面、選取器或部署前盤點。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid要列出工具的聊天室 UUID。

回應結構

List[CustomApiToolInfo]

OpenAPI 快照中沒有此模型的頂層元件欄位。

範例

列出聊天室工具

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  }
}
回應200
[
  {
    "id": "22222222-2222-4222-8222-222222222222",
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "name": "check_inventory",
    "description": "查詢倉庫庫存",
    "usage_hint": "客戶詢問商品是否有庫存時使用。",
    "response_description": "quantity 是可出貨數量。",
    "method": "GET",
    "url": "https://inventory.example.com/items/{{@sku}}",
    "headers": null,
    "parameters": [
      {
        "name": "sku",
        "type": "string",
        "description": "要查詢的商品編號",
        "required": true,
        "default": null,
        "options": null,
        "min": null,
        "max": null,
        "pattern": "^[A-Z0-9-]+$"
      }
    ],
    "query_params": {
      "source": "teamsync"
    },
    "json_body": null,
    "response_extract": "{sku: sku, quantity: quantity}",
    "enabled": true,
    "version": 1,
    "version_note": null,
    "created_at": "2026-07-19T03:00:00",
    "updated_at": "2026-07-19T03:05:00"
  }
]

錯誤

狀態發生條件錯誤本文
403呼叫者不是聊天室建立者或管理者。
{
  "detail": "Insufficient permissions, not the creator. (Required department manager)"
}
GET
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}/logs
用途

依新到舊列出代理實際呼叫外部 API 的解析後請求、回應、耗時與工具快照。

適用時機

排查外部呼叫、檢查延遲或稽核某個工具版本時使用。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}/logs

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid執行紀錄所屬的聊天室 UUID。
tool_idqueryuuid選填的工具定義 UUID 篩選。
limitqueryint 1..200最多回傳幾筆紀錄,可填 1 到 200,預設為 50。
offsetqueryint >= 0略過前幾筆紀錄,預設為 0。

回應結構

List[CustomApiToolExecutionLogInfo]

OpenAPI 快照中沒有此模型的頂層元件欄位。

範例

列出指定工具的執行紀錄

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "query": {
    "tool_id": "22222222-2222-4222-8222-222222222222",
    "limit": "50",
    "offset": "0"
  }
}
回應200
[
  {
    "id": "33333333-3333-4333-8333-333333333333",
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tool_definition_id": "22222222-2222-4222-8222-222222222222",
    "tool_name": "check_inventory",
    "assistant_message_id": null,
    "tool_version": 1,
    "tool_snapshot": {
      "name": "check_inventory",
      "method": "GET",
      "url": "https://inventory.example.com/items/{{@sku}}",
      "parameters": [
        {
          "name": "sku",
          "type": "string",
          "description": "要查詢的商品編號",
          "required": true,
          "default": null,
          "options": null,
          "min": null,
          "max": null,
          "pattern": "^[A-Z0-9-]+$"
        }
      ]
    },
    "method": "GET",
    "url": "https://inventory.example.com/items/SKU-100",
    "request_headers": null,
    "request_body": null,
    "response_status": 200,
    "response_body": {
      "sku": "SKU-100",
      "quantity": 12
    },
    "duration_ms": 86,
    "error": null,
    "client_id": null,
    "created_at": "2026-07-19T03:00:00"
  }
]

錯誤

狀態發生條件錯誤本文
403呼叫者不是聊天室建立者或管理者。
{
  "detail": "Insufficient permissions, not the creator. (Required department manager)"
}
GET
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}/logs/{log_id}
用途

取得一筆執行紀錄的完整解析請求、回應與凍結工具快照。

適用時機

從紀錄清單進入單次呼叫除錯或稽核畫面時使用。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}/logs/{log_id}

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid執行紀錄所屬的聊天室 UUID。
log_idpathuuid執行紀錄 UUID。

回應結構

CustomApiToolExecutionLogInfo
欄位型別必填說明
assistant_message_idstring | null未指定
chatroom_idstring未指定
client_idstring | null未指定
created_atstring (date-time)未指定
duration_msinteger | null未指定
errorstring | null未指定
idstring未指定
methodstring未指定
request_bodyobject | null未指定
request_headersobject | null未指定
response_bodyunknown | null未指定
response_statusinteger | null未指定
tool_definition_idstring | null未指定
tool_namestring未指定
tool_snapshotobject未指定
tool_versioninteger未指定
urlstring未指定

範例

取得單筆執行紀錄

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "log_id": "33333333-3333-4333-8333-333333333333"
  }
}
回應200
{
  "id": "33333333-3333-4333-8333-333333333333",
  "chatroom_id": "11111111-1111-4111-8111-111111111111",
  "tool_definition_id": "22222222-2222-4222-8222-222222222222",
  "tool_name": "check_inventory",
  "assistant_message_id": null,
  "tool_version": 1,
  "tool_snapshot": {
    "name": "check_inventory",
    "method": "GET",
    "url": "https://inventory.example.com/items/{{@sku}}",
    "parameters": [
      {
        "name": "sku",
        "type": "string",
        "description": "要查詢的商品編號",
        "required": true,
        "default": null,
        "options": null,
        "min": null,
        "max": null,
        "pattern": "^[A-Z0-9-]+$"
      }
    ]
  },
  "method": "GET",
  "url": "https://inventory.example.com/items/SKU-100",
  "request_headers": null,
  "request_body": null,
  "response_status": 200,
  "response_body": {
    "sku": "SKU-100",
    "quantity": 12
  },
  "duration_ms": 86,
  "error": null,
  "client_id": null,
  "created_at": "2026-07-19T03:00:00"
}

錯誤

狀態發生條件錯誤本文
404紀錄不存在,或不屬於指定聊天室。
{
  "detail": "Execution log not found"
}
POST
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/test

測試自訂 API 工具

用途

套用測試參數並實際呼叫外部 API,回傳解析後請求、原始回應與擷取結果。

適用時機

在啟用工具前驗證範本、參數與回應擷取,或除錯設定時使用。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/test

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid工具所屬的聊天室 UUID。
tool_idpathuuid要測試的工具定義 UUID。

請求結構

TestCustomApiToolPayload
欄位型別必填說明
parametersobjectParameter values for the test call, e.g. {"product_id": "abc"}

回應結構

TestCustomApiToolResponse
欄位型別必填說明
duration_msinteger | nullRound-trip time in milliseconds
errorstring | nullError message for connection/timeout failures
extracted_responseunknown | nullResponse after JMESPath extraction (null if not configured or same as raw)
resolved_bodyobject | nullJSON body after substitution
resolved_headersRecord<string, string> | nullHeaders sent (auth values masked)
resolved_query_paramsobject | nullQuery params after substitution
resolved_urlstringURL after template substitution
response_bodyunknown | nullFull raw response from the external API
response_statusinteger | nullHTTP status code (null if connection failed)

範例

測試庫存查詢工具

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tool_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "parameters": {
      "sku": "SKU-100"
    }
  }
}
回應200
{
  "resolved_url": "https://inventory.example.com/items/SKU-100",
  "resolved_query_params": {
    "source": "teamsync"
  },
  "resolved_body": null,
  "resolved_headers": null,
  "response_status": 200,
  "response_body": {
    "sku": "SKU-100",
    "quantity": 12
  },
  "extracted_response": {
    "sku": "SKU-100",
    "quantity": 12
  },
  "duration_ms": 86,
  "error": null
}

錯誤

狀態發生條件錯誤本文
400提供的測試參數不符合工具定義。
{
  "detail": "Parameter validation failed: 1 validation error for check_inventory_Input\nsku\n  Field required [type=missing, input_value={}, input_type=dict]\n    For further information visit https://errors.pydantic.dev/2.12/v/missing"
}
404工具不存在,或不屬於指定聊天室。
{
  "detail": "Tool not found"
}
GET
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}

取得自訂 API 工具

用途

取得一個工具目前完整的參數、範本、版本與狀態。

適用時機

在編輯、測試或切換啟用狀態前載入完整工具定義,確認目前版本、請求設定與 enabled 狀態。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid工具所屬的聊天室 UUID。
tool_idpathuuid工具定義 UUID。

回應結構

CustomApiToolInfo
欄位型別必填說明
chatroom_idstring未指定
created_atstring (date-time)未指定
descriptionstring未指定
enabledboolean未指定
headersRecord<string, string> | null未指定
idstring未指定
json_bodyobject | null未指定
methodstring未指定
namestring未指定
parametersobject[] | null未指定
query_paramsobject | null未指定
response_descriptionstring | null未指定
response_extractstring | null未指定
updated_atstring (date-time)未指定
urlstring未指定
usage_hintstring | null未指定
versioninteger未指定
version_notestring | null未指定

範例

取得庫存查詢工具

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tool_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "id": "22222222-2222-4222-8222-222222222222",
  "chatroom_id": "11111111-1111-4111-8111-111111111111",
  "name": "check_inventory",
  "description": "查詢倉庫庫存",
  "usage_hint": "客戶詢問商品是否有庫存時使用。",
  "response_description": "quantity 是可出貨數量。",
  "method": "GET",
  "url": "https://inventory.example.com/items/{{@sku}}",
  "headers": null,
  "parameters": [
    {
      "name": "sku",
      "type": "string",
      "description": "要查詢的商品編號",
      "required": true,
      "default": null,
      "options": null,
      "min": null,
      "max": null,
      "pattern": "^[A-Z0-9-]+$"
    }
  ],
  "query_params": {
    "source": "teamsync"
  },
  "json_body": null,
  "response_extract": "{sku: sku, quantity: quantity}",
  "enabled": true,
  "version": 1,
  "version_note": null,
  "created_at": "2026-07-19T03:00:00",
  "updated_at": "2026-07-19T03:05:00"
}

錯誤

狀態發生條件錯誤本文
404工具不存在,或不屬於指定聊天室。
{
  "detail": "Tool not found"
}
PATCH
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}

更新自訂 API 工具

用途

以 PATCH 合併更新工具定義、重新驗證完整設定,並自動遞增版本以保留變更脈絡。

適用時機

修改說明、端點、參數、範本或回應擷取設定時使用。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid工具所屬的聊天室 UUID。
tool_idpathuuid要更新的工具定義 UUID。

請求結構

UpdateCustomApiToolPayload
欄位型別必填說明
descriptionstring | nullShort description
headersRecord<string, string> | nullCustom HTTP headers, supports {{@param}} and {{sys_var}} templates
json_bodyobject | nullJSON body template
method"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | nullHTTP method
namestring | nullProvider-safe tool name. Use only ASCII letters, numbers, underscores, and hyphens.
parametersCustomApiToolParameterPayload[] | nullParameter definitions
query_paramsobject | nullQuery param template
response_descriptionstring | nullResponse interpretation guide
response_extractstring | nullJMESPath expression for response extraction
urlstring | nullURL template
usage_hintstring | nullUsage guidance for the agent
version_notestring | nullChangelog note for this version

回應結構

CustomApiToolInfo
欄位型別必填說明
chatroom_idstring未指定
created_atstring (date-time)未指定
descriptionstring未指定
enabledboolean未指定
headersRecord<string, string> | null未指定
idstring未指定
json_bodyobject | null未指定
methodstring未指定
namestring未指定
parametersobject[] | null未指定
query_paramsobject | null未指定
response_descriptionstring | null未指定
response_extractstring | null未指定
updated_atstring (date-time)未指定
urlstring未指定
usage_hintstring | null未指定
versioninteger未指定
version_notestring | null未指定

範例

更新工具說明並記錄版本備註

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tool_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "description": "查詢即時倉庫庫存",
    "version_note": "Clarify freshness"
  }
}
回應200
{
  "id": "22222222-2222-4222-8222-222222222222",
  "chatroom_id": "11111111-1111-4111-8111-111111111111",
  "name": "check_inventory",
  "description": "查詢即時倉庫庫存",
  "usage_hint": "客戶詢問商品是否有庫存時使用。",
  "response_description": "quantity 是可出貨數量。",
  "method": "GET",
  "url": "https://inventory.example.com/items/{{@sku}}",
  "headers": null,
  "parameters": [
    {
      "name": "sku",
      "type": "string",
      "description": "要查詢的商品編號",
      "required": true,
      "default": null,
      "options": null,
      "min": null,
      "max": null,
      "pattern": "^[A-Z0-9-]+$"
    }
  ],
  "query_params": {
    "source": "teamsync"
  },
  "json_body": null,
  "response_extract": "{sku: sku, quantity: quantity}",
  "enabled": true,
  "version": 2,
  "version_note": "Clarify freshness",
  "created_at": "2026-07-19T03:00:00",
  "updated_at": "2026-07-19T03:05:00"
}

錯誤

狀態發生條件錯誤本文
400新名稱衝突,或合併後的參數與範本互相不一致。
{
  "detail": "Tool name 'check_inventory' already exists in this chatroom"
}
404工具不存在,或不屬於指定聊天室。
{
  "detail": "Tool not found"
}
DELETE
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}

刪除自訂 API 工具

用途

永久移除工具定義,使代理無法再呼叫;既有執行紀錄仍保留當時的工具快照供稽核。

適用時機

工具已淘汰且不應再被代理呼叫時刪除;若只是暫停使用,應切換 enabled 狀態以便日後恢復。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid工具所屬的聊天室 UUID。
tool_idpathuuid要刪除的工具定義 UUID。

回應結構

SuccessResponse
欄位型別必填說明
messagestring未指定

範例

刪除指定工具

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tool_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "message": "Tool deleted successfully"
}

錯誤

狀態發生條件錯誤本文
404工具不存在,或不屬於指定聊天室。
{
  "detail": "Tool not found"
}
PATCH
路由範本/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/enabled
用途

控制 AI 代理是否把這個工具載入可用工具集。

適用時機

暫停有問題的工具,或在驗證完成後重新啟用時使用。

實際掛載路徑
  • 完整路由/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/enabled

範圍

範圍是否提供驗證與權限
完整路由可使用ChatRoomAccessRequired

參數

欄位位置型別必填說明
chatroom_idpathuuid工具所屬的聊天室 UUID。
tool_idpathuuid要切換的工具定義 UUID。

請求結構

ToggleEnabledPayload
欄位型別必填說明
enabledbooleanToggle tool availability for the AI agent

回應結構

CustomApiToolInfo
欄位型別必填說明
chatroom_idstring未指定
created_atstring (date-time)未指定
descriptionstring未指定
enabledboolean未指定
headersRecord<string, string> | null未指定
idstring未指定
json_bodyobject | null未指定
methodstring未指定
namestring未指定
parametersobject[] | null未指定
query_paramsobject | null未指定
response_descriptionstring | null未指定
response_extractstring | null未指定
updated_atstring (date-time)未指定
urlstring未指定
usage_hintstring | null未指定
versioninteger未指定
version_notestring | null未指定

範例

停用庫存查詢工具

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "tool_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "enabled": false
  }
}
回應200
{
  "id": "22222222-2222-4222-8222-222222222222",
  "chatroom_id": "11111111-1111-4111-8111-111111111111",
  "name": "check_inventory",
  "description": "查詢倉庫庫存",
  "usage_hint": "客戶詢問商品是否有庫存時使用。",
  "response_description": "quantity 是可出貨數量。",
  "method": "GET",
  "url": "https://inventory.example.com/items/{{@sku}}",
  "headers": null,
  "parameters": [
    {
      "name": "sku",
      "type": "string",
      "description": "要查詢的商品編號",
      "required": true,
      "default": null,
      "options": null,
      "min": null,
      "max": null,
      "pattern": "^[A-Z0-9-]+$"
    }
  ],
  "query_params": {
    "source": "teamsync"
  },
  "json_body": null,
  "response_extract": "{sku: sku, quantity: quantity}",
  "enabled": false,
  "version": 1,
  "version_note": null,
  "created_at": "2026-07-19T03:00:00",
  "updated_at": "2026-07-19T03:05:00"
}

錯誤

狀態發生條件錯誤本文
404工具不存在,或不屬於指定聊天室。
{
  "detail": "Tool not found"
}
Last updated on