# 工具功能概覽

## 什麼是工具？

工具就像是 AI 助理的**外掛**或**技能**，讓它不只能聊天，還能做更多事情。例如，如果 AI 助理有「**查詢天氣」**這個工具，它就能告訴你今天的氣溫；如果它有「**播放音樂」**這個工具，就能直接幫你打開音樂。

透過讓用戶定義一組可供 AI 助理使用的「工具」，AI 助理能夠：

1. 理解使用者的複雜請求。
2. 自動地判斷何時需要使用特定的工具。
3. 自動生成呼叫該工具所需的參數。

這使得 AI 助理不再僅限於生成文本回覆，更能實際執行多樣化的任務，例如：

* **查詢即時資訊：** 從資料庫或 API 獲取最新股價、天氣預報、航班狀態等。
* **執行外部操作：** 呼叫訂票系統 API、控制智慧家居設備、發送電子郵件或訊息。
* **處理檔案：** 讀取、寫入或分析本地或雲端文件。
* **與其他軟體整合：** 操作 CRM 系統、專案管理工具或其他企業應用程式。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8f3d6d27da284a96c617de72543b43845da9c2b3%2F%E6%88%AA%E5%9C%96%202025-05-03%20%E4%B8%8B%E5%8D%885.28.29.png?alt=media" alt=""><figcaption></figcaption></figure>

## 工具的運作流程

一個基本的工具呼叫流程包含以下步驟：

1. **定義工具：**
   * 用戶需先定義好工具的相關參數。
   * 爲 AI 助理設定可以使用的工具項目。
   * 每個工具必須包含：
     * 清晰的**名稱** (Name)。
     * 易於理解的**描述** (Description)，說明工具的用途。
     * 詳細的**參數說明** (Parameters)，包含每個參數的名稱、資料類型、是否為必填項等。
2. **使用者提問：**
   * 使用者以自然語言向 AI 助理提出請求。
   * *範例：* 「幫我查一下明天台北的天氣。」
3. **模型思考與選擇工具：**
   * AI 助理內部的 LLM 分析使用者請求的意圖。
   * 模型從可用的工具列表中，判斷是否需要以及需要使用哪個工具來回應請求。
   * *範例：* 模型判斷需要天氣資訊，選擇了名為 `get_weather` 的工具。
4. **生成工具呼叫參數：**

   * 模型生成一個結構化的輸出 (通常是 JSON 格式)，包含要呼叫的工具名稱及其所需參數。
   * *範例：*

   ```json
   {
     "name": "get_weather",
     "arguments": {
       "city": "台北",
       "date": "明天"
     }
   }
   ```
5. **應用程式執行工具：**
   * AI 助理的後端應用程式接收並解析模型生成的 JSON 指令。
   * 應用程式根據指令中的工具名稱和參數，實際執行相應的函數或呼叫外部 API。
   * *範例：* 後端程式呼叫天氣查詢 API，傳入「台北」和「明天」作為參數。
6. **將結果回傳給模型：**

   * 應用程式將執行工具後得到的結果 (通常也是 JSON 格式) 回傳給 AI 助理的模型。
   * *範例：*

   ```json
   {
     "temperature": "25°C",
     "condition": "晴天"
   }
   ```
7. **模型生成最終回覆：**
   * 模型接收工具執行的結果，並將其整合進最終的自然語言回覆中。
   * *範例：* 「明天台北的天氣預計是晴天，氣溫約為 25°C。」

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-65a942b2242bee96b93252c0796a83a2eb842bc9%2F%E6%88%AA%E5%9C%96%202025-05-03%20%E4%B8%8B%E5%8D%885.03.42.png?alt=media" alt=""><figcaption></figcaption></figure>

## 工具的主要優勢

* **擴展 AI 助理能力：** 打破僅限於生成文本的限制，讓 AI 助理能夠存取即時資訊、執行現實世界的任務。
* **提高可靠性與精確度：** 透過結構化的呼叫與回傳，確保任務指令清晰明確，降低模型「幻覺」或操作錯誤的風險。
* **實現複雜的自動化流程：** 能夠設計出可自主完成多步驟、跨系統任務的 AI 助理，大幅提升效率 (例如：自動規劃旅遊行程並預訂機票酒店)。
* **更自然的互動體驗：** 使用者只需用自然語言描述需求，AI 助理即可理解並轉化為精確的系統操作。

## MaiAgent 支援工具類型

目前支援以下主要類型：

### 🌐 API 工具

* **最常用類型**。用於連接和呼叫外部的 HTTP/HTTPS API 服務。
* **常見應用**：獲取天氣資訊、查詢外部資料庫、觸發 webhook、與第三方服務整合等。
* **必要配置**：API 端點 URL、HTTP 方法、請求標頭 (Headers)、參數結構 (Parameters Schema)。

### ☁️ MCP 工具

* **模型上下文協定**（Model Context Protocol, MCP）,透過標準化協定實現伺服器、用戶端與主機的協作。
* **適用場景**：讓 AI 助理調用外部工具執行更複雜和實用的任務。
* **必要配置**：MCP 伺服器 URL、參數、環境變數等。