> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/hook/setup.md). # 新增與設定 Hook 從標準範本建立 Hook、調整參數（禁語清單、判斷模型、偵測服務、封鎖訊息等），並關聯到 Agent。本頁說明如何從標準範本建立一個 Hook、調整它的參數，並把它掛到 Agent 上開始運作。 ## 一、新增 Hook ### 1. 進入 Hook 列表從左側選單進入 AI 功能 →〈Hook〉。列表會顯示目前組織所有的 Hook，包含**名稱、描述、類型、攔截點、動作、關聯 AI 助理、啟用狀態、建立者、更新時間**。

Hook 列表頁 — Hook 列表：可看到每個 Hook 的類型、攔截點（何時介入）、動作（改寫／攔截）、掛在哪些 Agent 上與啟用狀態

### 2. 選擇範本點右上角新增 Hook，在彈出視窗中選擇一個標準範本。每張範本卡片都標示了它的**攔截點**與**動作**，方便你快速判斷用途。

建立 Hook：選擇範本 — 選擇範本：七種標準範本各自標示攔截點（接收使用者訊息時／AI 回應生成後）與動作（修改／封鎖）

{% hint style="info" %} 建立流程分成三個分頁：**範本**（選哪一種）→ **基本資料**（名稱、描述）→ **套用至 AI 助理**（要掛到哪些 Agent）。選好範本後依序填寫即可。 {% endhint %} ## 二、調整參數不同範本有不同的參數。建立後進入 Hook 的設定頁即可調整。常見參數如下： | 範本 | 主要參數 | 說明 | | -------- | -------------------------- | -------------------------------------- | | 個人資料遮罩 | 要遮罩的 PII 類型 | 勾選要偵測的類型（Email／手機／身分證／信用卡） | | 語意個資遮罩 | 個資偵測模型與偵測型別、最低信心值、遮罩樣式 | 先選偵測服務，再勾要遮的個資型別（姓名、地址、電話等）；信心值調高可降低誤殺 | | 敏感詞攔截 | 禁語清單、最短詞長 | 一行一個禁語；最短詞長可過濾太短的詞避免誤殺 | | 提示注入防護 | 判斷模型、額外判斷規則 | 選一個 LLM 來判斷是否為攻擊；可補充自訂規則 | | 內容安全分類攔截 | 內容安全模型與攔截分類、額外分數門檻、偵測服務異常時 | 先選偵測服務，再勾要攔截的分類；全部不勾＝任一分類違規就攔截 | | 無效訊息過濾 | 招呼詞清單、連續重複上限、判斷模型 | 規則先過濾，再由 LLM 判斷是否為無效訊息 | | 回覆可信度把關 | 改寫模型、把關準則 | 選一個 LLM 來判斷回覆是否可靠並改寫 |

個人資料遮罩設定頁 — 以「個人資料遮罩」為例：可勾選要偵測的 PII 類型，並設定啟用狀態

### 判斷模型（LLM 型範本）提示注入防護、無效訊息過濾、回覆可信度把關這類需要「語意判斷」的範本，會有一個**判斷模型**欄位。下拉選單會列出你組織目前可用的模型——這項判斷會逐則訊息執行，**建議選反應快、成本較低的模型**（例如 Haiku、GPT-5 mini、Gemini Flash 這類）。留空則使用平台預設模型。

LLM 型範本的判斷模型設定 — 以「回覆可信度把關」為例：判斷模型可從組織可用的 LLM 下拉選擇，並用「把關準則」以白話描述判斷方向

### 偵測服務（安全模型型範本）「內容安全分類攔截」與「語意個資遮罩」不是用一般 LLM 判斷，而是把內容交給**專用的安全模型**：回傳的是結構化的分類與分數，可以設門檻、可以稽核，延遲與成本也比 LLM 判官低。這兩個範本的設定都是**兩段式**：先選偵測服務，再勾要處理的項目。 **內容安全分類攔截** 1. 在內容安全模型與攔截分類第一個下拉選偵測服務（目前提供 OpenAI Moderation）。 2. 第二個下拉勾選要攔截的分類，例如騷擾、仇恨、違法行為、自殘、性、暴力；**全部不勾＝只要模型判定任一分類違規就攔截**（最嚴格，建議起手值）。 3. 額外分數門檻預設 0，代表完全採用模型判定；設成 0 到 1 之間時，分數還要達到門檻才攔截，調高可降低誤殺。 4. 偵測服務異常時決定服務逾時或未設定金鑰時怎麼辦：`pass` 放行訊息（可用性優先，預設）、`block` 一律攔截（合規優先，受監管產業建議選此）。

內容安全分類攔截設定頁 — 內容安全分類攔截：先選偵測服務，再勾攔截分類；下方可設額外分數門檻與服務異常時的策略

內容安全分類攔截：可勾選的分類 — 可勾選的分類由偵測服務即時提供，每個分類旁標示服務原生的分類名稱，換服務時清單會跟著變

**語意個資遮罩** 1. 在個資偵測模型與偵測型別第一個下拉選偵測服務（目前提供 Google Cloud DLP）。 2. 第二個下拉勾選要遮的個資型別：「標準類型」有姓名、地址、電話號碼、電子郵件、台灣身分證字號、台灣護照號碼等；「供應商專屬類型」還有信用卡號、IBAN 等更多細項。**勾越多，每次呼叫的成本越高**，建議只勾業務上真的需要遮的。 3. 最低信心值預設 0.5，低於此值的偵測結果會被忽略；調高可降低誤殺（例如把公司名誤判成人名），代價是可能漏遮。 4. 遮罩樣式：`type_token` 換成 `[NAME]`、`[ADDRESS]` 這類佔位符，AI 仍知道這裡原本是什麼類型的資料（建議）；`asterisk` 換成等長星號，完全不透露型別。

語意個資遮罩設定頁 — 語意個資遮罩：先選偵測服務，再勾要遮的個資型別（此例勾了姓名與地址）；下方可設最低信心值與遮罩樣式

語意個資遮罩：可勾選的個資型別 — 可勾選的個資型別分成「標準類型」與「供應商專屬類型」兩區，同一個選單內分區呈現

{% hint style="warning" %} **內容會送到外部偵測服務。** 這兩個範本會把待檢查的文字交給偵測服務（OpenAI、Google Cloud）判定。有資料落地或不得外送要求的組織，請先確認合規再啟用。切換偵測服務時，已勾選的項目會自動清空，避免型別不相容導致存檔失敗。 {% endhint %} {% hint style="info" %} **封鎖訊息可自訂。** 「封鎖」型範本（如提示注入防護、敏感詞攔截、無效訊息過濾、內容安全分類攔截）可以在封鎖回覆訊息設定被擋下時要回覆給使用者的訊息，例如「您的訊息包含不適當用語，請修改後再試。」 {% endhint %} ## 三、關聯 Agent Hook 一定要**掛到 Agent**才會生效。有兩種方式： * **建立時掛載**：在新增 Hook 的〈套用至 AI 助理〉分頁直接勾選要套用的 Agent。 * **從 Agent 設定掛載**：進入某個 Agent 的設定頁，切換到 Hook 分頁，選擇要套用的 Hook。

套用 Hook 至 Agent — 在 Hook 的〈套用至 AI 助理〉分頁，從左側「可選」清單把 Hook 加到右側「已選」，即完成掛載

{% hint style="success" %} **一個 Agent 可以掛多個 Hook。** 系統會依序執行，例如先「無效訊息過濾」擋掉灌水、再「個人資料遮罩」遮掉個資、再「提示注入防護」擋掉攻擊——組合成專屬的防護流程。 {% endhint %} {% hint style="info" %} **掛上「接收使用者訊息時」的 Hook，附件、知識庫段落與工具回傳也會一起被檢查。** 不需要另外設定：只要 Agent 掛了進 AI 前的 Hook，使用者上傳的附件內容、知識庫檢索到的段落、Agent 模式下工具查回來的結果，在送進模型之前都會經過同一組 Hook。詳見 [Hook 訊息攔截總覽](/build/hook.md#four-sources)。 {% endhint %} ### 啟用 Hook 確認參數與關聯的 Agent 後，把 Hook 設為啟用。啟用後，只要使用者與該 Agent 對話，Hook 就會在對應的時點自動運作。 ## 四、下一步設定完成後，你可以在 [Hook 執行紀錄](/build/hook/execution-logs.md) 查看每一次攔截或改寫的紀錄，確認 Hook 有正確運作。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/build/hook/setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.