如何在自己的 VPS 建立 n8n AI agent

n8n AI agent 是什麼，以及它與 chain 的差異

n8n AI agent 是單一的 AI Agent 節點，並連接子節點：一個聊天模型、一個以上的工具，以及選用的記憶體。您以一般語言說明目標，模型會決定要呼叫哪些工具，以及呼叫順序，直到能夠回答為止。以下所有內容都是圍繞這個概念的設定。

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

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

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

docker compose exec n8n n8n --version

本指南中的名稱符合截至 2026 年 7 月的 n8n 最新穩定版本。自版本 1.82.0 起，每個 AI Agent 節點都會以 Tools Agent 執行，因此舊版的 agent-type 下拉式選單已不存在。

步驟 1：選擇觸發方式

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

Chat Trigger 會傳遞名為 chatInput 的欄位給代理程式。步驟 3 會使用這個名稱；名稱錯誤是首次失敗最常見的原因。

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

步驟 2：模型憑證

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

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

請依每個 agent 選擇模型，而不是依公司統一選擇。只使用一項工具來查詢資料並回報結果的 agent，使用 Haiku 即可正常執行。以 2026 年 7 月的價格來看，Haiku 的輸入為每 1 million tokens $1，輸出為每 1 million tokens $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 格式回傳一項受監控服務目前的正常或異常狀態，以及中斷持續時間。」

若要讓模型填入要求的一部分，請使用 $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」，模型則會從對話、輸入資料和其他工具結果中尋找該值。在聊天工作流程中，模型也可能直接詢問使用者。

步驟 5：記憶體，以及 Agent 忘記內容的原因

如果沒有記憶體子節點，每則訊息都會從零開始。連接 Simple Memory 子節點，以保留近期對話。

它有 2 個參數。Session Key 用來決定對話身分，因此使用不同金鑰的 2 位使用者會取得分開的歷史記錄。Context Window Length 是要重新載入至提示中的先前互動數量。

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

當 n8n 以 queue mode 執行時，Simple Memory 無法在作用中的正式環境工作，因為歷史記錄儲存在工作流程本身的資料中，而不是共用儲存區。在 queue mode 執行個體上，請改用 Postgres Chat Memory 子節點，並將其指向主要程序與工作程序都能連線的資料庫。

步驟 6：System Message

開啟 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。一次迭代包含一次模型呼叫，以及將一次工具結果回傳至內容中。因此，單次代理程式執行並非只有 1 次 API 呼叫，而是最多 10 次；每次呼叫都會將持續增長的完整對話作為輸入。

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

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

從 shell 觀察執行過程。

docker compose logs -f n8n

防止無人代理程式在背景中悄悄消耗資源

Chat Trigger 後方的代理程式有人員監看，回答看起來不正確時，該人員會停止它。Schedule Trigger 後方的代理程式則無人監看。完整說明請參閱 永遠運作的 VPS 上的 AI 代理程式成本控管。這裡主要需要處理 4 項設定。

• 在模型子節點上限制 Maximum Number of Tokens，讓單次回應無法執行過久。
• 將 Max Iterations 設為仍能完成工作的最小值。
• 將工具回應維持在較小的大小。若工具傳回 4,000 行的 JSON 內容，全部內容都會放入下一次模型呼叫，並在同一次執行中放入之後的每次呼叫。
• 確認代理程式是否真的需要排程。每 5 分鐘執行一次的工作每天會觸發 288 次。單次執行的成本是多少，就將該數值乘以執行次數。

反覆測試時，請停用工作流程。啟用中的工作流程會持續根據 n8n 儲存的版本執行，而該版本不一定是畫面上目前顯示的版本。

FAQ

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

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

代理程式會回答，但從未呼叫我的工具。哪裡出錯？

幾乎都是工具的 Description 欄位有問題。模型會讀取這些描述來選擇工具，因此像「HTTP Request」這樣的描述，無法告訴模型工具適用的時機。請改寫描述，說明工具會傳回哪些資料，以及適用的情況。然後在 System Message 中新增一行，指示代理程式在回答前先呼叫該工具。

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

因為模型會決定執行步驟的數量。每次反覆執行都會重新傳送目前為止的完整對話內容，包括先前的工具輸出。因此，執行四個反覆步驟的成本，會遠高於單次呼叫成本的四倍。Max Iterations 會限制反覆執行的上限，而 Return Intermediate Steps 會顯示特定執行實際使用的步驟數。

我的記憶在編輯器中正常運作，但在正式環境中無法運作。發生了什麼變化？

請確認執行個體是否採用佇列模式。Simple Memory 會將歷史記錄儲存在工作流程本身的執行資料中。這些資料在交由獨立工作程序處理後無法保留，因此作用中的正式工作流程會遺失記憶。請改用 Postgres Chat Memory 子節點，將歷史記錄保存在每個工作程序共用的資料庫中。