Tự dựng AI agent n8n trên VPS với Claude và tool HTTP

n8n AI agent là gì và khác chain ở điểm nào

Một n8n AI agent là một node AI Agent duy nhất, có các sub-node gắn vào: một chat model, một hoặc nhiều tool và memory tùy chọn. Bạn nêu mục tiêu bằng ngôn ngữ tự nhiên, rồi model quyết định cần gọi tool nào và theo thứ tự nào cho đến khi có thể trả lời. Toàn bộ phần bên dưới là cấu hình xoay quanh ý tưởng đó.

Chain hoạt động theo cách ngược lại. Trong Basic LLM Chain, bạn quyết định các bước và model chỉ điền nội dung. Trong agent, model quyết định các bước. Vì vậy, cùng một câu hỏi có thể chỉ tốn một lần gọi model hôm nay nhưng tốn chín lần vào ngày mai. Khác biệt này chi phối mọi setting trong hướng dẫn này. Nếu đây là khái niệm mới đối với bạn, không chỉ là một tính năng của n8n, bạn nên tự viết một lần bằng tay trước khi lắp nó bằng các node. Node sẽ ẩn chính xác phần mà bạn sẽ phải phân tích trong phần còn lại của hướng dẫn.

Phần này giả định n8n đã chạy phía sau HTTPS trên một máy do bạn quản lý. Nếu chưa, hãy bắt đầu với tự host n8n trên Docker bằng chứng chỉ hợp lệ, vì API key bạn sắp lưu cần bản backup encryption key mà hướng dẫn đó yêu cầu. Với các pattern không dùng agent như webhook summarizer và scheduled classifier, xem các pattern workflow Claude và n8n.

Hãy kiểm tra version trước khi tin dùng bất kỳ tên field nào ở đây, vì n8n thường xuyên thay đổi các AI node.

docker compose exec n8n n8n --version

Version 1.82.0 đã deprecated setting agent-type để thay bằng Tools Agent. Các node v1 legacy vẫn còn setting này; tài liệu n8n cho biết version node này sẽ bị xóa trong n8n 3.0.

Bước 1: chọn trigger

Với conversational agent, thêm node Chat Trigger. Tắt Make Chat Publicly Available trong khi xây dựng để chỉ panel chat của editor có thể truy cập. Bật tùy chọn này khi agent đã hoàn tất và bạn đã quyết định cách xác thực.

Chat Trigger cung cấp cho agent một field có tên chatInput. Tên này sẽ được dùng ở bước 3. Nhập sai tên là nguyên nhân phổ biến nhất khiến lần chạy đầu tiên thất bại.

Với agent chạy không cần giám sát, dùng node Schedule Trigger hoặc Webhook. Cả hai đều không tạo chatInput, vì vậy bạn phải tự viết prompt.

Bước 2: thông tin xác thực của model

Thả node AI Agent lên canvas. n8n sẽ ngay lập tức hiển thị một connector Chat Model trống bên dưới node này. Gắn một sub-node Anthropic Chat Model vào đó.

Tạo credential trong Claude Console tại platform.claude.com, vào Settings rồi chọn API keys. Key chỉ được hiển thị một lần. Console cũng yêu cầu bạn chọn thời hạn khi tạo key. Agent chạy không giám sát sẽ dừng hoạt động vào ngày key hết hạn, vì vậy hãy ghi ngày đó ở nơi bạn dễ thấy. Với agent chạy không giám sát, hãy dùng service account key có scope trong một workspace để request không cần thêm workspace header.

API usage được tính phí theo token. Cách thanh toán phụ thuộc vào Claude plan của bạn, theo thông tin có hiệu lực ngày 31 October 2026. Các plan Max, Ultra và Team có monthly API credits: $100 cho Max, $200 cho Ultra và tối đa $500 dùng chung cho Team. Bạn nhận credit bằng cách liên kết một Console organization với plan trong Settings > Billing trên Max hoặc Ultra, hoặc Organization settings > Billing trên Team. Bạn không cần thêm payment method trong Console. Subscriber mới có thể nhận credit sau 7 ngày sử dụng plan. Credit chưa dùng sẽ hết hạn vào cuối mỗi billing cycle, hoặc hết hạn hằng tháng với annual plan. Khi included credits hết, request tiếp tục dùng purchased credits. Auto-reload có thể mua thêm credit, còn organization được lập hóa đơn sẽ bị tính phí cho phần usage vượt mức. Request sẽ dừng khi prepaid organization không còn credit. API usage không bao giờ được tính vào Claude plan của bạn. Các plan Free, Pro và Enterprise không có monthly API credits, nên API trên các plan này được tính phí riêng với subscription.

Chọn model theo từng agent, không chọn theo toàn bộ company. Một agent chỉ dùng một tool để tra cứu và trả kết quả sẽ chạy tốt trên Haiku. Phiên bản hiện tại, Haiku 5.5, có mức giá $0.10 cho mỗi triệu input token và $0.50 cho mỗi triệu output token tính đến ngày 12 October 2026. Mức giá tăng lên $0.50 và $2.50 đối với request có prompt vượt quá 100,000 token. Một memory window dài và tool result lớn có thể khiến request vượt ngưỡng này. Khi agent có nhiều tool và phải lập kế hoạch sử dụng chúng, hãy chuyển sang Sonnet. Vấn đề cần tránh là một model rẻ gọi sai tool 4 lần, khiến chi phí cao hơn một model đắt gọi đúng tool 1 lần.

Đặt Maximum Number of Tokens trong options của sub-node. Giá trị này giới hạn độ dài của mỗi response do model tạo ra. Nếu để giá trị mặc định lớn, một lần chạy bị nhầm có thể tạo ra response rất dài và khiến bạn phải trả phí cho phần đó.

Có một lưu ý trong tài liệu n8n thường khiến mọi người mắc lỗi: expression bên trong sub-node luôn được resolve theo item đầu vào đầu tiên, không resolve theo từng item. Hãy đặt expression theo từng item trong các trường prompt của root node.

Bước 3: prompt mà agent nhận được

Mở node AI Agent. Tham số Source for Prompt (User Message) có 2 tùy chọn.

• Connected Chat Trigger Node chờ một field đầu vào có tên chatInput. Đây là lựa chọn phù hợp khi đặt phía sau Chat Trigger.
• Define below hiển thị field Prompt (User Message) để bạn nhập văn bản tĩnh hoặc expression. Đây là lựa chọn phù hợp khi đặt phía sau Schedule Trigger hoặc node Webhook.

Khi đặt node Webhook ở phía trước, body của request POST nằm trong $json.body, nên field prompt sẽ có dạng sau.

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.

Bước 4: cung cấp cho agent một tool

Tài liệu của n8n cho biết bạn phải kết nối ít nhất một tool sub-node với node AI Agent, mặc dù code hiện tại của node này (version 3.1) chỉ từ chối chạy khi không có chat model. Dù thế nào, hãy bắt đầu với một tool, vì một tool hoạt động tốt sẽ cung cấp nhiều thông tin hơn bốn tool cấu hình dở dang, còn agent không có tool thì chỉ là một chain tốn chi phí cao hơn.

Kết nối node HTTP Request với connector Tool của agent. Cấu hình node này chính xác như một node HTTP Request thông thường, rồi kiểm tra endpoint đó từ shell trước.

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

Nếu lệnh curl đó trả về lỗi hoặc một trang đăng nhập HTML, agent cũng sẽ fail. Thông báo lỗi có thể khiến bạn tưởng đây là lỗi của model, trong khi nguyên nhân thực sự là URL hoặc vấn đề xác thực. Hãy sửa lỗi trong shell, không sửa trong node.

Trường Description của tool không phải là tài liệu dành cho đồng nghiệp. Model đọc trường này cùng với tên tool và schema của tham số để quyết định tool này có phù hợp hay không. Hãy viết một câu đơn giản mô tả dữ liệu trả về: "Trả về trạng thái up hoặc down hiện tại và thời gian downtime của một service được monitor, dưới dạng JSON."

Để model điền một phần của request, hãy dùng expression $fromAI(). Expression này chỉ hoạt động trong các tool được kết nối với node AI Agent và không hoạt động trong Code tool.

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

Các đối số lần lượt là key, sau đó là description tùy chọn, type và defaultValue. Key phải dài từ 1 đến 64 ký tự và chỉ được dùng chữ cái, chữ số, dấu gạch dưới và dấu gạch ngang. Type phải là một trong string, number, boolean hoặc json, và mặc định là string. Một lời gọi đầy đủ có dạng như sau.

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

Key chỉ là một gợi ý, không phải tham chiếu đến dữ liệu hiện có. $fromAI('service') không đọc một field có tên service từ bất kỳ đâu. Nó yêu cầu model "tạo một giá trị và gọi giá trị đó là service", rồi model tìm giá trị này trong conversation, dữ liệu đầu vào và kết quả của các tool khác. Trong workflow chat, model có thể chỉ cần hỏi người dùng.

Web search thường là tool thứ hai. Vì đây chỉ là một HTTP endpoint khác, bạn có thể trỏ chính node này đến SearXNG instance của riêng bạn thay vì một search API trả phí, miễn là bạn coi mọi trang mà nó trả về là văn bản không đáng tin cậy và hiện đã nằm trong prompt của bạn.

Bước 5: memory và lý do agent quên

Không có sub-node memory, mỗi message đều bắt đầu từ trạng thái rỗng. Hãy gắn một sub-node Simple Memory để lưu cuộc hội thoại gần đây.

Nó có 2 tham số. Session Key xác định đây là cuộc hội thoại nào, vì vậy 2 người dùng có key khác nhau sẽ có history riêng. Context Window Length xác định có bao nhiêu interaction trước đó được đưa lại vào prompt.

Context Window Length vừa là nút điều chỉnh chi phí vừa là nút điều chỉnh chất lượng, vì mỗi turn được ghi nhớ sẽ được gửi lại dưới dạng input token trong mọi lần gọi sau đó. Với một agent hoạt động nhiều, window là 20 có nghĩa là bạn trả phí cho cùng những message ban đầu 20 lần.

Simple Memory không hoạt động trong workflow production đang chạy khi n8n dùng queue mode, vì nó lưu history trong một Map singleton cục bộ của process, được đánh index bằng workflow ID và session ID, còn các worker không dùng chung vùng memory đó. Trên instance dùng queue mode, hãy dùng sub-node Postgres Chat Memory thay thế và trỏ nó đến một database mà cả process chính và các worker đều có thể truy cập.

Bước 6: System Message

Mở Options của agent và thêm System Message. Đây là nơi chứa mô tả công việc và là phần văn bản có tác động lớn nhất trong workflow.

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.

Câu “Always call the status tool before answering” thực sự có tác dụng tại đây. Nếu không có câu này, model nghĩ rằng nó đã biết câu trả lời sẽ bỏ qua tool và trả lời từ memory. Cách này sẽ sai một cách chắc chắn ngay khi hạ tầng của bạn thay đổi.

Vì sao agent lặp và điều gì ngăn vòng lặp

Trong Options còn có Max Iterations, mặc định là 10. Một iteration là một lần gọi model. Model có thể yêu cầu gọi tool hoặc trả về câu trả lời cuối; kết quả của tool được đưa vào lần gọi tiếp theo. Vì vậy, một lần chạy agent không chỉ là một API call mà có thể gồm tối đa 10 lần gọi. Mỗi lần gọi đều gửi kèm toàn bộ conversation đang dài dần làm input.

Hãy giảm giá trị này. Hầu hết agent chỉ dùng một tool đều hoàn tất trong 2 iteration. Đặt giới hạn là 3 hoặc 4 sẽ biến vòng lặp không dừng thành một lỗi rõ ràng mà bạn có thể thấy trong execution list.

Trong khi debug, hãy bật Return Intermediate Steps. Khi đó output cuối sẽ bao gồm các lần gọi tool mà agent đã thực hiện. Nhờ vậy, bạn có thể phân biệt trường hợp “model không hề gọi tool” với trường hợp “tool không trả về thông tin hữu ích”. Hãy tắt lại trước khi đưa vào production, vì các bước này chỉ gây nhiễu cho người dùng cuối.

Hãy theo dõi một lần chạy từ shell.

docker compose logs -f n8n

Ngăn agent chạy không giám sát tiêu tốn chi phí âm thầm

Một agent phía sau Chat Trigger có người theo dõi và người đó sẽ dừng agent khi câu trả lời có vẻ sai. Một agent phía sau Schedule Trigger thì không có ai giám sát. Ở đây, bạn cần theo dõi chi phí model thay vì chi phí license, vì các node agent, tool và memory đều hoạt động trên bản self-hosted miễn phí, còn các tính năng cần paid key chủ yếu là tính năng dành cho team và governance. Phần trình bày đầy đủ nằm trong Kiểm soát chi phí AI agent trên VPS luôn bật. Bốn thiết lập sau xử lý phần lớn vấn đề.

• Giới hạn Maximum Number of Tokens trên sub-node model để không response nào có thể chạy quá dài.
• Đặt Max Iterations ở mức nhỏ nhất nhưng vẫn hoàn thành được tác vụ.
• Giữ response của tool ở mức nhỏ. Một tool trả về JSON blob dài 4,000 dòng sẽ đưa toàn bộ dữ liệu đó vào lần gọi model tiếp theo, rồi vào mọi lần gọi sau đó trong cùng một lần chạy.
• Xem agent có thực sự cần schedule hay không. Một job chạy mỗi năm phút sẽ được kích hoạt 288 lần mỗi ngày. Lấy chi phí của một lần chạy rồi nhân với con số đó.

Unpublish workflow trong khi bạn lặp lại quy trình, hoặc ít nhất hãy nhớ version nào đang live. Một workflow đã publish với Schedule Trigger tiếp tục chạy version bạn publish gần nhất, không phải draft đang hiển thị trên màn hình, vì n8n giữ các chỉnh sửa của bạn trong draft cho đến khi bạn publish lại.

FAQ

Vì sao node AI Agent từ chối thực thi?

Trước tiên, hãy kiểm tra các connector. Node AI Agent cần một sub-node chat model. Nếu không có, node sẽ dừng với lỗi "Please connect a model to the Chat Model input" trước khi thực hiện bất kỳ API call nào. Tài liệu của n8n cũng yêu cầu ít nhất một sub-node tool. Vì vậy, nếu model đã được kết nối nhưng node vẫn từ chối chạy, hãy gắn một tool, dù chỉ là tool đơn giản, rồi chạy lại.

Agent trả lời nhưng không bao giờ gọi tool của tôi. Lỗi nằm ở đâu?

Gần như luôn là do trường Description của tool. Model chọn tool bằng cách đọc các phần mô tả này. Vì vậy, mô tả như "HTTP Request" không cho model biết tool áp dụng khi nào. Hãy viết lại mô tả để nêu rõ tool trả về dữ liệu gì và hữu ích trong tình huống nào. Sau đó, thêm một dòng vào System Message, yêu cầu agent gọi tool đó trước khi trả lời.

Vì sao cùng một câu hỏi nhưng mỗi lần chạy lại có chi phí khác nhau?

Vì model quyết định số bước cần thực hiện. Mỗi iteration gửi lại toàn bộ conversation đến thời điểm đó, bao gồm cả output của các tool trước đó. Vì vậy, một lần chạy mất 4 iteration sẽ tính phí token input và output của cả 4 lần gọi. Max Iterations đặt giới hạn tối đa cho số bước này. Return Intermediate Steps cho biết một lần chạy cụ thể đã sử dụng bao nhiêu bước.

Memory hoạt động trong editor nhưng không hoạt động trong production. Điều gì đã thay đổi?

Hãy kiểm tra instance có chạy ở queue mode hay không. Simple Memory lưu lịch sử trong một singleton Map nội bộ của process, với key là workflow ID và session ID. Các worker process riêng biệt không dùng chung Map này. Hãy thay bằng sub-node Postgres Chat Memory. Sub-node này lưu lịch sử trong database mà mọi worker đều dùng chung.