自訂 API 工具
定義、測試、檢視、啟用及稽核聊天室層級、可供 AI 代理呼叫的 HTTP 工具。
POST
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}用途
為聊天室建立可由 AI 代理呼叫的 HTTP API 定義、輸入參數與回應擷取規則。
適用時機
當代理需要以受控參數呼叫外部庫存、CRM 或其他服務時使用。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 工具所屬的聊天室 UUID。 |
請求結構
CreateCustomApiToolPayload| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
description | string | 是 | Short one-liner for the agent |
headers | Record<string, string> | null | 否 | Custom HTTP headers, supports {{@param}} and {{sys_var}} templates |
json_body | object | null | 否 | JSON body template with {{@param}}, {{sys_var}}, and constants |
method | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | 是 | HTTP method |
name | string | 是 | Provider-safe tool name, unique per chatroom. Use only ASCII letters, numbers, underscores, and hyphens. |
parameters | CustomApiToolParameterPayload[] | null | 否 | Agent input parameter definitions |
query_params | object | null | 否 | Query param template with {{@param}}, {{sys_var}}, and constants |
response_description | string | null | 否 | Describes what the API response means and how to interpret it |
response_extract | string | null | 否 | JMESPath 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}' |
url | string | 是 | URL template, may contain system vars like {{chatroom_id}} |
usage_hint | string | null | 否 | Detailed guidance on when/how the agent should use this tool |
回應結構
CustomApiToolInfo| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
chatroom_id | string | 是 | 未指定 |
created_at | string (date-time) | 是 | 未指定 |
description | string | 是 | 未指定 |
enabled | boolean | 是 | 未指定 |
headers | Record<string, string> | null | 是 | 未指定 |
id | string | 是 | 未指定 |
json_body | object | null | 是 | 未指定 |
method | string | 是 | 未指定 |
name | string | 是 | 未指定 |
parameters | object[] | null | 是 | 未指定 |
query_params | object | null | 是 | 未指定 |
response_description | string | null | 是 | 未指定 |
response_extract | string | null | 是 | 未指定 |
updated_at | string (date-time) | 是 | 未指定 |
url | string | 是 | 未指定 |
usage_hint | string | null | 是 | 未指定 |
version | integer | 是 | 未指定 |
version_note | string | 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 驗證失敗。 | |
| 403 | 呼叫者不是聊天室建立者或管理者。 | |
GET
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}用途
列出聊天室全部工具定義、版本與 enabled 狀態。
適用時機
適合工具管理頁面、選取器或部署前盤點。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 要列出工具的聊天室 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 | 呼叫者不是聊天室建立者或管理者。 | |
GET
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}/logs用途
依新到舊列出代理實際呼叫外部 API 的解析後請求、回應、耗時與工具快照。
適用時機
排查外部呼叫、檢查延遲或稽核某個工具版本時使用。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}/logs
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 執行紀錄所屬的聊天室 UUID。 |
tool_id | query | uuid | 否 | 選填的工具定義 UUID 篩選。 |
limit | query | int 1..200 | 否 | 最多回傳幾筆紀錄,可填 1 到 200,預設為 50。 |
offset | query | int >= 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 | 呼叫者不是聊天室建立者或管理者。 | |
GET
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}/logs/{log_id}用途
取得一筆執行紀錄的完整解析請求、回應與凍結工具快照。
適用時機
從紀錄清單進入單次呼叫除錯或稽核畫面時使用。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}/logs/{log_id}
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 執行紀錄所屬的聊天室 UUID。 |
log_id | path | uuid | 是 | 執行紀錄 UUID。 |
回應結構
CustomApiToolExecutionLogInfo| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
assistant_message_id | string | null | 是 | 未指定 |
chatroom_id | string | 是 | 未指定 |
client_id | string | null | 是 | 未指定 |
created_at | string (date-time) | 是 | 未指定 |
duration_ms | integer | null | 是 | 未指定 |
error | string | null | 是 | 未指定 |
id | string | 是 | 未指定 |
method | string | 是 | 未指定 |
request_body | object | null | 是 | 未指定 |
request_headers | object | null | 是 | 未指定 |
response_body | unknown | null | 是 | 未指定 |
response_status | integer | null | 是 | 未指定 |
tool_definition_id | string | null | 是 | 未指定 |
tool_name | string | 是 | 未指定 |
tool_snapshot | object | 是 | 未指定 |
tool_version | integer | 是 | 未指定 |
url | string | 是 | 未指定 |
範例
取得單筆執行紀錄
請求
{
"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 | 紀錄不存在,或不屬於指定聊天室。 | |
POST
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/test用途
套用測試參數並實際呼叫外部 API,回傳解析後請求、原始回應與擷取結果。
適用時機
在啟用工具前驗證範本、參數與回應擷取,或除錯設定時使用。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/test
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 工具所屬的聊天室 UUID。 |
tool_id | path | uuid | 是 | 要測試的工具定義 UUID。 |
請求結構
TestCustomApiToolPayload| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
parameters | object | 否 | Parameter values for the test call, e.g. {"product_id": "abc"} |
回應結構
TestCustomApiToolResponse| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
duration_ms | integer | null | 是 | Round-trip time in milliseconds |
error | string | null | 是 | Error message for connection/timeout failures |
extracted_response | unknown | null | 是 | Response after JMESPath extraction (null if not configured or same as raw) |
resolved_body | object | null | 是 | JSON body after substitution |
resolved_headers | Record<string, string> | null | 是 | Headers sent (auth values masked) |
resolved_query_params | object | null | 是 | Query params after substitution |
resolved_url | string | 是 | URL after template substitution |
response_body | unknown | null | 是 | Full raw response from the external API |
response_status | integer | null | 是 | HTTP 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 | 提供的測試參數不符合工具定義。 | |
| 404 | 工具不存在,或不屬於指定聊天室。 | |
GET
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}用途
取得一個工具目前完整的參數、範本、版本與狀態。
適用時機
在編輯、測試或切換啟用狀態前載入完整工具定義,確認目前版本、請求設定與 enabled 狀態。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 工具所屬的聊天室 UUID。 |
tool_id | path | uuid | 是 | 工具定義 UUID。 |
回應結構
CustomApiToolInfo| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
chatroom_id | string | 是 | 未指定 |
created_at | string (date-time) | 是 | 未指定 |
description | string | 是 | 未指定 |
enabled | boolean | 是 | 未指定 |
headers | Record<string, string> | null | 是 | 未指定 |
id | string | 是 | 未指定 |
json_body | object | null | 是 | 未指定 |
method | string | 是 | 未指定 |
name | string | 是 | 未指定 |
parameters | object[] | null | 是 | 未指定 |
query_params | object | null | 是 | 未指定 |
response_description | string | null | 是 | 未指定 |
response_extract | string | null | 是 | 未指定 |
updated_at | string (date-time) | 是 | 未指定 |
url | string | 是 | 未指定 |
usage_hint | string | null | 是 | 未指定 |
version | integer | 是 | 未指定 |
version_note | string | 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 | 工具不存在,或不屬於指定聊天室。 | |
PATCH
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}用途
以 PATCH 合併更新工具定義、重新驗證完整設定,並自動遞增版本以保留變更脈絡。
適用時機
修改說明、端點、參數、範本或回應擷取設定時使用。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 工具所屬的聊天室 UUID。 |
tool_id | path | uuid | 是 | 要更新的工具定義 UUID。 |
請求結構
UpdateCustomApiToolPayload| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
description | string | null | 否 | Short description |
headers | Record<string, string> | null | 否 | Custom HTTP headers, supports {{@param}} and {{sys_var}} templates |
json_body | object | null | 否 | JSON body template |
method | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | null | 否 | HTTP method |
name | string | null | 否 | Provider-safe tool name. Use only ASCII letters, numbers, underscores, and hyphens. |
parameters | CustomApiToolParameterPayload[] | null | 否 | Parameter definitions |
query_params | object | null | 否 | Query param template |
response_description | string | null | 否 | Response interpretation guide |
response_extract | string | null | 否 | JMESPath expression for response extraction |
url | string | null | 否 | URL template |
usage_hint | string | null | 否 | Usage guidance for the agent |
version_note | string | null | 否 | Changelog note for this version |
回應結構
CustomApiToolInfo| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
chatroom_id | string | 是 | 未指定 |
created_at | string (date-time) | 是 | 未指定 |
description | string | 是 | 未指定 |
enabled | boolean | 是 | 未指定 |
headers | Record<string, string> | null | 是 | 未指定 |
id | string | 是 | 未指定 |
json_body | object | null | 是 | 未指定 |
method | string | 是 | 未指定 |
name | string | 是 | 未指定 |
parameters | object[] | null | 是 | 未指定 |
query_params | object | null | 是 | 未指定 |
response_description | string | null | 是 | 未指定 |
response_extract | string | null | 是 | 未指定 |
updated_at | string (date-time) | 是 | 未指定 |
url | string | 是 | 未指定 |
usage_hint | string | null | 是 | 未指定 |
version | integer | 是 | 未指定 |
version_note | string | 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 | 新名稱衝突,或合併後的參數與範本互相不一致。 | |
| 404 | 工具不存在,或不屬於指定聊天室。 | |
DELETE
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}用途
永久移除工具定義,使代理無法再呼叫;既有執行紀錄仍保留當時的工具快照供稽核。
適用時機
工具已淘汰且不應再被代理呼叫時刪除;若只是暫停使用,應切換 enabled 狀態以便日後恢復。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 工具所屬的聊天室 UUID。 |
tool_id | path | uuid | 是 | 要刪除的工具定義 UUID。 |
回應結構
SuccessResponse| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
message | string | 否 | 未指定 |
範例
刪除指定工具
請求
{
"pathParams": {
"chatroom_id": "11111111-1111-4111-8111-111111111111",
"tool_id": "22222222-2222-4222-8222-222222222222"
}
}回應200
{
"message": "Tool deleted successfully"
}錯誤
| 狀態 | 發生條件 | 錯誤本文 |
|---|---|---|
| 404 | 工具不存在,或不屬於指定聊天室。 | |
PATCH
路由範本
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/enabled用途
控制 AI 代理是否把這個工具載入可用工具集。
適用時機
暫停有問題的工具,或在驗證完成後重新啟用時使用。
實際掛載路徑
- 完整路由
/private/chatrooms/custom_api_tools/{chatroom_id}/{tool_id}/enabled
範圍
| 範圍 | 是否提供 | 驗證與權限 |
|---|---|---|
| 完整路由 | 可使用 | ChatRoomAccessRequired |
參數
| 欄位 | 位置 | 型別 | 必填 | 說明 |
|---|---|---|---|---|
chatroom_id | path | uuid | 是 | 工具所屬的聊天室 UUID。 |
tool_id | path | uuid | 是 | 要切換的工具定義 UUID。 |
請求結構
ToggleEnabledPayload| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
enabled | boolean | 是 | Toggle tool availability for the AI agent |
回應結構
CustomApiToolInfo| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
chatroom_id | string | 是 | 未指定 |
created_at | string (date-time) | 是 | 未指定 |
description | string | 是 | 未指定 |
enabled | boolean | 是 | 未指定 |
headers | Record<string, string> | null | 是 | 未指定 |
id | string | 是 | 未指定 |
json_body | object | null | 是 | 未指定 |
method | string | 是 | 未指定 |
name | string | 是 | 未指定 |
parameters | object[] | null | 是 | 未指定 |
query_params | object | null | 是 | 未指定 |
response_description | string | null | 是 | 未指定 |
response_extract | string | null | 是 | 未指定 |
updated_at | string (date-time) | 是 | 未指定 |
url | string | 是 | 未指定 |
usage_hint | string | null | 是 | 未指定 |
version | integer | 是 | 未指定 |
version_note | string | 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 | 工具不存在,或不屬於指定聊天室。 | |
Last updated on