# 工具功能概覽
## 什麼是工具？
工具就像是 AI 助理的**外掛**或**技能**，讓它不只能聊天，還能做更多事情。例如，如果 AI 助理有「**查詢天氣」**這個工具，它就能告訴你今天的氣溫；如果它有「**播放音樂」**這個工具，就能直接幫你打開音樂。
透過讓用戶定義一組可供 AI 助理使用的「工具」，AI 助理能夠：
1. 理解使用者的複雜請求。
2. 自動地判斷何時需要使用特定的工具。
3. 自動生成呼叫該工具所需的參數。
這使得 AI 助理不再僅限於生成文本回覆，更能實際執行多樣化的任務，例如：
* **查詢即時資訊：** 從資料庫或 API 獲取最新股價、天氣預報、航班狀態等。
* **執行外部操作：** 呼叫訂票系統 API、控制智慧家居設備、發送電子郵件或訊息。
* **處理檔案：** 讀取、寫入或分析本地或雲端文件。
* **與其他軟體整合：** 操作 CRM 系統、專案管理工具或其他企業應用程式。
## 工具的運作流程
一個基本的工具呼叫流程包含以下步驟：
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。」
## 工具的主要優勢
* **擴展 AI 助理能力：** 打破僅限於生成文本的限制，讓 AI 助理能夠存取即時資訊、執行現實世界的任務。
* **提高可靠性與精確度：** 透過結構化的呼叫與回傳，確保任務指令清晰明確，降低模型「幻覺」或操作錯誤的風險。
* **實現複雜的自動化流程：** 能夠設計出可自主完成多步驟、跨系統任務的 AI 助理，大幅提升效率 (例如：自動規劃旅遊行程並預訂機票酒店)。
* **更自然的互動體驗：** 使用者只需用自然語言描述需求，AI 助理即可理解並轉化為精確的系統操作。
## MaiAgent 支援工具類型
目前支援以下主要類型：
### 🌐 API 工具
* **最常用類型**。用於連接和呼叫外部的 HTTP/HTTPS API 服務。
* **常見應用**：獲取天氣資訊、查詢外部資料庫、觸發 webhook、與第三方服務整合等。
* **必要配置**：API 端點 URL、HTTP 方法、請求標頭 (Headers)、參數結構 (Parameters Schema)。
### ☁️ MCP 工具
* **模型上下文協定**（Model Context Protocol, MCP）,透過標準化協定實現伺服器、用戶端與主機的協作。
* **適用場景**：讓 AI 助理調用外部工具執行更複雜和實用的任務。
* **必要配置**：MCP 伺服器 URL、參數、環境變數等。
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.maiagent.ai/tools/tool_description.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.