建立與最佳化自訂代理程式的最佳實踐

設計良好的自訂代理程式可減少額度消耗並提供更好的結果。以下是如何充分利用每次執行的訣竅：

• 將自訂代理程式用於重複性工作。 若為一次性需求，請改用 Notion 代理程式——它已包含在您的方案中。自訂代理程式會消耗 Notion 額度，因為它們會在背景自動執行，無論您是否在線上。

• 選擇特定的觸發條件。 針對特定的 @提及或屬性變更進行觸發，而非針對每則訊息或資料庫更新。減少錯誤啟動，減少浪費的執行次數。

• 保持上下文集中。 將您的代理程式指向其所需的特定頁面或資料庫。如此一來，它只會讀取必要的內容，且每次執行都能保持專注。

• 預先定義「完成」的標準。 確切告訴您的代理程式完整的執行結果是什麼樣子。指令越清晰，它達到結果的速度就越快。

• 批次處理獨立任務。 例如，要求您的代理程式一次讀取多個來源，而不是一次讀取一個。

  • ✅ 「讀取專案資料庫與 #support Slack 頻道，然後撰寫每週更新。」

  • 🚫 「讀取專案資料庫，然後撰寫每週更新。接著讀取 #support Slack 頻道並新增至每週更新。」

• 當工作流程相似時，請從現有的自訂代理程式開始。 如果您需要的工作流程已存在為自訂代理程式，請直接建立副本，而不要從頭開始建立。開啟該自訂代理程式，選取 ••• 並選擇 建立副本。

  • 該副本預設為私人。

  • 複製後，請重新驗證 Slack 等工具，檢查觸發條件是否如預期般轉移，並重新部署任何 Worker——它們不會包含在副本中。這對於快速建立現有代理程式的團隊變體特別有用。深入了解 本文中關於建立副本自訂代理程式的內容。

當自訂代理程式擁有明確的工作、正確的來源以及嚴謹的「完成」定義時，它們最為可靠。這篇最佳實踐文章涵蓋了如何撰寫更好的指令、選擇正確的觸發條件，以及隨著時間推移改善結果。

如果您不確定從何處開始，請從團隊經常重複的工作著手。當工作流程可預測且易於審核時，自訂代理程式最為有效。

尋找符合以下條件的工作流程：

• 可重複，例如彙整報告、分流傳入的請求，或回答常見的 Slack 問題

• 頻繁，意即每天或每週都會發生

• 易於評估，因此您可以快速判斷輸出是否正確

選擇工作流程後，請先建立自訂代理程式的最簡版本。在增加複雜度之前，請先確保其能穩定運作。

當流程感覺穩定且可預測時，您可以新增觸發條件或排程來實現完全自動化。

當您為自訂代理程式提供清晰的指示時，它會產生更一致且可靠的結果。請專注於成功的樣貌，並提供達成該目標所需的背景資訊。

從您想要的結果開始

• 描述最終輸出應呈現的樣貌，而非列出每個步驟

• 讓自訂代理程式自行決定如何達成目標

• 範例：「建立每週狀態更新，總結已完成的任務、阻礙因素以及後續步驟。」

分享實際範例

• 貼上先前的狀態更新、格式化報告或已分類的請求

• 使用具體範例，而非抽象描述

明確說明格式與目的地

• 指定輸出應傳送至何處（Slack、資料庫或現有頁面）

• 標明應填寫哪些屬性或區段

• 範例：「將摘要發佈至 #team-updates，並將其新增至 Weekly Reports 資料庫。」

設定簡單的界線

• 釐清自訂代理程式應執行什麼，以及應 避免 什麼

• 範例：「更新現有的每週報告頁面，而非建立新頁面」，或「僅在 #support 中回應」。

標明邊緣案例

• 說明若沒有資料或沒有新內容可報告時該怎麼做

• 範例：「如果本週沒有更新，請發布『無更新』，而不是直接跳過。」

保持說明簡短且聚焦

• 較簡短的說明能產生更一致的結果

• 如果您的設定變得冗長，請將工作流程拆分為多個自訂代理程式

設定自訂代理程式時，請決定工作應按排程執行、回應動作執行，還是兩者皆有。

將排程用於可預測的工作

• 當任務應在固定頻率下執行（無論是否有活動）時，請選擇排程

• 非常適合每週報告、每日簡報或每月摘要等重複性工作

將觸發條件用於回應式工作

• 當任務應針對特定事件進行回應時，請選擇觸發條件

• 例如在 Slack 中回報錯誤、資料庫中新增頁面，或收到特定寄件者的電子郵件

必要時結合排程與觸發條件

• 有些工作流程會同時包含這兩種模式

• 例如，一個基於觸發條件的自訂代理程式可以在錯誤發生時進行分類，而另一個排程自訂代理程式則負責彙整這些已分類錯誤的每週摘要

從較低頻率與有限範圍開始

• 先從每週排程開始，而非每日排程

• 先從一個頻道開始，而非五個頻道

• 確認輸出一致且可靠後，再擴大規模

在完全啟用您的工作流程之前，請花點時間測試並調整您的設定。

在啟用觸發條件或排程前進行測試

• 點擊 執行 以手動執行自訂代理程式

• 檢閱輸出以確認其行為符合預期

• 只有在結果正確無誤後，才開啟觸發條件或排程

使用小規模群組進行測試

• 與幾位團隊成員分享代理程式以收集意見回饋

• 利用早期的意見回饋在更廣泛地推廣之前發現問題

預期需要反覆調整

• 大多數代理程式需要經過幾次測試執行才能達到預期效果

• 根據輸出資料的實際結果來優化指示，而不是根據您原先預想的指示內容

優先檢查活動記錄檔

• 點擊時鐘圖示以查看觸發該次執行的原因

• 檢視代理程式執行了哪些動作，以及可能在何處失敗

• 在擴大存取權限之前，請使用記錄檔來診斷問題並確認代理程式的行為符合預期

了解常見的修復方法

• 「輸出不正確」通常表示指示需要更明確的說明

• 「資料遺失」通常表示代理程式需要存取權限以存取其他頁面或資料庫，請確認其存取權限

  工具和存取權限

• 「執行失敗」通常指向權限不足或指令不明確的問題

設計良好的代理程式執行速度更快，且能避免不必要的工作。有三個因素會影響效率：

• 代理程式執行的頻率，

• 它讀取的內容數量，以及

• 完成任務所需的步驟數量

提升效能最簡單的方法是限制不必要的執行。設計觸發條件，讓代理程式僅在可能採取動作時才執行。

從小規模開始並逐步擴展

• 從每週執行開始，而不是每天執行

• 先使用一個頻道或工作流程，再擴展到更多頻道或工作流程

• 一旦結果可靠，再增加執行頻率

使用高訊號觸發條件，讓您的代理程式僅在需要時執行

• 針對 Slack：設定 @提及或特定表情符號反應作為觸發條件，而非針對所有訊息

• 針對 Notion：設定特定屬性變更為觸發條件，而非對每次資料庫更新觸發

• 針對 Notion Mail：設定篩選後的電子郵件集作為觸發條件，而非每封電子郵件

預期會有一些「無需採取動作」的執行

• 當代理程式判斷沒有需要執行的事項時，就會發生這種情況

• 這是正常且高效的——代理程式在退出前只會檢查觸發條件和指示

代理程式讀取的內容越多，每次執行所需的工作量就越大。請保持範圍精簡。

• 將代理程式指向盡可能小的範圍。理想情況是單一頁面或幾個頁面，這些頁面連結到代理程式僅在需要時才能載入的子頁面。

• 如果您已經知道代理程式應該使用哪個資料庫或頁面作為真實來源，請避免要求代理程式進行廣泛搜尋。

執行過程中的每個額外步驟都會增加工作量，特別是當自訂代理程式執行多次搜尋時。

• 明確定義完成的標準，以便代理程式能以更少的步驟完成任務。

• 如果代理程式能同時呼叫多個工具，效率會更高。請盡可能在指示中鼓勵平行使用工具。

  • 可同時執行：「同時讀取專案資料庫、工程 Slack 頻道以及最新的短期衝刺筆記頁面。」這三個來源是獨立的，因此代理程式會同時讀取所有來源，而不是逐一讀取。

  • 必須按順序執行：「在報告資料庫中建立摘要頁面，然後將連結發佈到 Slack 的 #team-updates。」代理程式需要頁面網址才能發佈連結，因此這些步驟必須依序執行。

如果代理程式頻繁詢問多個後續問題、重試相同動作、重複檢查相同頁面，或以可預測的方式出錯，則需要改進說明或設定。

• 如果執行時因權限原因頻繁出錯（例如沒有權限在 Slack 中回應，或網址不受信任），請在 工具與存取權 下調整代理程式的存取權，或在說明中告知代理程式避免執行這些動作。