文件

自訂 API

從你的代理程式呼叫外部 API，擷取資料或觸發整合功能。

自訂 API 動作可讓你的代理程式與外部服務互動。擷取即時資料、送出表單，或在其他工具中觸發工作流程。

建立自訂 API 動作

  1. 前往你代理程式的動作分頁
  2. 點選新增動作 → 自訂 API
  3. 設定 API 呼叫：
    • 端點網址：要呼叫的 API 端點
    • HTTP 方法：GET、POST、PUT、PATCH 或 DELETE
    • 標頭：驗證資訊與內容類型
    • 請求主體：要傳送的資料（適用於 POST／PUT／PATCH）
  4. 儲存並測試

設定選項

端點網址

API 端點的完整網址：

https://api.yourservice.com/v1/data

僅限使用 HTTPS 端點，HTTP 端點基於安全考量會被封鎖。

HTTP 方法

方法使用情境
GET從外部服務擷取資料
POST傳送資料、建立記錄
PUT取代現有記錄
PATCH局部更新現有記錄
DELETE刪除記錄

標頭

新增驗證與內容標頭：

Authorization: Bearer {{SECRET:service_api_key}}
Content-Type: application/json

請另外建立具名密鑰。Agentkit 只會在伺服器上解析 {{SECRET:name}}。讀取動作與記錄時都不會包含儲存的值。

輸入資料來源

對於包含單一電子郵件地址的文字欄位，請選擇已驗證電子郵件，無法取得時再詢問。Agentkit 會使用已驗證的網站聯絡人地址或來信寄件者地址。匿名訪客會被要求提供地址。模型無法取代已驗證的地址。

請求主體

POST／PUT 請求可定義要傳送的 JSON 主體資料。

API 何時會被呼叫

AI 會根據對話情境與動作說明，決定何時呼叫 API。你可以透過清楚描述動作的觸發時機，引導這項行為。

處理回應

成功回應

當 API 回傳成功（2xx 狀態碼）時：

  • 向訪客顯示成功訊息
  • 在聊天中納入回應資料
  • 觸發後續動作

錯誤處理

當 API 呼叫失敗時：

  • 顯示友善的錯誤訊息
  • 記錄錯誤以供除錯
  • 可選擇重試該請求

使用情境範例

查詢訂單狀態

設定 GET 端點，在訪客詢問訂單狀態時擷取訂單資料。

送出至 CRM

設定 POST 端點，將潛在客戶資料送進你的 CRM 系統。

取得即時資料

設定 GET 端點，從你的系統擷取即時資料（例如庫存或可預約狀態）。

安全性考量

API 金鑰

  • 將 API 金鑰儲存為具名密鑰，並使用 {{SECRET:name}} 參照。
  • 測試時使用特定環境的金鑰
  • 定期輪換金鑰

速率限制

  • 外部 API 可能有速率限制
  • 依此調整你代理程式的速率限制設定
  • 在日誌中監控 API 使用量

資料隱私

  • 只傳送必要的資料
  • 如有需要，確認外部服務符合 GDPR 規範
  • 不要在日誌中記錄敏感的回應資料

逾時與重試

設定預設值說明
逾時20 秒若無回應，請求會失敗
重試0如需可靠傳遞，請改用 Webhook 重試機制

測試你的 API 動作

  1. 使用測試端點設定動作
  2. 前往 Playground
  3. 用適當的輸入觸發此動作
  4. 在聊天中確認回應
  5. 查看日誌以進行除錯

後續步驟