將 Notion 用作你的 AI 知識庫：完整實戰手冊
本指南將把你的 ABC Salesbot AI Agent 連接到公司的 Notion 工作區，讓團隊成員可以在 WhatsApp 上提問，並直接從你的 SOP、政策和文件中獲得答案。
1. 概述
使用情境
- 公司資訊： 「我們公司的使命是什麼？」
- HR 政策： 「我有多少天假期？」
- SOP： 「如何為新客戶辦理入職？」
- 規範指引： 「報銷限額是多少？」
前置需求
- 擁有 AI Agent 權限的 ABC Salesbot 帳戶
- 擁有管理員權限的 Notion 工作區
- 文件已經存放在 Notion 中
所需時間
設定大約需要 30 分鐘。
2. 架構
運作原理
團隊成員提出問題後，你的 AI Agent 會呼叫兩個基於 Notion API 的自訂工具，然後回覆答案並附上來源頁面的連結：
- 團隊成員在聊天中提問
- AI Agent 在 Notion 中搜尋相符的頁面
- AI Agent 取得最符合頁面的內容
- AI Agent 用實際內容回答，並附上 Notion 連結
雙工具工作流程
Notion API 需要兩次獨立的呼叫：
- 第 1 步，
query_notion_pages： 搜尋 Notion 並回傳頁面標題和 ID - 第 2 步，
get_notion_page_content： 從指定頁面取得實際內容
為什麼需要兩個工具？ Notion 的搜尋 API 只回傳頁面中繼資料（標題、ID），不包含頁面內的實際內容。我們需要第二次呼叫來取得內容。
3. 第 1 步：建立 Notion 整合
3.1 開啟 Notion Integrations
- 開啟 https://www.notion.so/my-integrations
- 點擊 + New integration（新增整合）
3.2 設定整合
- Name（名稱）： ABC Salesbot（或你喜歡的名稱）
- Logo： 可選，上傳你的公司 Logo
- Associated workspace（關聯工作區）： 選擇你的公司工作區
3.3 設定能力
在 Content Capabilities（內容能力）下啟用：
- Read content（讀取內容，必需）
在 Comment Capabilities（留言能力）下：
- Read comments（讀取留言，可選）
3.4 儲存並複製密鑰
- 點擊 Save
- 點擊 Internal Integration Secret 旁邊的 Show
- 複製 Internal Integration Secret（內部整合密鑰）
- 把它保存在安全的地方，稍後在 ABC Salesbot 中會用到
3.5 設定頁面存取權限
關鍵步驟！你的整合只能存取你明確授權的頁面。
- 在整合設定中，點擊 Access（存取權限）標籤
- 你會看到可以選擇整合能存取哪些頁面或工作區
- 選擇你希望 AI 能夠讀取的頁面：你可以授權特定頁面，也可以授權整個工作區
- 點擊 Save 或 Update 確認
提示：如果你授權了某個父頁面，其下所有子頁面也都可以存取。
建議結構：把所有內容放在一個頂層頁面下，例如一個 Company Knowledge Base（公司知識庫）頁面，其中包含以下子頁面：
- 使命、願景與價值觀
- 公司目標
- HR 政策： 休假政策、費用報銷、行為準則
- SOP： 客戶入職、支援流程、銷售流程
- 技術文件： 產品設定、疑難排解
授權頂層的「Company Knowledge Base」頁面後，裡面的所有子頁面都可以被存取。
4. 第 2 步：在 ABC Salesbot 中建立自訂工具
你需要建立兩個自訂工具。
工具 1：query_notion_pages
該工具用於搜尋你的 Notion 工作區。
Info（資訊）標籤：
- Name：
query_notion_pages - Description： Search the company Notion knowledge base for relevant pages. Returns page titles and IDs. After searching, you MUST use get_notion_page_content to fetch the actual content.
- Method： POST
- URL：
https://api.notion.com/v1/search - Enabled： On
- Crawl page： Off
Configurations（設定）標籤：
- Username： 留空
- Password： 留空
- API Key： 留空
- Bearer Token： 貼上你的 Notion 整合密鑰
Custom Headers（自訂標頭）（每一項都點擊「Add Header」新增）：
- Notion-Version：
2022-06-28 - Content-Type：
application/json
Parameters（參數）標籤（點擊「Add Params」並填寫）：
- Name：
query - Description： The search keywords to find relevant Notion pages
- Type： string
- Default： 留空
- Location： body
- Required： On
點擊 Save。
工具 2：get_notion_page_content
該工具用於取得頁面的實際內容。
Info（資訊）標籤：
- Name：
get_notion_page_content - Description： Retrieve the full content of a Notion page using its page ID. ALWAYS use this after query_notion_pages to get the actual text content before answering the user.
- Method： GET
- URL：
https://api.notion.com/v1/blocks/{page_id}/children - Enabled： On
- Crawl page： Off
Configurations（設定）標籤：
- Username： 留空
- Password： 留空
- API Key： 留空
- Bearer Token： 貼上你的 Notion 整合密鑰（與工具 1 相同）
Custom Headers（自訂標頭）（點擊「Add Header」）：
- Notion-Version：
2022-06-28
Parameters（參數）標籤（點擊「Add Params」並填寫）：
- Name：
page_id - Description： The Notion page ID from search results (the "id" field)
- Type： string
- Default： 留空
- Location： path
- Required： On
點擊 Save。
重要：儲存後再次檢查
儲存兩個工具後，請回頭確認兩個工具的自訂標頭都儲存成功了。可能存在第一次儲存標頭不生效的問題。請檢查：
- 工具 1： Notion-Version 和 Content-Type 標頭仍然存在
- 工具 2： Notion-Version 標頭仍然存在
如果遺失了，請重新新增並儲存。
5. 第 3 步：設定系統提示詞
從本指南末尾的附錄中複製完整的系統提示詞，並貼到你的 AI Agent 的 System Prompt（系統提示詞）欄位中。
系統提示詞中的關鍵部分
- Identity & Purpose（身分與目的）： 告訴 AI 它是誰、做什麼
- Two-Tool Workflow（雙工具工作流程）： 必須使用兩個工具的關鍵指令
- Terminology Translation（術語轉換）： 將口語化的說法對應到業務術語
- Search Strategy（搜尋策略）： 如何高效搜尋
- Escalation Guidelines（升級指引）： 何時轉給主管、HR 等
- Response Format（回覆格式）： 如何組織答案
- Sample Interactions（範例對話）： 優秀回覆的範例
自訂清單
使用前，請更新以下部分：
- Terminology Translation： 加入你公司特有的術語
- 升級聯絡人： 更新部門名稱和聯絡人
- 範例對話： 加入與你的文件相關的範例
6. 第 4 步：測試
執行以下測試，驗證一切正常。
測試 1：基礎搜尋
提問：「What is our company mission?」
預期行為：
- AI 使用「mission vision」呼叫
query_notion_pages - AI 從結果中擷取 page_id
- AI 用該 page_id 呼叫
get_notion_page_content - AI 回覆實際的使命宣言，並附上 Notion 連結
測試 2：政策問題
提問：「How many days annual leave do I get?」
預期行為：
- AI 搜尋與休假相關的頁面
- AI 取得頁面內容
- AI 給出具體答案並附上連結
測試 3：術語轉換
提問：「What's my commission?」（而你的文件中寫的是「fees」）
預期行為：
- AI 將「commission」轉換為「fees」
- AI 找到並回傳相關內容
測試 4：未找到內容
提問：「What's the pet policy?」（假設該政策不存在）
預期行為：
- AI 搜尋後沒有找到任何內容
- AI 如實說明沒有找到
- AI 給出替代建議（詢問主管、HR）
成功標準
- AI 呼叫了兩個工具
- AI 給出的是實際內容，而不只是頁面標題
- AI 在回覆中附上了 Notion 連結
- AI 能夠得體地處理「未找到」的情況
7. 疑難排解
錯誤：「missing_version」
錯誤訊息：Notion-Version header failed validation, Notion-Version header should be defined。
解決方法： 在 Configurations 標籤中新增自訂標頭 Notion-Version，值為 2022-06-28。
錯誤：「unauthorized」或「invalid_token」
錯誤訊息：API token is invalid。
解決方法：
- 在 Notion integrations 中重新生成權杖
- 將新權杖複製到 Bearer Token 欄位
- 確認權杖前後沒有多餘的空格
錯誤：「object_not_found」
錯誤訊息：Could not find page with ID: xxxxx。
解決方法： 該頁面沒有共享給你的整合。前往 Notion，開啟該頁面，透過 Connections（連接）加入你的整合。
錯誤：「invalid_request_url」
錯誤訊息：Invalid request URL。
解決方法： 在工具設定中關閉「Crawl page」開關。
AI 只回傳頁面標題，不回傳內容
原因： AI 沒有呼叫第二個工具。
解決方法：
- 檢查系統提示詞中是否包含雙工具指令
- 讓
get_notion_page_content的描述更明確 - 用更強硬的指令測試：「After searching, you MUST call get_notion_page_content」
搜尋沒有結果
可能的原因：
- 頁面沒有共享給整合
- 搜尋詞與頁面內容不相符
- 缺少 Notion-Version 標頭
解決方法：
- 確認頁面已共享（在 Notion 中檢查 Connections）
- 嘗試更寬泛的搜尋詞
- 檢查 Configurations 標籤中的標頭
AI 不做術語轉換
原因： 系統提示詞中沒有該術語，或 AI 忽略了指令。
解決方法：
- 將缺少的術語加入 Terminology Translation 部分
- 讓術語部分在系統提示詞中更突出
- 考慮使用更強的模型（用 GPT-4o 取代 GPT-4.1 mini）
模型建議
- GPT-4.1 mini： 可靠性約 70-80%，成本最低，適合預算有限的簡單知識庫
- GPT-4o mini： 可靠性約 85%，成本低，性能均衡
- GPT-4o： 可靠性約 95%，成本中等，適合需要高準確率的複雜知識庫
- GPT-4.1： 可靠性約 95%，成本中等，適合複雜的多步驟任務
8. 附錄：完整系統提示詞
將下方摺疊區內的全部內容複製到你的 AI Agent 的 System Prompt（系統提示詞）欄位中，然後根據你的公司情況自訂術語和升級聯絡人。
以下系統提示詞請保持英文原樣貼到產品中，請勿翻譯。
快速參考卡
設定清單
- 在 notion.so/my-integrations 建立一個 Notion 整合
- 複製整合密鑰（Bearer Token）
- 將你的 Notion 頁面共享給該整合
- 建立工具 1：
query_notion_pages（POST 到/v1/search） - 建立工具 2：
get_notion_page_content（GET 到/v1/blocks/{page_id}/children） - 為兩個工具都新增標頭
Notion-Version: 2022-06-28 - 貼上系統提示詞
- 用「What is our company mission?」進行測試
工具速查
- query_notion_pages： POST 到
https://api.notion.com/v1/search，關鍵參數query（body） - get_notion_page_content： GET 到
https://api.notion.com/v1/blocks/{page_id}/children，關鍵參數page_id（path）
必需的標頭（兩個工具都需要）
- Notion-Version：
2022-06-28 - Content-Type：
application/json（僅工具 1）