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

n8n AI agent 的定義，以及與 chain 的差異

n8n AI agent 是一個單獨的 AI Agent 節點，並在其上連接子節點：一個聊天模型、一個以上的工具，以及選用的記憶體。你以自然語言描述目標，模型會決定要呼叫哪些工具，以及呼叫順序，直到能夠產生回答。以下內容都是圍繞這個概念的設定。

chain 的運作方式相反。在 Basic LLM Chain 中，你決定執行步驟，模型只負責產生文字。在 agent 中，模型決定執行步驟，因此相同問題今天可能只需要呼叫模型一次，明天卻可能需要呼叫 9 次。這項差異會影響本指南中的每一項設定。如果你對這個迴圈還不熟悉，尤其是不熟悉其概念而不只是 n8n 功能，建議先手動撰寫一次，再將它組裝成節點。因為節點會隱藏你在本指南其餘部分需要持續分析的確切流程。

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

在信任本指南中的任何欄位名稱前，請先確認你的版本，因為 n8n 經常變更 AI 節點。

docker compose exec n8n n8n --version

Version 1.82.0 已將 agent-type 設定標記為 deprecated，改用 Tools Agent。舊版 v1 節點仍保留此設定；n8n 文件指出，該節點版本預計在 n8n 3.0 移除。

步驟 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 的 Claude Console 中建立憑證，依序開啟 Settings 和 API keys。金鑰只會顯示一次。Console 也會要求你在建立金鑰時選擇到期日。無人值守的代理程式會在金鑰到期當天停止運作，因此請將到期日記錄在容易查看的位置。對於無人值守的代理程式，請使用限定於某個 workspace 的 service account key，讓請求不必另外指定 workspace header。

API 使用量會依 token 計費。計費方式取決於你的 Claude 方案，截至 31 October 2026 為止。Max、Ultra 和 Team 方案包含每月 API 額度：Max 為 $100、Ultra 為 $200，Team 則提供最高 $500 的共用額度。你可以在 Max 或 Ultra 的 Settings > Billing，或 Team 的 Organization settings > Billing 中，將 Console organization 連結至方案以申請額度。你不需要在 Console 中新增付款方式。新訂閱者加入方案 7 天後即可申請額度。未使用的額度會在每個計費週期結束時到期；年繳方案則每月到期。內含額度用完後，請求會繼續使用已購買的額度；啟用 auto-reload 後可自動購買更多額度，採發票計費的 organization 則會為超額使用量付費。預付費 organization 沒有剩餘額度時，請求會停止。API 使用量不會計入 Claude 方案費用。Free、Pro 和 Enterprise 方案不包含每月 API 額度，因此這些方案的 API 費用會與訂閱費分開計算。

請以代理程式為單位選擇模型，而不是以公司為單位。只使用一項工具、查找資料後回報結果的代理程式，使用 Haiku 即可正常執行。目前版本 Haiku 5.5 的價格截至 12 October 2026 為每 1 million 個輸入 token $0.10、每 1 million 個輸出 token $0.50；如果請求的 prompt 超過 100,000 個 token，價格會提高為 $0.50 和 $2.50。較長的記憶視窗與大型工具結果都可能使請求超過這個門檻。代理程式使用多項工具並且必須跨工具規劃時，請改用 Sonnet。你要避免的是：便宜模型錯誤呼叫工具 4 次，成本反而高於昂貴模型正確呼叫 1 次。

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

n8n 文件中有一項容易忽略的限制：子節點中的運算式永遠會以第一個輸入項目為解析對象，不會逐項解析。請將逐項運算式放在根節點的 prompt 欄位中。

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

開啟 AI Agent 節點。Source for Prompt (User Message) 參數有兩項設定。

• Connected Chat Trigger Node 會接收名為 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：為代理程式提供一個工具

n8n 的文件指出，您必須將至少一個工具子節點連接至 AI Agent 節點，但目前的節點程式碼（版本 3.1）只有在缺少聊天模型時才會拒絕執行。無論如何，請先從一個工具開始，因為一個可正常運作的工具，比四個設定了一半的工具更能提供資訊；沒有工具的代理程式，只是成本更高的 chain。

將 HTTP Request 節點連接至代理程式的 Tool 連接器。請按照設定一般 HTTP Request 節點的方式進行設定，然後先從 shell 測試該 endpoint。

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

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

工具的 Description 欄位不是提供同事閱讀的文件。模型會在判斷工具是否相關時，同時讀取這個欄位、工具名稱及參數 schema。請以明確句子說明會傳回的內容：「以 JSON 格式傳回一個受監控服務目前為 up 或 down 的狀態，以及停機持續時間。」

若要讓模型填入部分請求，請使用 $fromAI() expression。這只能在連接至 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 endpoint，您可以將這個節點指向 自己的 SearXNG 執行個體，而不是付費搜尋 API，但必須將它傳回的每個頁面都視為不受信任的文字，因為這些文字現在已經位於您的提示中。

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

如果沒有記憶體子節點，每則訊息都會從空白狀態開始。加入 Simple Memory 子節點，以保存近期對話。

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

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

n8n 以 queue mode 執行時，Simple Memory 不適用於作用中的正式工作流程，因為它會將歷史記錄儲存在以工作流程和工作階段 ID 為 key 的處理程序本機 singleton Map 中，而 worker 不會共用這段記憶體。在 queue mode 執行個體上，請改用 Postgres Chat Memory 子節點，並將其指向主要處理程序與 worker 都能連線的資料庫。

步驟 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。一次迭代就是一次模型呼叫；模型會在其中要求使用工具，或返回最終答案。工具結果會回傳給下一次呼叫。因此，單次代理程式執行並不只包含 1 次 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 edition 上運作，而且 需要付費金鑰的功能大多與團隊和治理有關。完整說明請參閱 在長時間運作的 VPS 上控管 AI agent 成本。以下 4 項設定最具效果。

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

反覆調整期間，請取消發佈 workflow，或至少記住目前正式執行的是哪個版本。含有 Schedule Trigger 的已發佈 workflow 會持續執行你上次發佈的版本，而不是畫面上的草稿，因為 n8n 會將你的修改保留為草稿，直到你再次發佈為止。

FAQ

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

先檢查連接器。AI Agent 節點需要一個 chat model 子節點。若未連接，節點會在發出任何 API 呼叫前停止，並顯示「Please connect a model to the Chat Model input」。n8n 的文件也將至少一個工具子節點列為必要項目。因此，如果模型已連接但節點仍拒絕執行，請連接一個工具，即使是功能簡單的工具也可以，然後再次執行。

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

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

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

因為模型會決定執行步驟數。每次迭代都會重新傳送目前為止的完整對話內容，包括先前的工具輸出。因此，執行 4 次迭代的工作流程，會針對 4 次呼叫的輸入與輸出 token 計費。Max Iterations 設定迭代次數上限，而 Return Intermediate Steps 會顯示特定執行實際使用的步驟數。

我的記憶在編輯器中正常，但在正式環境中無法運作。哪裡變了？

請確認執行個體是否使用 queue mode。Simple Memory 會將歷史記錄儲存在以工作流程 ID 和工作階段 ID 為索引、僅限單一程序使用的 singleton Map 中。不同 worker 程序不會共用這些資料。請改用 Postgres Chat Memory 子節點，將歷史記錄儲存在所有 worker 共用的資料庫中。