建立 API 工具

API 工具用於整合外部服務、自動化操作流程。

快速建立 API 工具

1. 進入工具管理介面

首先，請從左側導航欄進入「 AI 功能」區塊，然後點擊「🔧 工具」。進入工具列表頁面後，點選右上角的「➕ 新增工具」按鈕。

2. 選擇工具類型

工具類型，選擇 API。

3. 設定顯示名稱

為工具設定清晰的顯示名稱，這邊設為 google calendar。

• 用途：此名稱將會顯示在平台介面中，供所有用戶查看。

• 建議：選擇一個能清晰表達工具主要功能的名稱，方便用戶理解。此名稱沒有嚴格的格式限制。

4. 設定工具名稱

接下來是「工具名稱」欄位。

• 用途：此名稱是 AI 助理在內部呼叫和識別此工具時使用的唯一標識符。

• 命名規則 (重要)：

  • 必須使用英文。

  • 只能包含：

    • 小寫英文字母 (a-z)

    • 大寫英文字母 (A-Z)

    • 數字 (0-9)

    • 底線 (_)

    • 連字符 (-)

  • 範例：get_weather_forecast, database-query-tool

下圖設為 google_calendar_retriever

5. 撰寫工具描述

在「工具描述」欄位中，用戶可以提供清晰且詳細的工具說明。

• 重要性：良好的描述能幫助 AI 助理更準確地理解：

  • 工具的功能和目的。

  • 何時應該使用這個工具。

  • 如何解釋工具的輸出結果。

• 建議內容：說明工具做什麼、輸入什麼、輸出什麼，以及任何使用上的注意事項。

6. API 配置詳細設定

a. 🔗 API URL

• 填寫目標 API 端點的完整網址 (包含 http:// 或 https://)。

• 範例：https://api.opencalendar.org/data/2.5

b. 📮 HTTP 方法

• 從下拉選單選擇 API 服務要求的 HTTP 動詞：

  • GET：通常用於獲取資源。

  • POST：通常用於創建新資源或提交數據。

  • PUT：通常用於完整替換或更新資源。

  • DELETE：通常用於刪除資源。

c. 📰 標頭 (Headers)

• 點擊「➕ 新增標頭」來定義隨請求發送的 HTTP 標頭。

• 格式：必須是有效的 JSON 物件，其中鍵 (Key) 是標頭名稱，值 (Value) 是標頭內容 (字串)。

• 常見用途：

  • 身份驗證 (Authorization, X-API-Key)

  • 指定內容類型 (Content-Type)

  • 指定接受的回應格式 (Accept)

• 範例：

  复制

  {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": "Bearer {{SECRET_API_TOKEN}}",
    "Accept": "application/vnd.github.v3+json"
  }

d. 🧩 參數結構 (Parameters Schema)

• 核心設定：定義 AI 助理在呼叫此工具時，可以或必須提供哪些參數，以及這些參數的格式。

• 格式：使用標準的 JSON Schema 格式。

• 關鍵元素：

  • type: "object"：表示參數是一個物件。

  • properties: 定義每個參數的物件。

    • 參數名稱 (例如 "search")：對應的物件包含該參數的細節。

      • type: 參數的資料類型 (string, integer, number, boolean, array, object)。

      • description: 對 AI 助理的說明，解釋此參數的意義。

      • default (可選): 參數的默認值。

      • enum (可選): 如果參數值只能是特定幾個選項之一，在此列出。

  • required: 一個包含所有必填參數名稱的陣列。

• 範例 (影音搜尋工具)：

  复制

  {
      "type": "object",
      "properties": {
          "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "回傳結果數量上限"
          },
          "fields": {
              "type": "string",
              "description": "以逗號分隔的欄位清單"
          },
          "search": {
              "type": "string",
              "description": "搜尋關鍵字"
          }
      },
      "required": ["search"]
  }

7. 💾 儲存工具

確認所有設定無誤後，捲動到頁面底部，點擊「確認」按鈕。您的新工具就建立完成了！

⚠️ 重要提醒

連線測試

• 建立工具後，建議先測試 API 是否正常運作

• 可使用測試工具驗證工具功能，如：

  • POSTMAN

  • 企業自己搭建的 API 測試請求平台

權限管理

• 定期檢查工具使用狀況及權限開放狀態

故障排除

• 如果連線失敗，請檢查錯誤代碼查看錯誤原因

• 確認標頭和參數結構符合要求