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

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

AI agent trong n8n là một node AI Agent duy nhất, có các sub-node gắn vào nó: 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ỉ tạo phần văn bản. 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 9 lần vào ngày mai. Khác biệt này chi phối mọi thiết lập trong guide. Nếu đây là ý tưởng mới đối với bạn, không chỉ là một feature của n8n, bạn nên tự viết một lần trước khi lắp ghép bằng các node. Node che khuất 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 guide.

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

Hãy kiểm tra version trước khi tin tưở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

Tên trong guide này khớp với bản stable hiện tại của n8n tính đến tháng 7 năm 2026. Từ version 1.82.0, mọi AI Agent node đều chạy dưới dạng Tools Agent, vì vậy dropdown chọn loại agent cũ không còn tồn tại.

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 cho model

Thả một node AI Agent vào canvas. n8n 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 Anthropic 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. API usage được tính phí theo token và tách biệt với mọi gói đăng ký Claude.ai, vì vậy tài khoản phải thiết lập billing trước lần chạy đầu tiên.

Chọn model cho từng agent, không chọn theo toàn bộ công ty. Một agent chỉ dùng một tool để tra cứu và báo cáo kết quả có thể chạy tốt trên Haiku. Tính đến July 2026, Haiku có mức giá $1 cho mỗi million input tokens và $5 cho mỗi million output tokens. 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à model rẻ gọi sai tool 4 lần, khiến chi phí cao hơn model đắt gọi đúng tool 1 lần.

Đặt Maximum Number of Tokens trong options của sub-node. Tùy chọn này giới hạn độ dài mỗi response do model tạo ra. Nếu giữ nguyên giá trị mặc định lớn, một lần chạy bị nhầm có thể tạo ra câu trả lời rất dài và làm phát sinh chi phí tương ứng.

Có một điểm trong tài liệu n8n thường gây nhầm lẫn: các expression bên trong sub-node luôn được resolve dựa trên item input đầu tiên, không resolve theo từng item. Đặt các 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ố Prompt có hai tùy chọn.

• Take from previous node automatically chờ một field đầu vào có tên chatInput. Đây là lựa chọn phù hợp khi đặt 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 sau Schedule Trigger hoặc node Webhook.

Khi đặt node Webhook ở trước, body của POST nằm trong $json.body, vì vậy 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

Một node AI Agent không có sub-node tool sẽ từ chối chạy. Hãy bắt đầu với một tool, vì một tool hoạt động đầy đủ sẽ cung cấp nhiều thông tin hơn 4 tool mới cấu hình được một phần.

Nối một node HTTP Request vào connector Tool của agent. Cấu hình node này đúng như khi cấu hình một node HTTP Request thông thường, sau đó 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 HTML đăng nhập, agent cũng sẽ fail. Lỗi khi đó có thể trông giống lỗi của model, nhưng thực tế lại là lỗi URL hoặc authentication. Hãy sửa lỗi trong shell, không sửa trong node.

Trường Description của tool không phải tài liệu dành cho đồng nghiệp. Đây là thông tin duy nhất model đọc khi quyết định tool này có liên quan hay không. Hãy viết một câu nêu rõ 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 nối với node AI Agent. Nó 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, type và defaultValue tùy chọn. Key phải có từ 1 đến 64 ký tự, chỉ 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 đủ hơn có dạng như sau.

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

Key chỉ là 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, input data và kết quả của các tool khác. Trong workflow chat, model có thể chỉ hỏi người dùng.

Web search thường là tool thứ hai. Vì nó cũng chỉ là một HTTP endpoint, bạn có thể trỏ chính node này đến SearXNG instance của bạn thay vì một paid search API, với điều kiện coi mọi trang mà nó trả về là text 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 trống. Gắn một sub-node Simple Memory để lưu cuộc trò chuyện gần đây.

Sub-node này có 2 tham số. Session Key xác định đây là cuộc trò chuyện nào, vì vậy 2 người dùng có key khác nhau sẽ có lịch sử riêng. Context Window Length xác định số interaction trước đó được nạp lại vào prompt.

Context Window Length không chỉ điều chỉnh chất lượng mà còn ảnh hưởng trực tiếp đến chi phí, 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 có nhiều message, window bằng 20 có nghĩa là bạn trả phí cho cùng các message ban đầu 20 lần.

Simple Memory không hoạt động đúng trong workflow production đang chạy khi n8n dùng queue mode, vì lịch sử nằm trong data riêng của workflow thay vì một shared store. Trên instance chạy queue mode, hãy dùng sub-node Postgres Chat Memory và trỏ nó đến 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ô hạn và điều gì dừng nó

Trong Options còn có Max Iterations, mặc định là 10. Một iteration gồm một lần gọi model và một kết quả tool được đưa trở lại context. 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 toàn bộ conversation đang ngày càng dài 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 thành trong 2 iteration. Giới hạn 3 hoặc 4 sẽ biến vòng lặp không dừng thành một lần fail rõ ràng trong execution list.

Trong lúc 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 phân biệt được trường hợp “model không hề gọi tool” với trường hợp “tool không trả về dữ liệu hữu ích”. Hãy tắt tùy chọn này trước khi đưa vào vận hành, vì các step đó chỉ gây nhiễu cho end user.

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

docker compose logs -f n8n

Ngăn agent chạy nền tiêu tốn tài nguyên mà không được chú ý

Một agent đứng sau Chat Trigger có người thật theo dõi, và người đó sẽ dừng agent khi câu trả lời có vẻ sai. Agent đứng sau Schedule Trigger thì không có ai giám sát. Ở đây, thứ bạn cần theo dõi là chi phí model, không phải 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 liên quan đến team và governance. Phần hướng dẫn đầy đủ nằm trong Kiểm soát chi phí AI agent trên VPS luôn bật. Bốn setting quyết định phần lớn hiệu quả kiểm soát chi phí.

• Giới hạn Maximum Number of Tokens trên sub-node model để không có một response nào 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 từ tool ở mức nhỏ. Một tool trả về blob JSON dài 4,000 dòng sẽ đưa toàn bộ nội dung đó vào model call tiếp theo, rồi tiếp tục đưa vào mọi call 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 5 phút sẽ kích hoạt 288 lần mỗi ngày. Một lần chạy tốn bao nhiêu thì lấy con số đó nhân lên.

Deactivate workflow trong thời gian bạn chỉnh sửa và kiểm thử. Workflow đang active với Schedule Trigger sẽ tiếp tục chạy theo phiên bản mà n8n đã lưu, không phải lúc nào cũng là phiên bản đang hiển thị trên màn hình của bạn.

FAQ

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

Node AI Agent cần một sub-node chat model và ít nhất một sub-node tool. Node có model nhưng không có tool sẽ fail trước khi thực hiện bất kỳ API call nào. 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 ở đâ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, nên mô tả như "HTTP Request" không cho biết tool áp dụng khi nào. Viết lại mô tả để nêu dữ liệu nào được trả về và tool 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 tốn 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 hiện có, bao gồm output của các tool trước đó. Vì vậy, một lần chạy mất 4 iteration có thể tốn nhiều hơn 4 lần một API call đơn lẻ. Max Iterations đặt giới hạn tối đa cho số bước. Return Intermediate Steps cho biết lần chạy đó thực tế đã 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?

Kiểm tra xem instance có chạy ở queue mode hay không. Simple Memory lưu history trong execution data của chính workflow. Dữ liệu này không tồn tại khi execution được chuyển cho một worker process riêng, nên workflow production đang chạy sẽ mất history. Thay bằng sub-node Postgres Chat Memory. Sub-node này lưu history trong database mà mọi worker đều dùng chung.