Cara Membuat Agen AI n8n di VPS Sendiri

Apa itu agen AI n8n dan perbedaannya dari chain

Agen AI n8n adalah satu node AI Agent dengan subnode yang terhubung: satu model chat, satu atau beberapa tool, dan memori opsional. Anda menyatakan tujuan dalam bahasa biasa, lalu model menentukan tool yang harus dipanggil dan urutannya hingga dapat memberikan jawaban. Semua hal di bawah ini membahas konfigurasi di sekitar satu gagasan 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 menjadi dasar setiap pengaturan dalam panduan ini. Jika konsep loop tersebut masih baru bagi Anda, bukan hanya fiturnya di n8n, sebaiknya tulis sendiri sekali sebelum menyusunnya dari node. Dengan demikian, Anda dapat memahami bagian persis yang akan dianalisis dalam sisa panduan ini, karena node menyembunyikannya.

Panduan ini mengasumsikan n8n sudah berjalan di belakang HTTPS pada mesin yang Anda kendalikan. Jika belum, mulai dengan self-hosting n8n di 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, yaitu peringkas webhook dan pengklasifikasi terjadwal, lihat pola workflow Claude dan n8n.

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

docker compose exec n8n n8n --version

Versi 1.82.0 tidak lagi menggunakan pengaturan jenis agent dan menggantinya dengan Tools Agent. Node v1 lama masih memiliki pengaturan tersebut; dokumentasi n8n menyatakan bahwa penghapusan versi node itu dilakukan pada n8n 3.0.

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 akan langsung menampilkan konektor Chat Model yang kosong di bawahnya. Pasang sub-node Anthropic Chat Model pada konektor tersebut.

Buat kredensial dari Claude Console di platform.claude.com, melalui Settings, lalu API keys. Kunci hanya ditampilkan satu kali. Console juga meminta Anda memilih masa berlaku saat membuat kunci. Agent tanpa pengawasan akan berhenti bekerja pada hari ketika kuncinya kedaluwarsa. Karena itu, catat tanggal tersebut di tempat yang mudah dilihat. Untuk agent tanpa pengawasan, gunakan kunci service account yang dibatasi pada workspace agar request tidak memerlukan header workspace terpisah.

Penggunaan API ditagihkan per token. Metode pembayarannya bergantung pada paket Claude Anda, per 31 October 2026. Paket Max, Ultra, dan Team mencakup kredit API bulanan: $100 pada Max, $200 pada Ultra, dan hingga $500 dalam kumpulan kredit pada Team. Anda dapat mengklaimnya dengan menautkan organisasi Console ke paket melalui Settings > Billing pada Max atau Ultra, atau Organization settings > Billing pada Team. Anda tidak perlu menambahkan metode pembayaran di Console. Pelanggan baru dapat mengklaim kredit setelah 7 hari berlangganan paket tersebut. Kredit yang tidak digunakan kedaluwarsa pada akhir setiap siklus penagihan, atau setiap bulan pada paket tahunan. Setelah kredit yang termasuk dalam paket habis, request tetap menggunakan kredit yang dibeli. Fitur auto-reload dapat membeli kredit tambahan, dan organisasi yang menerima invoice akan ditagih atas penggunaan berlebih. Request berhenti ketika organisasi prabayar tidak lagi memiliki kredit. Penggunaan API tidak pernah ditagihkan ke paket Claude Anda. Paket Free, Pro, dan Enterprise tidak mencakup kredit API bulanan. Pada paket tersebut, API ditagihkan secara terpisah dari langganan.

Pilih model untuk setiap agent, bukan untuk seluruh perusahaan. Agent dengan satu tool yang hanya mencari informasi lalu melaporkannya dapat berjalan baik pada Haiku. Versi saat ini, Haiku 5.5, tercantum dengan harga $0.10 per satu juta token input dan $0.50 per satu juta token output per 12 October 2026. Harganya naik menjadi $0.50 dan $2.50 untuk request apa pun yang prompt-nya melebihi 100,000 token. Jendela memori yang panjang dan hasil tool yang besar dapat menyebabkan batas ini terlampaui. Setelah agent memiliki beberapa tool dan harus menyusun rencana penggunaan di antaranya, beralihlah ke Sonnet. Masalah yang perlu dihindari adalah model murah yang memanggil tool yang salah sebanyak empat kali. Biayanya dapat lebih besar daripada 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 eksekusi yang keliru dapat menghasilkan jawaban yang sangat panjang dan meningkatkan tagihan Anda.

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

Langkah 3: prompt yang diterima agent

Buka node AI Agent. Parameter Source for Prompt (User Message) memiliki dua pengaturan.

• Connected Chat Trigger Node mengharapkan field masuk bernama chatInput. Pilihan ini tepat jika digunakan setelah Chat Trigger.
• Define below menampilkan field Prompt (User Message) untuk menulis teks statis atau expression. Pilihan ini tepat jika digunakan setelah Schedule Trigger atau node Webhook.

Jika node Webhook ditempatkan di depan, body POST berada di bawah $json.body, sehingga field prompt terlihat seperti ini.

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

Dokumentasi n8n menyebutkan bahwa Anda harus menghubungkan setidaknya satu sub-node tool ke node AI Agent, meskipun kode node saat ini (versi 3.1) hanya menolak berjalan jika tidak ada chat model. Gunakan satu tool terlebih dahulu, karena satu tool yang berfungsi memberikan lebih banyak informasi daripada empat tool yang baru dikonfigurasi sebagian. Agent tanpa tool pada dasarnya hanya sebuah chain dengan biaya lebih tinggi.

Hubungkan node HTTP Request ke konektor Tool pada agent. Konfigurasikan node tersebut sama persis seperti node HTTP Request biasa, lalu uji endpoint tersebut 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 merupakan masalah URL atau autentikasi. Perbaiki masalah tersebut dari shell, bukan pada node.

Kolom Description pada tool bukan dokumentasi untuk rekan kerja Anda. Model membaca kolom tersebut bersama nama tool dan skema parameternya saat menentukan apakah tool ini relevan. Tulis pernyataan sederhana tentang hasil yang dikembalikan: "Mengembalikan status up atau down saat ini dan durasi downtime untuk satu service yang dipantau, dalam format JSON."

Untuk memungkinkan model mengisi sebagian permintaan, 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, kemudian description opsional, type, dan defaultValue. Key harus memiliki panjang 1 hingga 64 karakter dan hanya menggunakan huruf, digit, garis bawah, serta tanda hubung. Type harus berupa salah satu dari string, number, boolean, atau json, dengan nilai default string. Contoh pemanggilan yang lebih lengkap terlihat seperti berikut.

{{ $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. Key tersebut memberi tahu model, "hasilkan sebuah nilai dan beri nama service", lalu model mencari nilai tersebut di dalam percakapan, data input, dan hasil tool lainnya. Dalam workflow chat, model dapat langsung menanyakannya kepada pengguna.

Pencarian web biasanya menjadi tool kedua. Karena tool tersebut juga hanya berupa endpoint HTTP, Anda dapat mengarahkan node yang sama ke instance SearXNG milik Anda sendiri, bukan API pencarian berbayar, dengan syarat setiap halaman yang dikembalikannya diperlakukan sebagai teks yang tidak tepercaya dan kini berada di dalam prompt Anda.

Langkah 5: memori dan alasan agent melupakan percakapan

Tanpa sub-node memori, setiap pesan dimulai dari awal. Tambahkan 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 dimasukkan kembali ke dalam prompt.

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

Simple Memory tidak berfungsi dalam workflow produksi aktif ketika n8n berjalan dalam queue mode, karena sub-node ini menyimpan riwayat dalam Map singleton lokal proses yang menggunakan ID workflow dan session sebagai key, sedangkan worker tidak berbagi memori tersebut. Pada instance yang menggunakan queue mode, gunakan sub-node Postgres Chat Memory dan arahkan ke database yang dapat dijangkau oleh proses utama dan worker.

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 agen melakukan loop, dan apa yang menghentikannya

Di bagian Options juga terdapat Max Iterations, yang secara default bernilai 10. Satu iterasi adalah satu pemanggilan model, yang dapat meminta tools atau mengembalikan jawaban akhir; hasil tools diteruskan ke pemanggilan berikutnya. Jadi, satu eksekusi agen bukan satu pemanggilan API, melainkan hingga sepuluh pemanggilan, dan setiap pemanggilan membawa seluruh percakapan yang terus bertambah sebagai input.

Kurangi nilainya. Sebagian besar agen dengan satu tool selesai dalam dua iterasi. Batas 3 atau 4 iterasi dapat 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 agen selama proses tersebut. Dengan demikian, Anda dapat membedakan antara “model tidak pernah memanggil tool” dan “tool tidak mengembalikan hasil yang berguna”. Nonaktifkan kembali opsi ini sebelum sistem digunakan di lingkungan produksi karena langkah-langkah tersebut hanya menjadi informasi yang 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 balik Chat Trigger memiliki manusia yang mengawasinya, dan manusia tersebut akan menghentikannya jika jawabannya tampak salah. Agent di balik Schedule Trigger tidak diawasi. Yang perlu 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 memang memerlukan kunci berbayar sebagian besar berkaitan dengan tim dan tata kelola. Pembahasan lengkap tersedia di Mengendalikan biaya AI agent pada VPS yang selalu aktif. Empat pengaturan berikut paling berpengaruh.

• Batasi Maximum Number of Tokens pada sub-node model agar tidak ada satu respons pun yang berjalan terlalu panjang.
• Tetapkan 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 proses yang sama.
• Pertimbangkan apakah agent memang memerlukan jadwal. Job yang berjalan setiap lima menit akan dipicu 288 kali sehari. Berapa pun biaya satu proses, kalikan biaya tersebut dengan jumlah itu.

Batalkan publikasi workflow selama proses iterasi, atau setidaknya catat versi mana yang sedang aktif. Workflow yang telah dipublikasikan dengan Schedule Trigger akan terus menjalankan versi terakhir yang Anda publikasikan, bukan draft yang tampil di layar, karena n8n menyimpan perubahan Anda sebagai draft sampai Anda memublikasikannya kembali.

FAQ

Mengapa node AI Agent saya menolak untuk dijalankan?

Periksa konektor terlebih dahulu. Node AI Agent memerlukan sub-node chat model. Tanpa sub-node tersebut, node berhenti dengan pesan "Please connect a model to the Chat Model input" sebelum melakukan panggilan API. Dokumentasi n8n juga menyatakan bahwa setidaknya satu sub-node tool diperlukan. Jadi, jika model sudah terhubung tetapi node masih menolak dijalankan, hubungkan satu tool, meskipun tool tersebut sederhana, lalu jalankan kembali.

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

Hampir selalu masalahnya ada pada kolom Description milik tool. Model memilih tool dengan membaca deskripsi tersebut. Jadi, deskripsi seperti "HTTP Request" tidak menjelaskan kapan tool itu berlaku. Tulis ulang deskripsi tersebut agar menjelaskan data yang dikembalikan dan situasi penggunaannya. Kemudian, tambahkan baris pada System Message yang menginstruksikan agent untuk memanggil tool tersebut sebelum memberikan jawaban.

Mengapa biaya untuk pertanyaan yang sama berbeda pada setiap eksekusi?

Karena model menentukan jumlah langkah yang diperlukan. Pada setiap iterasi, seluruh percakapan hingga saat itu dikirim kembali, termasuk output tool sebelumnya. Jadi, eksekusi yang memerlukan empat iterasi akan membebankan token input dan output untuk keempat panggilan tersebut. Max Iterations menetapkan batas atasnya, sedangkan Return Intermediate Steps menunjukkan jumlah langkah yang benar-benar digunakan dalam eksekusi tertentu.

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

Periksa apakah instance berjalan dalam queue mode. Simple Memory menyimpan riwayat dalam Map singleton lokal-proses yang menggunakan workflow dan session ID sebagai kunci. Proses worker yang terpisah tidak berbagi Map tersebut. Ganti dengan sub-node Postgres Chat Memory, yang menyimpan riwayat dalam database yang digunakan bersama oleh semua worker.