建立 API 工具

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

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

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

什麼是 API？

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

想像你在餐廳用餐：

你：需要食物的客戶（應用程式）
廚房：製作食物的地方（提供服務的系統）
服務員：在你和廚房之間傳遞訊息（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

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"
}

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"]
}