# 建立 API 工具

{% hint style="info" %}
您可以使用 MaiAgent 製作的 [工具製作 AI 助理](https://chat.maiagent.ai/web-chats/27934296-105a-4f3f-80f0-7e9dcdb638d3) 協助您建立 API 工具
{% endhint %}

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

## **什麼是 API？** <a href="#what-is-api" id="what-is-api"></a>

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

想像你在餐廳用餐：

* **你**：需要食物的客戶（應用程式）
* **廚房**：製作食物的地方（提供服務的系統）
* **服務員**：在你和廚房之間傳遞訊息（**API**）

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

<figure><img src="/files/iwFxnHtljhRJ2CU5aLv2" alt=""><figcaption><p>API 流程示意圖</p></figcaption></figure>

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

**電商客服自動化**

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

**行銷活動管理**

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

**線上課程平台：**

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

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

## 快速建立 API 工具 <a href="#quick-create-api-tool" id="quick-create-api-tool"></a>

### 1. 進入工具管理介面 <a href="#step-1-enter-tool-management" id="step-1-enter-tool-management"></a>

首先，請從左側導航欄進入「 <mark style="color:blue;">AI 功能</mark>」區塊，然後點擊「<mark style="color:blue;">🔧 工具</mark>」。進入工具列表頁面後，點選右上角的「<mark style="color:blue;">➕ 新增工具</mark>」按鈕。

<figure><img src="/files/RqwNqlN67Ny7DSLtYUMG" alt="工具列表頁面與新增按鈕"><figcaption><p>點擊「➕ 新增工具」開始建立</p></figcaption></figure>

### 2. 選擇工具類型 <a href="#step-2-select-tool-type" id="step-2-select-tool-type"></a>

工具類型，選擇 API。

<figure><img src="/files/oquIRV6oXl4zTSzvvi93" alt=""><figcaption></figcaption></figure>

### 3. 設定顯示名稱 <a href="#step-3-set-display-name" id="step-3-set-display-name"></a>

為工具設定清晰的顯示名稱，這邊設為 <mark style="color:blue;">google calendar</mark>。

<figure><img src="/files/CQoZGHsl7RQIL1atDRHq" alt=""><figcaption></figcaption></figure>

* **用途**：此名稱將會顯示在平台介面中，供所有用戶查看。
* **建議**：選擇一個能清晰表達工具主要功能的名稱，方便用戶理解。此名稱沒有嚴格的格式限制。

### 4. 設定工具名稱 <a href="#step-4-set-tool-name" id="step-4-set-tool-name"></a>

接下來是「<mark style="color:blue;">工具名稱</mark>」欄位。

* **用途**：此名稱是 AI 助理在內部呼叫和識別此工具時使用的唯一標識符。
* **命名規則 (重要)**：
  * 必須使用英文。
  * 只能包含：
    * 小寫英文字母 (a-z)
    * 大寫英文字母 (A-Z)
    * 數字 (0-9)
    * 底線 (`_`)
    * 連字符 (`-`)
  * **範例**：`get_weather_forecast`, `database-query-tool`

下圖設為 <mark style="color:blue;">google\_calendar\_retriever</mark>

<figure><img src="/files/o319Aj1aTmQk2jaTQtbb" alt=""><figcaption><p>API 工具名稱定義</p></figcaption></figure>

### 5. 撰寫工具描述 <a href="#step-5-write-tool-description" id="step-5-write-tool-description"></a>

在「<mark style="color:blue;">工具描述</mark>」欄位中，用戶可以提供清晰且詳細的工具說明。

* **重要性**：良好的描述能幫助 AI 助理更準確地理解：
  * 工具的功能和目的。
  * 何時應該使用這個工具。
  * 如何解釋工具的輸出結果。
* **建議內容**：說明工具做什麼、輸入什麼、輸出什麼，以及任何使用上的注意事項。

<figure><img src="/files/lGr9csdTbZ5ospr1N9PK" alt=""><figcaption><p>工具描述</p></figcaption></figure>

### 6. API 配置詳細設定 <a href="#step-6-api-configure-details" id="step-6-api-configure-details"></a>

#### a. 🔗 API URL <a href="#api-url" id="api-url"></a>

* 填寫目標 API 端點的完整網址 (包含 `http://` 或 `https://`)。
* **範例**：`https://api.opencalendar.org/data/2.5`

<figure><img src="/files/2OuenTwouLfK7TLCZHQS" alt=""><figcaption></figcaption></figure>

#### b. 📮 HTTP 方法 <a href="#http-method" id="http-method"></a>

* 從下拉選單中選擇 API 服務要求的 HTTP 動詞：
  * `GET`：通常用於獲取資源。
  * `POST`：通常用於創建新資源或提交數據。
  * `PUT`：通常用於完整替換或更新資源。
  * `DELETE`：通常用於刪除資源。

<figure><img src="/files/y5F9BA2TCe5vcEOXc2Rn" alt=""><figcaption></figcaption></figure>

#### c. 📰 標頭 (Headers) <a href="#headers" id="headers"></a>

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

**常見用途**：

* 身份驗證 (`Authorization`, `X-API-Key`)
* 指定內容類型 (`Content-Type`)
* 指定接受的回應格式 (`Accept`)

若要新增標頭，您需要：

* 點擊「<mark style="color:blue;">➕ 新增標頭</mark>」來定義隨請求發送的 HTTP 標頭。
* **格式**：必須是有效的 JSON 物件，其中鍵 (Key) 是標頭名稱，值 (Value) 是標頭內容 (字串)。
* **範例**：

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

<figure><img src="/files/rzlb0CAc1ebgiW4hkqf7" alt="API 標頭設定截圖"><figcaption><p>設定必要的 HTTP 請求標頭</p></figcaption></figure>

#### d. 🧩 參數結構 (Parameters Schema) <a href="#parameters-schema" id="parameters-schema"></a>

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

* **核心設定**：定義 AI 助理在呼叫此工具時，可以或必須提供哪些參數(要傳遞給系統處理的內容)，以及這些參數的格式。
* **格式**：使用標準的 **JSON Schema** 格式。
* **關鍵元素**：
  * `type: "object"`：表示參數是一個物件。
  * `properties`: 定義每個參數的物件。
    * **參數名稱** (例如 `"search"`)：對應的物件包含該參數的細節。
      * `type`: 參數的資料類型 (`string`, `integer`, `number`, `boolean`, `array`, `object`)。
      * `description`: 對 AI 助理的說明，解釋此參數的意義。
      * `default` (可選): 參數的默認值。
      * `enum` (可選): 如果參數值只能是特定幾個選項之一，在此列出。
  * `required`: 一個包含所有**必填**參數名稱的陣列。
* **範例** (影音搜尋工具)：

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

<figure><img src="/files/OEGufnGB0Jtz6QZ3gG4x" alt="API 參數結構設定截圖"><figcaption><p>使用 JSON Schema 精確定義 API 參數</p></figcaption></figure>

### 7. 💾 儲存工具 <a href="#step-7-save-tool" id="step-7-save-tool"></a>

確認所有設定無誤後，捲動到頁面底部，點擊「<mark style="color:blue;">確認</mark>」按鈕。您的新工具就建立完成了！

<figure><img src="/files/LPVQb5XEvJA6SpG4RVEz" alt=""><figcaption></figcaption></figure>

## ⚠️ 重要提醒 <a href="#important-notes" id="important-notes"></a>

**連線測試**

* 建立工具後，建議先測試 API 是否正常運作
* 可使用測試工具驗證工具功能，如：
  * POSTMAN
  * 企業自己搭建的 API 測試請求平台

**權限管理**

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


---

# 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/setup_api_tool.md?ask=<question>
```

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.