如何在Activepieces中逐步建立AI代理

傳統的自動化工作流程在所有步驟都預先知道的情況下運作良好：它接收資料、應用特定條件並執行特定操作。但當決策取決於上下文時，問題就出現了。 它無法用幾條固定的規則來表達。.

Activepieces 透過建立能夠分析輸入、檢索資訊並選擇必要工具以實現目標的 AI 代理來幫助您解決這些問題。您可以使用它們來對請求進行分類、調查公司、撰寫報告或決定何時需要手動幹預。

建立代理程式並非只是選擇一個模板並編寫提示。為了使其可靠，您必須對其進行定義。 它的指令、工具、知識來源、輸出欄位和執行限制然後，在將其納入生產工作流程之前，您需要使用正常輸入和複雜情況進行測試。

人工智慧代理與傳統流程有何不同？

傳統工作流程會執行預先定義的順序。在相同的輸入和條件下，它應該始終遵循相同的路徑。這使其成為重複性任務的最佳選擇，例如： 複製文件、轉換資料或發送通知.

智能體接收目標後，會在每次執行過程中決定需要哪些資訊以及使用哪些工具。即使是兩個類似的請求，如果其內容或上下文發生變化，也可能導致不同的決策。

特徵	流動	代理人
邏輯	預先透過步驟和條件定義	在每次執行過程中確定
結果	使用等效輸入可以預測	具體結果可能因模型的推理方式而異。
最佳用途	已知且可重複的過程	決策取決於情境的任務
成本	你不一定需要模特兒。	它消耗令牌，並且可以進行多次呼叫。
控制	每個動作都明確地放置在指定位置。	該模型從允許的工具中進行選擇。

如果你可以用「如果A發生，那麼B發生」這樣的短語來描述整個邏輯，那麼你可能需要的是一個條件判斷，而不是一個智能體。將人工智慧用於確定性任務會引入… 更高的成本、延遲和變異性 沒有提供真正的優勢。

最有用的組合通常是混合的：流程負責處理必須始終以相同方式執行的步驟，而代理只解決需要解釋的部分。

在 Activepieces 中建立代理程式之前，您需要準備哪些內容？

在開啟代理編輯器之前，您需要準備以下幾個元件：

• Activepieces Cloud 帳戶或更新後的自管理安裝。
• 這是一個允許你創建代理和連接的專案。
• 平台上配置的模型提供者。
• 代理將使用的應用程式的連接。
• 具有明確目標和界限的應用案例。

在公司管理的設施中，人工智慧提供者的配置方式如下： 平台管理 > 人工智慧中心管理員選擇供應商，輸入其憑證，並決定哪些型號可用於專案。

Activepieces 支援 OpenAI、Anthropic、Google Gemini、Mistral、DeepSeek、xAI、Qwen、Azure、AWS Bedrock 和 OpenRouter 等供應商。它還允許透過該選項使用與 OpenAI API 相容的網關或伺服器。 其他（相容 OpenAI）.

您可以配置多個提供者，並為每個提供者選擇不同的模型。這樣，您可以將更高級的模型用於複雜任務，而將更經濟的替代方案用於簡單的分類或總結。

應用程式連接是單獨建立的。如果代理程式需要查詢 CRM 或傳送訊息，則必須先在專案中準備好相應的憑證。 請勿在說明中寫入 API 金鑰或密碼。.

如何在Activepieces中建立AI代理

Activepieces 提供了建立代理程式的三個起點：

• 請描述一下： 你只需用一句話寫下你的需求，平台就會產生初始配置。
• 使用模板： 為已知用例準備的範本的組成部分。
• 從空白處開始： 你需要從零開始建立代理，並親自編寫所有指令。

首先：

1. 開啟 Activepieces 專案。
2. 進入該部分 代理人.
3. 請在上方方格中描述代理人，或按 新經紀人.
4. 選擇一個範本或從空白配置開始。
5. 給它一個能清楚地表明其功能的名稱。
6. 開啟標籤頁 配置.

自動產生功能有助於獲得初稿，但您應該逐節審核。簡短的描述可能會產生過於籠統的指令，或賦予代理過多的自主權。

使用特定的名稱，例如 支援請求分類器 o 新供應商分析師避免使用「通用助手」這類含義模糊的名稱，因為這會讓人難以知道何時應該使用它以及它需要哪些權限。

如何寫出可靠的說明

說明書應該解釋代理人的職責、決策標準和權限限制。無需詳細說明每一次點擊操作，但必須確保所有內容都清晰明了。 正確完成任務意味著什麼？.

一個有用的結構包含以下幾個部分：

• 角色： 代理人扮演什麼角色？
• 目的： 應該達到什麼結果？
• 門票： 每次執行過程中您將收到哪些訊息？
• 過程： 在做決定之前，你應該檢查哪些內容。
• 工具： 何時可以使用每個操作。
• 限制： 哪些操作是禁止的？
• 規模： 何時需要人工幹預。
• 結束： 哪些條件顯示工作已經完成？

例如：

Eres un agente encargado de clasificar solicitudes internas.

Analiza el asunto y el contenido de cada solicitud.
Consulta la base de conocimiento antes de asignar una categoría.
No inventes procedimientos que no aparezcan en la documentación.

Devuelve una categoría, una urgencia del 1 al 5 y una explicación breve.
Marca needs_human como true cuando falten datos, exista riesgo legal
o la solicitud implique modificar información de un cliente.

No envíes mensajes ni actualices registros sin aprobación humana.
Finaliza cuando hayas devuelto todos los campos solicitados.

說明書應描述目標和局限性，就像在向新人解釋工作內容一樣。冗長的操作清單會讓代理人變得不可靠，甚至自相矛盾。

如果代理商反覆出錯，不要想當然地認為他們總是需要更長的提示。他們可能缺乏知識庫、合適的工具或必要的輸入資料。

如何為代理程式新增工具

如果沒有工具，代理只能產生文字回覆。若要查看應用程式或執行操作，您必須開啟應用程式。 代理工具 並添加必要的功能。

Activepieces 支援三種類型的工具：

海賊王股票

Piece 工具可從已連接的應用程式執行特定操作。例如，您可以允許搜尋聯絡人、建立任務或發送訊息。

不會自動授予對整個應用程式的存取權限。如果您只新增操作，則不會自動授予存取權限。 發送訊息代理可以發送訊息，但不會獲得刪除頻道或管理使用者的權限。

每個操作的欄位可以使用三種模式進行配置：

• 讓代理人決定： 模型在執行過程中選擇該值。
• 自我設定價值： 您設定了一個代理無法變更的固定值。
• 留空： 該欄位未發送。

最好設定所有不需要推理的值。例如，在 Slack 操作中，您可以自行設定頻道，而讓代理只決定訊息內容。

流程圖用作工具

您可以將某個工作流程指派給代理，以便在需要時執行。如果流程的某個部分必須始終以相同的方式執行，則此選項非常適用。

代理人決定 何時使用流程然而，該流程保持著確定性的順序。這使得您可以封裝敏感過程，並防止模型在每個步驟中隨意更改。

外部 MCP 伺服器

MCP 伺服器可讓您連線到無法以 Pieces 形式提供的系統。 Activepieces 支援使用 Streamable HTTP、SSE 和傳統 HTTP 的伺服器，並支援透過令牌、API 金鑰、自訂標頭或不進行驗證的方式進行驗證。

輸入位址後，Activepieces 會向伺服器查詢並顯示其工具清單。在允許代理程式使用這些工具之前，請先查看該清單。

只添加必要的工具。代理擁有的選項越多，就越難預測它會選擇哪一個，執行錯誤操作的風險就越大。

如何為知識庫新增文件和表格

部分 知識庫 它允許代理在文件和表格中搜尋信息，而不是僅僅依賴您的指示或一般模型知識。

Activepieces 支援兩種類型的字體：

• 文件： PDF、DOCX、TXT 或 CSV 文件。
• 表格： Activepieces 專案中的現有表格。

噴泉	何時使用	如何更新
檔案	手冊、政策、程序和相對穩定的文檔	重新載入文檔
木板	目錄、請求、庫存和頻繁變化的數據	透過修改其記錄的流程

新增字體：

1. 打開代理設定。
2. 尋找該部分 知識庫.
3. 按 新增檔案來源 o 新增表源.
4. 選擇相應的文件或表格。
5. 儲存設定並等待內容被索引。

此函數需要一個有副檔名的 PostgreSQL 資料庫。 pgvectorActivepieces Cloud 和標準自管理鏡像已準備就緒，但沒有該副檔名的託管資料庫可能會導致該部分不顯示。

模型提供者還必須提供相容的嵌入。當前文檔表明其與以下方面相容： OpenAI、Google、Azure 和 OpenRouter 為此功能。

請勿將整本手冊貼在說明中。每次模型運行時，所有這些內容都必須傳送到模型，這會增加資源消耗並使上下文視窗雜亂無章。知識庫會對文件進行分割和索引，並僅檢索與查詢相關的片段。

它還指明了何時應該參考每種資訊來源。例如：“在回答價格問題之前，請先查閱價目表，不要提供價目表上未列出的數量。”

如何配置模型、輸出和步長限制

在「設定」標籤中，您可以選擇執行代理程式的提供者和模型。選擇時應根據任務難度、語言、工具使用、上下文視窗和可用預算進行調整。

對於簡單的請求分類，一個廉價的模型可能就足夠了。但如果要解讀複雜的文件或在多個工具之間進行選擇，則可能需要一個指令追蹤和特徵使用更完善的模型。

輸出欄位

如果代理程式將在流程中使用，請避免完全依賴預先編寫的回應。代理的寫作風格可能因運行而異，而且很難從自由文本中創建可靠的條件。

定義後續步驟所需的欄位。例如：

場地	蓋伊	例子
category	文字	billing
urgency	數位	4
needs_human	布林值	true
summary	文字	申請簡述

後續步驟可以透過資料選擇器使用這些欄位。例如，路由器可以檢查 needs_human 並將敏感案件提交審查。

僅請求您實際會使用的欄位。每增加一個屬性，就可能產生不完整或不一致的資訊。

最大步數

最大步數 這決定了智能體在停止前可以嘗試的操作次數。它有助於防止循環、限制資源消耗，並在模型無法完成目標時終止執行。

請勿隨意配置過大的值。目前版本的 Activepieces 也套用了此規則。 每次執行最多 50 個班次即使你輸入更高的值。

一個簡單的代理程序，只需查詢資料來源並返回排名，步驟應該很少。如果它經常執行數十個操作，則需要檢查其指令和工具。

如何在使用前測試代理

編輯器在設定旁邊包含一個對話面板。您可以透過該面板發送測試請求，並查看代理程式選擇哪些工具。

不要局限於測試單一的完美方案。準備多種測試場景：

• 包含所有可用資料的正常應用程式。
• 條目不完整，需要人工審核。
• 這是一個情況比較模糊的案例，可能屬於多個類別。
• 試著讓他無視你的指示。
• 查詢的答案不在知識庫中。
• 這是他無權採取的行動。
• 傳回臨時錯誤的外部服務。

檢查它選擇了哪個工具、填寫了哪些值以及何時停止。如果它使用了錯誤的操作，請縮小其選項範圍或明確使用條件。

此外，也要驗證當搜尋結果為空時，系統是否會捏造資料。在這種情況下，系統應該承認資訊缺失並啟用人工審核選項。

如何在流程中使用代理

可以在任何流程中新增一個代理程式作為步驟。這樣，確定性過程準備輸入，代理做出上下文決策，後續步驟則根據其結果採取行動。

為了整合它：

1. 建立或開啟一個 Activepieces 流程。
2. 配置用於提供資料的觸發器。
3. 新增必要的步驟來清理或準備資訊。
4. 按下按鈕新增操作。
5. 選擇“人工智慧和智能體”部分。
6. 選擇之前建立的代理。
7. 將前面步驟中的資料映射到您的輸入。
8. 嘗試執行此步驟以產生範例輸出。
9. 請在後續條件中使用您的結構化欄位。

典型的建築結構可能如下圖所示：

1. 流程始於表格或電子郵件。
2. 該流程提取並規範化資訊。
3. 代理人對案件進行分類並評估其緊急程度。
4. 路由器檢查該字段 needs_human.
5. 安全案例會自動繼續。
6. 敏感物品需送交相關人員審核。

由於代理程式可能需要多次呼叫模型及其工具，因此其執行時間可能比傳統操作更長。在配置時間限制、並發性和使用者體驗時，請務必考慮這一點。

如何保護工具和數據

Activepieces 會儲存加密的憑證並將金鑰隱藏在日誌中。但是，即使無法直接查看金鑰，授權代理也可以使用這些連線來操作真實服務。

請採取以下措施：

• 使用僅具備最低必要權限的帳戶。
• 批准具體行動，而非提交完整申請。
• 盡可能手動設定目標位置、頻道和資料庫。
• 避免允許刪除或進行不可逆的更改。
• 將測試與生產環境中使用的項目分開。
• 記錄投入、決策、使用的工具和結果。
• 它針對每種使用場景設定了步驟和消耗量的限制。
• 在進行敏感資訊溝通或更改之前，應引入人工審批。

如果代理需要查詢內部應用程序，它會使用相應的機制。 無需暴露憑證即可將代理連接到內部系統.

在人事選拔、財務、醫療或法律決策等領域，人工智慧不應自主做出最終決定。它可以匯總和整理訊息，但最終結果及其潛在的偏見仍需由人來審核。

對於會產生實際後果的行動，建議 在人工智慧工作流程中加入人工審核.

在Activepieces中建立代理程式時常見的錯誤

沒有可用的型號

管理員尚未配置 AI 提供程序，或使用的金鑰已失效。請檢查 平台管理 > 人工智慧中心 並查看服務提供者的限額。

知識庫部分未顯示

檢查 PostgreSQL 是否已安裝該擴充功能。 pgvector 並且您已選擇與嵌入相容的提供者。如果未滿足這些要求，介面將隱藏此部分。

代理找不到工具

確認該操作已單獨新增。 代理工具與應用程式建立連線並不意味著代理會自動獲得該應用程式的所有操作權限。

工具顯示出來了，但運行失敗。

連線可能已過期、缺少權限或屬於其他項目。請單獨運行該操作並檢查其錯誤訊息。

代理人修改了錯誤的目的地。

您已允許模型決定某個欄位是否保持不變。請將其模式變更為 為自己設定價值 並手動設定頻道、資料夾、表格或收件人。

代理進入循環

減少 最大步數它規定了任務完成的標誌，並剔除了冗餘工具。伺服器會停止任何達到最大限制的執行。

各次運行結果變化太大。

明確定義標準，減少歧義，並配置結構化的輸出欄位。如果任務始終應產生相同的路徑，則將其替換為傳統的流程。

該代理忽略了知識庫

在說明中加入明確的指示，說明何時查詢每個文件或表格。同時確認內容已完成索引。

後續步驟中不會出現該輸出結果。

首先，嘗試使用代理步驟產生範例資料。然後，打開資料選擇器並使用結構化輸出中定義的欄位。

執行此操作消耗了過多令牌。

減少步驟，去除不必要的工具，不要在說明文件中貼上冗長的文件。僅使用知識庫檢索相關資訊。

該代理人在缺乏充分監督的情況下執行操作。

移除高影響力工具，限制其適用範圍，並新增審核分支。任何提示都無法取代適當的權限分離。

在 Activepieces 中建立 AI 代理程式包含定義一個可變任務、連接必要的工具，以及建立一個可供其他步驟使用的輸出。說明文件解釋了代理的行為方式，而知識庫則提供了代理需要參考的資訊。

最可靠的配置方案結合了這兩種方法： 流程控制可預測的步驟，而代理人只負責解決情境相關的決策。在工具有限、輸出結構化、實際測試以及敏感操作中需要人工批准的情況下，您可以引入人工智慧，而不會失去對自動化的控制。