建立 API 工具

本指南將引導您在平台中建立新的 MCP 工具。

您可以使用 MaiAgent 製作的 工具製作 AI 助理 協助您建立 API 工具

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

什麼是 API？

API（Application Programming Interface，應用程式介面） 是不同軟體系統之間溝通的橋樑。簡單來說，它就像是軟體世界的「服務員」，幫助不同的程式互相傳遞資訊和執行功能。

想像你在餐廳用餐：

• 你：需要食物的客戶（應用程式）

• 廚房：製作食物的地方（提供服務的系統）

• 服務員：在你和廚房之間傳遞訊息（API）

你不需要直接進廚房，只要告訴服務員你要什麼，服務員會把你的需求傳達給廚房，然後把做好的餐點送到你面前。

API 流程示意圖

API 工具可以協助您自動操作標準化流程及設置特定的回傳格式，也可以協助您獲取您系統中的資訊如：

電商客服自動化

客戶詢問訂單 ➡️ API 查詢訂單狀態 ➡️ 自動回覆配送進度

行銷活動管理

新產品上架 ➡️ 自動更新官網 ➡️ 發送 EDM ➡️ 社群平台宣傳

線上課程平台：

學生詢問課程進度 ➡️ API 查詢學習紀錄 ➡️ 自動回覆完成百分比和下次上課時間

透過 API 工具，AI 助理從單純的對話機器人，進化成能夠實際執行業務流程的智慧助理，大幅提升工作效率和自動化程度。

快速建立 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

API 工具名稱定義

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)

標頭就像是信件的「信封」，在看到實際的資料內容前，先告訴接收方一些重要的資訊，沒有正確的標頭，API 請求可能無法通過驗證，或者接收方無法正確解析資料。。

常見用途：

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

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

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

若要新增標頭，您需要：

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

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

• 範例：

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

設定必要的 HTTP 請求標頭

d. 🧩 參數結構 (Parameters Schema)

參數結構就像是「點餐單」，告訴 AI 助理可以向 API 要求什麼資料，以及要怎麼要求。

• 核心設定：定義 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"]
  }

使用 JSON Schema 精確定義 API 參數

7. 💾 儲存工具

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

⚠️ 重要提醒

連線測試

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

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

  • POSTMAN

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

權限管理

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