LogoLogo
註冊/登入
  • 使用者手冊
  • 技術人員手冊
  • API 文件
  • AI 助理市集
  • 概述
  • 申請與登入
    • 申請帳號
    • 如何登入平台
    • 忘記密碼
  • 打造您專屬的 AI 助理
    • AI 助理的功能
    • 建立 AI 助理
  • 為您的 AI 助理製作工具
    • 工具的功能說明
    • 建立工具
    • 爲 AI 助理配置工具
  • 提供 AI 助理參考資料
    • 如何建立知識庫
    • 如何建立 FAQ 常見問題
    • 如何使用爬蟲(爬取資料)功能
  • 讓 AI 助理正式上線
    • 選擇串接平台
    • 內部問答的功能
    • 串接對話平台:網站
    • 串接對話平台:LINE
    • 串接對話平台:FB Messenger
  • 串接對話平台:Telegram
  • 追蹤 AI 助理運作成效
    • 所有對話的功能
    • 回覆品質控管
    • Webhook
    • 使用分析
  • 組織設定
    • 「組織」管理架構說明
    • 組織與成員設定
  • 角色權限管理
  • 應用實例
    • 文字客服
      • 法規查詢助理
      • 產品查詢助理
    • 內部知識管理
      • 專業知識管理
      • 會議需求管理
  • 語音客服
    • IVR 客服意圖辨識
    • 語音通話摘要
    • 語音通話質檢
  • 影像視覺
    • 發票辨識
    • 公文掃描
    • 名片掃描
  • 外部資料串接
    • 農業數據資料查詢
  • MaiAgent AI助理
    • 掃 QR Code 即時互動
  • 其他
    • 用量計算
Powered by GitBook
On this page
  • 1. 進入工具管理介面
  • 2. 設定顯示名稱
  • 3. 設定工具名稱
  • 4. 選擇工具類型
  • a. 🌐 API 工具
  • b. ☁️ MCP 工具
  • 5. 撰寫工具描述
  • 6. API 配置詳細設定
  • a. 🔗 API URL
  • b. 📮 HTTP 方法
  • c. 📰 標頭 (Headers)
  • d. 🧩 參數結構 (Parameters Schema)
  • 7. MCP 配置詳細設定
  • a. ⚙️ MCP 伺服器 URL
  • b. 🎛️ MCP 命令參數 (mcp_args)
  • c. 🌳 MCP 環境變數 (mcp_env)
  • d. 🔑 MCP 允許的子工具 (mcp_allowed_tools)
  • 8. 💾 儲存工具

Was this helpful?

  1. 為您的 AI 助理製作工具

建立工具

Previous工具的功能說明Next爲 AI 助理配置工具

Last updated 10 days ago

Was this helpful?

本指南將引導您完成在平台中建立新工具的步驟。工具是擴展 AI 助理能力的關鍵,允許它與外部服務互動或執行特定任務。

1. 進入工具管理介面

首先,請從左側導航欄進入「 AI 功能」區塊,然後點擊「🔧 工具」。進入工具列表頁面後,點選右上角的「➕ 新增工具」按鈕。

2. 設定顯示名稱

在「新增工具」表單中,第一個需要填寫的是「顯示名稱」。

  • 用途:此名稱將會顯示在平台介面中,供所有用戶查看。

  • 建議:選擇一個能清晰表達工具主要功能的名稱,方便用戶理解。此名稱沒有嚴格的格式限制。

3. 設定工具名稱

接下來是「工具名稱」欄位。

  • 用途:此名稱是 AI 助理在內部呼叫和識別此工具時使用的唯一標識符。

  • 命名規則 (重要):

    • 必須使用英文。

    • 只能包含:

      • 小寫英文字母 (a-z)

      • 大寫英文字母 (A-Z)

      • 數字 (0-9)

      • 底線 (_)

      • 連字符 (-)

    • 範例:get_weather_forecast, database-query-tool

4. 選擇工具類型

選擇「工具類型」。根據您的服務所使用的協定類型選擇工具類型。

目前支援以下主要類型:

a. 🌐 API 工具

  • 最常用類型。用於連接和呼叫外部的 HTTP/HTTPS API 服務。

  • 常見應用:獲取天氣資訊、查詢外部資料庫、觸發 webhook、與第三方服務整合等。

  • 必要配置:API 端點 URL、HTTP 方法、請求標頭 (Headers)、參數結構 (Parameters Schema)。

b. ☁️ MCP 工具

  • 模型上下文協定(Model Context Protocol, MCP),透過標準化協定實現伺服器、用戶端與主機的協作。

  • 適用場景:讓 AI 助理調用外部工具執行更複雜和實用的任務。

  • 必要配置:MCP 伺服器 URL、參數、環境變數等。

5. 撰寫工具描述

在「工具描述」欄位中,用戶可以提供清晰且詳細的工具說明。

  • 重要性:良好的描述能幫助 AI 助理更準確地理解:

    • 工具的功能和目的。

    • 何時應該使用這個工具。

    • 如何解釋工具的輸出結果。

  • 建議內容:說明工具做什麼、輸入什麼、輸出什麼,以及任何使用上的注意事項。

6. API 配置詳細設定

若您選擇了「🌐 API 工具」,請完成以下設定:

a. 🔗 API URL

  • 填寫目標 API 端點的完整網址 (包含 http:// 或 https://)。

  • 範例:https://api.openweathermap.org/data/2.5/weather

b. 📮 HTTP 方法

  • 從下拉選單選擇 API 服務要求的 HTTP 動詞:

    • GET:通常用於獲取資源。

    • POST:通常用於創建新資源或提交數據。

    • PUT:通常用於完整替換或更新資源。

    • DELETE:通常用於刪除資源。

c. 📰 標頭 (Headers)

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

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

  • 常見用途:

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

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

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

  • 範例:

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

d. 🧩 參數結構 (Parameters Schema)

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

7. MCP 配置詳細設定

若您在「4. 選擇工具類型」時選擇了「☁️ MCP 工具」,則需要完成以下設定。MCP (Multi-Cloud Platform) 工具用於整合多雲平台服務或執行本地客戶端應用程式。

a. ⚙️ MCP 伺服器 URL

  • 用途:MaiAgent 目前接受外部的 MCP 伺服器,透過提供 MCP 伺服器的服務位址(URL), AI 助理就可以調用 MCP 服務連結外部應用。

  • 格式:

    • 請填寫完整的 URL (例如:https://mcp.dev/maiagent/mcp_service)。

  • 注意:此欄位為必填。

b. 🎛️ MCP 命令參數 (mcp_args)

  • 用途:定義在執行 MCP 命令或呼叫 MCP 服務時需要傳遞的參數。

  • 格式:建議使用 JSON 陣列 (Array) 的格式,其中每個元素都是一個字串代表一個參數。

    • 範例 (JSON 陣列):

      [
        "--user",
        "admin",
        "--config",
        "/path/to/config.yaml"
      ]
    • 如果您輸入的是一個以逗號分隔的字串 (例如:arg1,arg2,arg3),系統會嘗試將其解析為參數列表。為避免歧義,推薦使用 JSON 陣列。

  • 留空:如果命令或服務不需要額外參數,此欄位可以留空。

c. 🌳 MCP 環境變數 (mcp_env)

  • 用途:為 MCP 命令的執行環境設定必要的環境變數。

  • 格式:必須是有效的 JSON 物件,其中鍵 (Key) 是環境變數的名稱,值 (Value) 是環境變數的內容 (字串)。

    • 範例:

      {
        "API_KEY": "{{SECRET_MCP_API_KEY}}",
        "REGION": "us-west-1",
        "DEBUG_MODE": "true"
      }
  • 留空:如果不需要設定特定的環境變數,此欄位可以留空。

d. 🔑 MCP 允許的子工具 (mcp_allowed_tools)

  • 用途:指定在此 MCP 客戶端下,AI 助理被授權可以使用的具體子工具列表。一個 MCP 客戶端可能提供多個不同的功能或子工具。

  • 格式:JSON 陣列 (Array) 的格式,其中每個元素都是一個字串,代表一個允許使用的子工具名稱。

    • 範例:

      [
        "get_system_load",
        "run_backup_job",
        "query_database_status"
      ]
  • 自動偵測/留空:如果此欄位留空或未提供,系統在初次連接 MCP 客戶端時,會嘗試自動偵測所有可用的子工具,並預設允許所有偵測到的子工具。若您希望限制 AI 助理只能使用特定的子工具,請在此明確列出。

8. 💾 儲存工具

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

工具製作 AI 助理
點擊「➕ 新增工具」開始建立
為您的工具設定一個易於理解的顯示名稱
設定符合命名規則的工具名稱
撰寫清晰、詳細的工具描述
設定必要的 HTTP 請求標頭
使用 JSON Schema 精確定義 API 參數
設定 MCP 客戶端 URL 或命令
設定 MCP 命令參數
設定 MCP 環境變數
設定 MCP 允許使用的子工具
工具列表頁面與新增按鈕
填寫顯示名稱
填寫工具名稱
工具類型選擇介面截圖
工具描述欄位截圖
API 標頭設定截圖
API 參數結構設定截圖
MCP 客戶端 URL 或命令設定示意圖
MCP 命令參數設定示意圖
MCP 環境變數設定示意圖
MCP 允許的子工具設定示意圖