AI Actions（智能操作）

AI Actions 讓你的 Webnav.ai 助手不只是回答問題，而能執行操作：呼叫你自己的後端 API 來下單、查單、查物流、發起退款等。

AI Actions 為 Pro / Enterprise 功能。

運作原理

Webnav.ai 是編排層，從不儲存你的訂單與資金，只呼叫你的 API 並把結果轉成自然語言。

訪客 → Widget → Webnav.ai（LLM 決策 + 呼叫你的 MCP 工具）→ 你的 MCP 伺服器 → 回到訪客

1. 訪客提出可執行的請求（「我的訂單 #1234 到哪了？」）。
2. LLM 匹配到發現的工具（query_logistics）並抽取參數（order_id: "1234"）。
3. Webnav.ai 透過 JSON-RPC 2.0 對你的 MCP 端點呼叫該工具。
4. 你的伺服器回傳資料，LLM 以自然語言回覆，並可附結構化卡片。

對於寫操作（下單、退款），助手會先顯示確認卡片，訪客點「確認」前不會執行任何操作。

設定（商家後台）

AI Actions 透過 MCP（Model Context Protocol） 工具伺服器接入——Webnav.ai 透過 JSON-RPC 2.0 over HTTP 動態發現並呼叫你的工具。進入 Dashboard → AI Actions。

1. 連接
   • 將 模式 切換為 MCP，輸入你的 MCP 端點（生產環境須為公網主機上的 HTTPS）。
   • 視需要新增鑑權標頭（如 bearer token）——值加密儲存並逐請求轉發。
2. 測試連接
   • 點 測試連接。Webnav.ai 經後端對你的端點發 initialize + tools/list，並顯示發現的工具與 annotations。你的端點不會被瀏覽器直接訪問。
3. 需確認工具
   • 確認預選的寫工具，並補充任何其他需要確認卡片的工具名稱，然後儲存。

完整協議、逐工具欄位規格與通訊格式，請見 MCP 接入指南。

五個標準電商動作

動作	類型	需確認	用途
list_products	讀	否	回傳商品目錄（用於 SKU 校驗）
query_order	讀	否	查訂單狀態／詳情
query_logistics	讀	否	查物流軌跡
create_order	寫	是	下新訂單
create_refund	寫	是	發起退款申請

list_products 在顯示寫操作確認卡片前由 Webnav.ai 內部使用：若訪客要求的 SKU 不在商品目錄中，助手會提示其選擇真實商品，而不是為無效 SKU 顯示確認卡片。

實際要實作這些動作呼叫的工具，請見 電商接入規範 與 MCP 接入指南。

確認流程（寫操作）

LLM 收集參數 → Webnav.ai 建立待確認動作 → widget 顯示 確認／取消
   → 訪客點確認 → Webnav.ai 僅執行一次 → 結果卡片

待確認動作為單次使用、限時（10 分鐘），且綁定該訪客——無法被重放或被他人確認，從而避免重複下單或重複退款。

身份（user token）

對於涉及用戶的操作，你的站點為已登入訪客簽發短時 user token 並交給 widget：

<script src="https://widget.webnav.ai/chat-widget.js"
        data-user-token="YOUR_SIGNED_USER_TOKEN"></script>

單頁應用可在登入後設定：

window.WebnavWidget.setUserToken('YOUR_SIGNED_USER_TOKEN');

Webnav.ai 不解析也不儲存此令牌，只轉發給你的 MCP 伺服器（將其配置為鑑權標頭），由你還原真實用戶。

寫工具安全

create_order、create_refund 以及任何名稱以 create_、refund_、cancel_、pay_ 開頭的工具，一律會觸發確認卡片——不管 MCP 伺服器的 annotations.destructiveHint 值為何。你還可以在 Dashboard → AI Actions → 需確認工具 中標記其他需要確認的工具。

詳見 MCP 接入指南，包含完整設定說明、通訊格式與 canonical 工具規格書。

安全與計費說明

• 所有出站呼叫都發往你的 MCP 端點，並受你的鑑權標頭保護，請在你這側驗證。
• 出站 host 必須是公網（禁止內網／私有位址——SSRF 防護）。後台「測試連接」一律透過 Webnav.ai 代理發出，你的端點不會被瀏覽器直接訪問。
• 每次動作呼叫都會被記錄（敏感欄位脫敏）——見 Dashboard → AI Actions → Call Logs。
• 每次對話的工具輪數有上限，以控制成本。