Cara Membuat Agen AI n8n di VPS Sendiri

Apa itu agen AI n8n dan perbedaannya dengan chain

Agen AI n8n adalah satu node AI Agent dengan sub-node yang terpasang padanya: satu model chat, satu atau beberapa tool, dan memory opsional. Anda menyatakan tujuan dalam bahasa biasa, lalu model menentukan tool mana yang akan dipanggil dan dalam urutan apa sampai dapat memberikan jawaban. Semua hal di bawah ini adalah konfigurasi yang terkait dengan satu konsep tersebut.

Chain bekerja dengan cara sebaliknya. Dalam Basic LLM Chain, Anda menentukan langkah-langkahnya dan model hanya mengisi teks. Dalam agent, model menentukan langkah-langkahnya. Karena itu, pertanyaan yang sama dapat memerlukan satu pemanggilan model hari ini dan sembilan pemanggilan besok. Perbedaan ini menentukan setiap pengaturan dalam panduan ini.

Panduan ini mengasumsikan n8n sudah berjalan di balik HTTPS pada mesin yang Anda kendalikan. Jika belum, mulai dengan self-hosting n8n pada Docker dengan sertifikat yang valid, karena API key yang akan Anda simpan memerlukan backup encryption key yang diwajibkan oleh panduan tersebut. Untuk pola non-agent, seperti summarizer webhook dan classifier terjadwal, lihat pola workflow Claude dan n8n.

Periksa versi Anda sebelum mengandalkan nama field apa pun di sini, karena n8n sering mengubah node AI.

docker compose exec n8n n8n --version

Nama-nama dalam panduan ini sesuai dengan stable version terbaru n8n per July 2026. Sejak version 1.82.0, setiap node AI Agent berjalan sebagai Tools Agent, sehingga dropdown jenis agent yang lama sudah tidak tersedia.

Langkah 1: pilih pemicu

Untuk agen percakapan, tambahkan node Chat Trigger. Biarkan Make Chat Publicly Available tetap nonaktif selama proses pembuatan, sehingga hanya panel chat editor yang dapat mengaksesnya. Aktifkan opsi tersebut setelah agen selesai dan Anda telah menentukan autentikasinya.

Chat Trigger memberikan agen sebuah field bernama chatInput. Nama tersebut digunakan pada langkah 3. Kesalahan pada nama ini merupakan penyebab kegagalan pertama yang paling umum.

Untuk agen yang berjalan tanpa pengawasan, gunakan node Schedule Trigger atau Webhook. Keduanya tidak menghasilkan chatInput. Karena itu, Anda harus menulis prompt sendiri.

Langkah 2: kredensial model

Tambahkan node AI Agent ke canvas. n8n segera menampilkan konektor Chat Model yang kosong di bawahnya. Pasang sub-node Anthropic Chat Model pada konektor tersebut.

Buat kredensial dari Anthropic Console di platform.claude.com, melalui Settings lalu API Keys. Kunci tersebut hanya ditampilkan satu kali. Penggunaan API ditagihkan berdasarkan token dan terpisah dari langganan Claude.ai apa pun, sehingga akun harus menyiapkan penagihan sebelum proses pertama dijalankan.

Pilih model untuk setiap agent, bukan untuk seluruh perusahaan. Agent dengan satu tool yang mencari informasi lalu melaporkannya dapat berjalan baik menggunakan Haiku, yang per Juli 2026 tercantum dengan harga $1 per juta token input dan $5 per juta token output. Setelah agent memiliki beberapa tool dan harus merencanakan penggunaannya, beralihlah ke Sonnet. Masalah yang perlu dihindari adalah model murah yang memanggil tool yang salah sebanyak empat kali. Biayanya dapat melebihi model mahal yang memanggil tool yang benar satu kali.

Atur Maximum Number of Tokens pada opsi sub-node. Pengaturan ini membatasi panjang setiap respons yang dihasilkan model. Jika dibiarkan pada nilai default yang besar, satu proses yang gagal memahami konteks dapat menghasilkan jawaban yang sangat panjang dan menambah biaya.

Ada satu catatan dari dokumentasi n8n yang sering terlewat: expression di dalam sub-node selalu dievaluasi berdasarkan item input pertama, bukan berdasarkan setiap item. Letakkan expression per item pada field prompt di root node.

Langkah 3: prompt yang diterima agent

Buka node AI Agent. Parameter Prompt memiliki dua pengaturan.

• Take from previous node automatically mengharapkan field masuk bernama chatInput. Pilihan ini tepat jika node berada setelah Chat Trigger.
• Define below menampilkan field Prompt (User Message) untuk menulis teks statis atau expression. Pilihan ini tepat jika node berada setelah Schedule Trigger atau node Webhook.

Jika node Webhook berada sebelumnya, body POST masuk ke dalam $json.body, sehingga field prompt terlihat seperti berikut.

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.

Langkah 4: berikan satu tool kepada agent

Node AI Agent tanpa sub-node tool akan menolak untuk berjalan. Mulailah dengan satu tool, karena satu tool yang berfungsi memberi Anda lebih banyak informasi daripada empat tool yang baru dikonfigurasi sebagian.

Hubungkan node HTTP Request ke konektor Tool pada agent. Konfigurasikan node tersebut persis seperti node HTTP Request biasa, lalu uji endpoint itu dari shell terlebih dahulu.

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

Jika perintah curl tersebut mengembalikan error atau halaman login HTML, agent juga akan gagal. Pesan kegagalannya dapat terlihat seperti masalah model, padahal sebenarnya masalah URL atau autentikasi. Perbaiki masalah itu dari shell, bukan di node.

Field Description pada tool bukan dokumentasi untuk kolega Anda. Field ini adalah satu-satunya informasi yang dibaca model saat menentukan apakah tool tersebut relevan. Tulis deskripsi sebagai pernyataan langsung tentang hasil yang dikembalikan: "Mengembalikan status up atau down saat ini dan durasi downtime untuk satu service yang dipantau, dalam format JSON."

Untuk membiarkan model mengisi sebagian request, gunakan ekspresi $fromAI(). Ekspresi ini hanya berfungsi pada tool yang terhubung ke node AI Agent dan tidak berfungsi pada Code tool.

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

Argumennya adalah key, lalu description, type, dan defaultValue yang bersifat opsional. Key harus terdiri dari 1 hingga 64 karakter dan menggunakan huruf, digit, underscore, serta hyphen. Type harus berupa salah satu dari string, number, boolean, atau json, dan nilai default-nya adalah string. Contoh pemanggilan yang lebih lengkap terlihat seperti ini.

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

Key adalah petunjuk, bukan referensi ke data yang sudah ada. $fromAI('service') tidak membaca field bernama service dari mana pun. Ekspresi tersebut memberi tahu model, "hasilkan sebuah nilai dan beri nama service", lalu model mencari nilainya di dalam percakapan, data input, dan hasil tool lainnya. Dalam workflow chat, model dapat langsung menanyakannya kepada pengguna.

Web search biasanya menjadi tool kedua. Karena tool ini hanyalah endpoint HTTP lain, Anda dapat mengarahkan node yang sama ke instance SearXNG milik Anda sendiri, bukan ke API pencarian berbayar, asalkan setiap halaman yang dikembalikannya diperlakukan sebagai teks tidak tepercaya yang kini berada di dalam prompt Anda.

Langkah 5: memory dan alasan agent melupakan

Tanpa sub-node memory, setiap pesan dimulai dari awal. Hubungkan sub-node Simple Memory untuk menyimpan percakapan terbaru.

Sub-node ini memiliki dua parameter. Session Key menentukan percakapan yang sedang digunakan, sehingga dua pengguna dengan key yang berbeda mendapatkan riwayat terpisah. Context Window Length menentukan jumlah interaksi sebelumnya yang dimuat kembali ke dalam prompt.

Context Window Length memengaruhi biaya dan kualitas. Setiap interaksi yang diingat dikirim ulang sebagai input token pada setiap pemanggilan berikutnya. Pada agent yang banyak berinteraksi, window sebesar 20 membuat Anda membayar pesan awal yang sama sebanyak dua puluh kali.

Simple Memory tidak berfungsi dalam workflow produksi aktif ketika n8n berjalan dalam queue mode, karena riwayat disimpan dalam data workflow itu sendiri, bukan dalam shared store. Pada instance yang menggunakan queue mode, gunakan sub-node Postgres Chat Memory dan arahkan ke database yang dapat dijangkau oleh proses utama dan workers.

Langkah 6: Pesan Sistem

Buka Options milik agent, lalu tambahkan System Message. Di sinilah deskripsi tugas ditetapkan, dan teks ini memberikan pengaruh terbesar dalam alur kerja.

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.

Instruksi "Always call the status tool before answering" benar-benar berfungsi di sini. Tanpa instruksi tersebut, model yang mengira sudah mengetahui jawabannya akan melewati tool itu dan menjawab berdasarkan memorinya. Jawaban tersebut dapat terdengar yakin, tetapi langsung menjadi salah ketika infrastruktur Anda berubah.

Mengapa agent berulang, dan apa yang menghentikannya

Di bagian Options juga terdapat Max Iterations, yang secara default bernilai 10. Satu iterasi terdiri atas satu pemanggilan model dan satu hasil tool yang dimasukkan kembali ke dalam konteks. Jadi, satu eksekusi agent bukan hanya satu pemanggilan API, melainkan hingga sepuluh pemanggilan. Setiap pemanggilan membawa seluruh percakapan yang terus bertambah sebagai input.

Turunkan nilainya. Sebagian besar agent dengan satu tool selesai dalam dua iterasi. Batas 3 atau 4 mengubah loop yang tidak berhenti menjadi kegagalan yang jelas dan dapat dilihat dalam daftar eksekusi.

Saat melakukan debugging, aktifkan Return Intermediate Steps. Output akhir kemudian menyertakan pemanggilan tool yang dilakukan agent selama proses. Dengan begitu, Anda dapat membedakan antara "model tidak pernah memanggil tool" dan "tool tidak mengembalikan hasil yang berguna". Nonaktifkan kembali opsi ini sebelum sistem digunakan dalam produksi karena langkah-langkah tersebut tidak diperlukan oleh pengguna akhir.

Pantau eksekusi dari shell.

docker compose logs -f n8n

Mencegah agent tanpa pengawasan menghabiskan biaya secara diam-diam

Agent di belakang Chat Trigger memiliki manusia yang mengawasinya, dan manusia tersebut menghentikannya ketika jawabannya terlihat salah. Agent di belakang Schedule Trigger tidak diawasi siapa pun. Yang dipantau di sini adalah penggunaan model, bukan biaya lisensi, karena node agent, tool, dan memory semuanya berjalan pada edisi self-hosted gratis, sedangkan fitur yang memerlukan kunci berbayar umumnya berkaitan dengan tim dan tata kelola. Penjelasan lengkapnya tersedia di pengendalian biaya AI agent pada VPS yang selalu aktif. Empat pengaturan paling berperan dalam hal ini.

• Batasi Maximum Number of Tokens pada sub-node model agar tidak ada satu respons pun yang berjalan terlalu lama.
• Atur Max Iterations ke jumlah terkecil yang masih dapat menyelesaikan tugas.
• Jaga agar respons tool tetap kecil. Tool yang mengembalikan blob JSON sepanjang 4,000 baris akan memasukkan seluruh isinya ke pemanggilan model berikutnya, lalu ke setiap pemanggilan setelahnya dalam run yang sama.
• Tanyakan apakah agent memang memerlukan jadwal. Job yang berjalan setiap lima menit akan dijalankan 288 kali sehari. Berapa pun biaya satu run, kalikan angka tersebut dengan 288.

Nonaktifkan workflow selama proses iterasi. Workflow aktif dengan Schedule Trigger tetap berjalan menggunakan versi yang disimpan n8n, dan versi tersebut tidak selalu sama dengan versi yang tampil di layar Anda.

FAQ

Mengapa node AI Agent saya menolak untuk dieksekusi?

Node AI Agent memerlukan sub-node model chat dan setidaknya satu sub-node tool. Node yang memiliki model tetapi tidak memiliki tool akan gagal sebelum melakukan panggilan API. Hubungkan satu tool, meskipun tool tersebut sederhana, lalu jalankan kembali.

Agent memberikan jawaban, tetapi tidak pernah memanggil tool saya. Apa masalahnya?

Hampir selalu penyebabnya adalah kolom Description pada tool. Model memilih tool dengan membaca deskripsinya. Deskripsi seperti "HTTP Request" tidak menjelaskan kapan tool tersebut digunakan. Tulis ulang deskripsi agar menjelaskan data yang dikembalikan dan situasi saat tool tersebut berguna. Kemudian, tambahkan baris pada System Message yang menginstruksikan agent untuk memanggil tool tersebut sebelum memberikan jawaban.

Mengapa pertanyaan yang sama memerlukan biaya berbeda pada setiap eksekusi?

Karena model menentukan jumlah langkah yang digunakan. Pada setiap iterasi, seluruh percakapan hingga saat itu dikirim ulang, termasuk output tool sebelumnya. Karena itu, eksekusi yang memerlukan empat iterasi biayanya jauh lebih besar daripada empat kali biaya satu panggilan. Max Iterations menetapkan batas atas jumlah iterasi tersebut. Return Intermediate Steps menunjukkan jumlah langkah yang benar-benar digunakan oleh suatu eksekusi.

Memori saya berfungsi di editor, tetapi tidak di produksi. Apa yang berubah?

Periksa apakah instance berjalan dalam mode antrean. Simple Memory menyimpan riwayat dalam data eksekusi workflow itu sendiri. Data tersebut tidak bertahan ketika workflow diserahkan kepada proses worker terpisah. Akibatnya, workflow produksi yang aktif kehilangan riwayatnya. Ganti dengan sub-node Postgres Chat Memory, yang menyimpan riwayat dalam database yang digunakan bersama oleh setiap worker.