如何在自架 VPS 上建立 n8n AI agent

n8n AI agent 的用途，以及與 chain 的差異

n8n AI agent 是一個單獨的 AI Agent node，並連接多個 sub-node：一個 chat model、一個以上的工具，以及選用的 memory。您以一般語言說明目標，模型會決定要呼叫哪些工具，以及呼叫順序，直到能夠產生回答為止。以下所有內容都是圍繞這個概念的設定。

chain 的運作方式則相反。在 Basic LLM Chain 中，您決定執行步驟，模型只負責產生文字。在 agent 中，模型會決定執行步驟。因此，相同問題今天可能只需呼叫模型 1 次，明天卻可能呼叫 9 次。本指南中的每項設定，都受到這項差異影響。

本指南假設 n8n 已在您管理的機器上，透過 HTTPS 執行。如果尚未完成，請先參閱 使用 Docker 自架 n8n 並設定正式憑證，因為您即將儲存的 API key 需要該指南要求建立的 encryption-key 備份。如需非 agent 的模式，包括 webhook 摘要器與排程分類器，請參閱 Claude 與 n8n 工作流程模式。

在採用本指南中的任何欄位名稱前，請先確認您的版本，因為 n8n 經常變更 AI nodes。

docker compose exec n8n n8n --version

本指南中的名稱符合截至 2026 年 7 月的 n8n current stable。自 version 1.82.0 起，每個 AI Agent node 都會以 Tools Agent 執行，因此舊版的 agent-type dropdown 已不存在。

步驟 1：選擇觸發方式

對話式代理程式請新增 Chat Trigger 節點。建置期間先關閉 Make Chat Publicly Available，讓只有編輯器中的聊天面板可以存取。代理程式完成並決定驗證方式後，再將其開啟。

Chat Trigger 會提供名為 chatInput 的欄位。步驟 3 會用到這個名稱，名稱設定錯誤是最常見的初始失敗原因。

若要執行無人值守的代理程式，請改用 Schedule Trigger 或 Webhook 節點。這兩者都不會產生 chatInput，因此需要自行撰寫提示。

步驟 2：模型憑證

在畫布上放置 AI Agent 節點。n8n 會立即在其下方顯示空白的 Chat Model 連接器。在該處附加 Anthropic Chat Model 子節點。

在 Anthropic Console 的 platform.claude.com 中建立憑證，依序開啟 Settings 和 API Keys。金鑰只會顯示一次。API 使用量按 token 計費，且與任何 Claude.ai 訂閱分開，因此帳戶必須先完成計費設定，才能首次執行。

請針對每個 agent 選擇模型，而不是為整間公司統一選擇模型。只使用一項工具、查詢資料後回報結果的 agent，使用 Haiku 即可正常運作。以 2026 年 7 月的價格為例，Haiku 每百萬個輸入 token 收費 $1，每百萬個輸出 token 收費 $5。當 agent 擁有多項工具，且必須規劃如何使用這些工具時，請改用 Sonnet。要避免的情況是：廉價模型連續 4 次呼叫錯誤的工具，成本反而高於昂貴模型正確呼叫工具 1 次。

在子節點的選項中設定 Maximum Number of Tokens。此設定會限制模型產生的每個回應長度。若保留較大的預設值，一次混亂的執行可能產生過長的回答，並因此產生額外費用。

n8n 文件中有一項容易忽略的限制：子節點內的運算式一律會根據第一個輸入項目解析，不會針對每個項目分別解析。請將逐項運算式放在根節點的提示欄位中。

步驟 3：代理程式收到的提示

開啟 AI Agent 節點。Prompt 參數有兩種設定。

• Take from previous node automatically 會讀取名為 chatInput 的輸入欄位。搭配 Chat Trigger 時，應選擇此設定。
• Define below 會顯示 Prompt (User Message) 欄位，您可以在其中輸入固定文字或運算式。搭配 Schedule Trigger 或 Webhook 節點時，應選擇此設定。

如果前方連接 Webhook 節點，POST 主體會位於 $json.body，因此提示欄位如下所示。

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

步驟 4：為代理程式提供一個工具

沒有工具子節點的 AI Agent 節點不會執行。先從一個工具開始，因為一個能正常運作的工具，比四個設定不完整的工具更能幫助你了解問題。

將 HTTP Request 節點連接到代理程式的 Tool 連接器。依照設定一般 HTTP Request 節點的方式完成設定，然後先從 shell 測試該端點。

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

如果該 curl 指令傳回錯誤或 HTML 登入頁面，代理程式也會失敗。錯誤訊息看起來可能像是模型問題，但實際上通常是 URL 或驗證問題。請先在 shell 中修正，不要在節點中處理。

工具的 Description 欄位不是寫給同事看的文件。模型只會依據這段內容判斷工具是否相關。請以簡單陳述說明會傳回的內容：「以 JSON 傳回一個受監控服務目前為 up 或 down 的狀態，以及服務中斷時間長度。」

若要讓模型填入請求的一部分，請使用 $fromAI() 運算式。這只能用於連接到 AI Agent 節點的工具，無法用於 Code 工具。

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

引數依序為 key，接著是選用的 description、type 與 defaultValue。鍵必須是長度 1 到 64 個字元的字串，且只能使用字母、數字、底線與連字號。類型必須是 string、number、boolean 或 json 其中之一，預設值為 string。較完整的呼叫方式如下。

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

鍵是提示，不是對現有資料的參照。$fromAI('service') 不會從任何位置讀取名為 service 的欄位。它會告訴模型「產生一個值，並將它命名為 service」，模型則會從對話、輸入資料及其他工具結果中尋找相符的值。在聊天工作流程中，模型也可能直接詢問使用者。

網頁搜尋通常是第二個工具。由於它只是另一個 HTTP 端點，因此你可以將同一個節點指向自己的 SearXNG 執行個體，而不是付費搜尋 API；但必須將它傳回的每個頁面視為不受信任的文字，因為這些內容現在已進入提示。

步驟 5：記憶體，以及代理程式為何會忘記

如果沒有記憶體子節點，每則訊息都會從零開始。連接 Simple Memory 子節點，即可保留最近的對話內容。

它有 2 個參數。Session Key 用來決定這是哪個對話，因此使用不同 key 的 2 位使用者會有各自獨立的歷史記錄。Context Window Length 則指定要將多少次先前的互動重新放入 prompt。

Context Window Length 不只是品質控制項，也是成本控制項，因為每次後續呼叫都會將記住的每一輪內容重新作為輸入 token 傳送。對於互動頻繁的代理程式而言，視窗設為 20 代表相同的早期訊息會被重複計費 20 次。

n8n 以 queue mode 執行時，Simple Memory 不適用於作用中的 production workflow，因為歷史記錄儲存在 workflow 自身的資料中，而不是共用儲存區。在 queue mode instance 上，請改用 Postgres Chat Memory 子節點，並將其指向 main process 與 workers 都能連線的資料庫。

步驟 6：系統訊息

開啟 agent 的 Options，並新增 System Message。工作說明應放在這裡，這也是整個工作流程中影響最大的一段文字。

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

「回答前一律先呼叫 status 工具」在這裡確實能發揮作用。沒有這項指示時，自認已經知道答案的模型可能會略過工具，直接依記憶回答；只要基礎架構發生變更，這種回答就會立即變成過度自信的錯誤資訊。

代理為何會循環，以及如何停止

Options 中還有 Max Iterations，預設值為 10。一次迭代包含一次模型呼叫，以及將一次工具結果饋送回內容。因此，單次代理執行不只是一次 API 呼叫，而是最多 10 次；每次呼叫都會將持續增長的完整對話作為輸入。

請調低此值。多數單一工具代理會在 2 次迭代內完成，而將上限設為 3 或 4 次，可讓失控循環轉為執行清單中可見的明確失敗。

進行偵錯時，請開啟 Return Intermediate Steps。最終輸出會包含代理沿途發出的工具呼叫，藉此判斷「模型從未呼叫工具」或「工具未回傳有用結果」。正式上線前請關閉此選項，因為這些步驟對終端使用者而言只是雜訊。

從 shell 觀察一次執行。

docker compose logs -f n8n

防止無人值守的 agent 在背景中持續耗用資源

Chat Trigger 後方的 agent 有人員監看。如果答案看起來不正確，該人員會停止它。Schedule Trigger 後方的 agent 則無人監看。這裡要監控的是模型使用量，而不是授權費用，因為 agent、tool 和 memory 節點都能在免費的 self-hosted 版本上運作，而 需要付費金鑰的功能大多與團隊和治理有關。完整說明請參閱 在持續運作的 VPS 上控制 AI agent 成本。這裡主要由 4 個設定發揮作用。

• 在 model 子節點上限制 Maximum Number of Tokens，讓單次回應無法執行太久。
• 將 Max Iterations 設為仍能完成工作所需的最小值。
• 維持 tool 回應精簡。若 tool 回傳 4,000 行的 JSON，全部內容會放入下一次 model 呼叫，並在同一次執行的後續每次呼叫中重複帶入。
• 先確認 agent 是否真的需要排程。每 5 分鐘執行一次的工作每天會觸發 288 次。單次執行的成本是多少，總成本就要乘以這個數字。

反覆測試期間請停用 workflow。啟用中的 workflow 搭配 Schedule Trigger 會持續依照 n8n 儲存的版本執行，而該版本不一定是畫面上目前顯示的版本。

FAQ

為什麼我的 AI Agent 節點拒絕執行？

AI Agent 節點需要一個 chat model 子節點，以及至少一個工具子節點。只有 model 而沒有工具的節點，會在發出任何 API 呼叫前失敗。附加一個工具，即使只是簡單工具，然後再次執行。

Agent 會回答，但從未呼叫我的工具。問題在哪裡？

幾乎總是工具的 Description 欄位有問題。模型會讀取這些描述來選擇工具，因此「HTTP Request」這類描述無法告訴模型工具何時適用。請改寫描述，說明工具會傳回哪些資料，以及在哪些情況下適合使用。接著在 System Message 中加入一行指示，要求 Agent 在回答前先呼叫該工具。

為什麼相同問題每次執行的費用都不同？

因為模型會決定執行步驟數。每次迭代都會重新傳送截至目前的完整對話，包括先前的工具輸出。因此，執行 4 次迭代的成本，會遠高於單次呼叫成本的 4 倍。Max Iterations 是迭代次數上限，Return Intermediate Steps 則會顯示特定執行實際使用的步驟數。

我的記憶在編輯器中有效，但在 production 中失效。發生了什麼變化？

請確認該 instance 是否以 queue mode 執行。Simple Memory 將歷史記錄儲存在 workflow 自身的執行資料中；這些資料在交由獨立 worker process 處理後無法保留，因此執行中的 production workflow 會遺失記憶。請改用 Postgres Chat Memory 子節點，將歷史記錄保存在所有 worker 共用的資料庫中。