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 ke node tersebut: satu model chat, satu atau beberapa alat, dan memori opsional. Anda menyatakan tujuan dalam bahasa biasa, lalu model menentukan alat mana yang akan dipanggil dan urutannya hingga dapat memberikan jawaban. Semua hal di bawah ini adalah konfigurasi untuk gagasan tersebut.

Chain bekerja dengan cara sebaliknya. Dalam Basic LLM Chain, Anda menentukan langkah-langkahnya dan model hanya menghasilkan teks. Dalam agen, 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 belakang HTTPS pada mesin yang Anda kendalikan. Jika belum, mulai dengan meng-host sendiri n8n di Docker dengan sertifikat yang valid, karena API key yang akan Anda simpan memerlukan cadangan encryption key yang diwajibkan oleh panduan tersebut. Untuk pola non-agen, seperti 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

Nama-nama dalam panduan ini sesuai dengan versi stabil terbaru n8n pada Juli 2026. Sejak versi 1.82.0, setiap node AI Agent berjalan sebagai Tools Agent, sehingga dropdown jenis agen yang lama sudah tidak ada.

Langkah 1: pilih pemicu

Untuk agen percakapan, tambahkan node Chat Trigger. Biarkan Make Chat Publicly Available tetap nonaktif selama Anda membangun agen, 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 ini penting pada langkah 3. Kesalahan pada nama tersebut merupakan penyebab kegagalan awal yang paling umum.

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

Langkah 2: kredensial model

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

Buat kredensial melalui Anthropic Console di platform.claude.com, buka Settings, lalu API Keys. Kunci hanya ditampilkan satu kali. Penggunaan API ditagihkan berdasarkan token dan terpisah dari langganan Claude.ai apa pun. Karena itu, akun harus sudah memiliki penagihan sebelum eksekusi pertama.

Pilih model untuk setiap agen, bukan untuk seluruh perusahaan. Agen dengan satu alat yang hanya 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 agen memiliki beberapa alat dan harus merencanakan penggunaannya, gunakan Sonnet. Masalah yang ingin Anda hindari adalah model murah yang memanggil alat yang salah sebanyak empat kali. Biayanya dapat melebihi model mahal yang memanggil alat yang benar satu kali.

Atur Maximum Number of Tokens di 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 menambah biaya.

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

Langkah 3: prompt yang diterima agen

Buka node AI Agent. Parameter Prompt memiliki dua pengaturan.

• Take from previous node automatically mengharapkan kolom masuk bernama chatInput. Ini merupakan pilihan yang tepat jika digunakan setelah Chat Trigger.
• Define below menampilkan kolom Prompt (User Message) untuk menulis teks statis atau ekspresi. Ini merupakan pilihan yang tepat jika digunakan setelah Schedule Trigger atau node Webhook.

Jika terdapat node Webhook di depannya, isi POST akan berada di bawah $json.body, sehingga kolom prompt akan 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 alat kepada agen

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

Hubungkan node HTTP Request ke konektor Tool milik agen. Konfigurasikan node tersebut 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 kesalahan atau halaman login HTML, agen juga akan gagal. Pesan kegagalannya dapat terlihat seperti masalah model, padahal sebenarnya merupakan masalah URL atau autentikasi. Perbaiki masalah tersebut dari shell, bukan di node.

Kolom Description pada alat bukan dokumentasi untuk rekan kerja Anda. Kolom tersebut adalah satu-satunya informasi yang dibaca model saat menentukan apakah alat ini relevan. Tulis pernyataan sederhana tentang hasil yang dikembalikan: "Mengembalikan status aktif atau tidak aktif saat ini serta durasi waktu henti untuk satu layanan yang dipantau, dalam format JSON."

Untuk memungkinkan model mengisi sebagian permintaan, gunakan ekspresi $fromAI(). Ekspresi ini hanya berfungsi pada alat yang terhubung ke node AI Agent. Ekspresi ini tidak berfungsi pada alat Code.

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

Argumennya adalah key, lalu description, type, dan defaultValue yang bersifat opsional. Kunci harus terdiri dari 1 hingga 64 karakter, menggunakan huruf, angka, garis bawah, dan tanda hubung. Jenisnya adalah salah satu dari string, number, boolean, atau json, dan nilai bawaannya adalah string. Pemanggilan yang lebih lengkap terlihat seperti berikut.

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

Kunci tersebut adalah petunjuk, bukan referensi ke data yang sudah ada. $fromAI('service') tidak membaca kolom bernama service dari mana pun. Ekspresi tersebut memberi tahu model, "hasilkan nilai dan beri nama service", lalu model mencari nilai tersebut melalui percakapan, data input, dan hasil alat lainnya. Dalam alur kerja chat, model dapat langsung menanyakannya kepada pengguna.

Langkah 5: memori dan alasan agen melupakan

Tanpa sub-node memori, setiap pesan dimulai tanpa konteks. Lampirkan sub-node Simple Memory untuk menyimpan percakapan terbaru.

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

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

Simple Memory tidak berfungsi dalam workflow produksi aktif saat n8n berjalan dalam queue mode. Riwayat tersimpan di data workflow itu sendiri, bukan di penyimpanan bersama. Pada instance queue mode, gunakan sub-node Postgres Chat Memory dan arahkan ke database yang dapat diakses oleh proses utama dan worker.

Langkah 6: Pesan Sistem

Buka Options agen, lalu tambahkan System Message. Di sinilah deskripsi tugas ditulis. Bagian 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.

"Always call the status tool before answering" benar-benar berfungsi di sana. Tanpa instruksi tersebut, model yang mengira sudah mengetahui jawabannya akan melewati tool itu dan menjawab berdasarkan ingatan. Jawabannya akan keliru dengan penuh keyakinan begitu infrastruktur Anda berubah.

Mengapa agen terus 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 alat yang dikirim kembali ke konteks. Jadi, satu eksekusi agen bukan satu pemanggilan API, melainkan hingga sepuluh pemanggilan. Setiap pemanggilan membawa seluruh percakapan yang terus bertambah sebagai input.

Turunkan nilainya. Sebagian besar agen dengan satu alat selesai dalam dua iterasi. Batas 3 atau 4 giliran mengubah perulangan yang tidak berhenti menjadi kegagalan yang jelas dan dapat Anda lihat di daftar eksekusi.

Saat melakukan debugging, aktifkan Return Intermediate Steps. Output akhir kemudian mencakup pemanggilan alat yang dilakukan agen selama proses. Dengan demikian, Anda dapat membedakan antara "model tidak pernah memanggil alat" dan "alat tidak mengembalikan hasil yang berguna". Nonaktifkan kembali opsi ini sebelum sistem digunakan dalam produksi, karena langkah-langkah tersebut hanya mengganggu 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. Manusia tersebut menghentikannya jika jawabannya tampak salah. Agent di balik Schedule Trigger tidak diawasi. Penjelasan lengkap tersedia di Pengendalian biaya agent AI pada VPS yang selalu aktif. Empat pengaturan berikut menangani sebagian besar kebutuhan ini.

• Batasi Maximum Number of Tokens pada sub-node model. Dengan demikian, tidak ada satu respons pun yang dapat berjalan terlalu lama.
• Atur Max Iterations ke jumlah terkecil yang masih dapat menyelesaikan tugas.
• Batasi ukuran respons tool. Tool yang mengembalikan blob JSON sepanjang 4,000 baris akan memasukkan seluruh data tersebut ke pemanggilan model berikutnya, lalu ke setiap pemanggilan setelahnya dalam eksekusi yang sama.
• Tanyakan apakah agent benar-benar memerlukan jadwal. Job yang berjalan setiap lima menit akan dipicu 288 kali sehari. Berapa pun biaya satu eksekusi, kalikan biaya tersebut dengan jumlah itu.

Nonaktifkan workflow selama proses iterasi. Workflow aktif dengan Schedule Trigger terus berjalan menggunakan versi yang telah 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 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 masalahnya ada pada kolom Description tool. Model memilih tool dengan membaca deskripsinya. Deskripsi seperti "HTTP Request" tidak menjelaskan kapan tool tersebut berlaku. Tulis ulang deskripsi agar menjelaskan data yang dikembalikan dan situasi saat data 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 diperlukan. Setiap iterasi mengirim ulang seluruh percakapan hingga saat itu, termasuk output tool sebelumnya. Oleh karena itu, eksekusi yang memerlukan empat iterasi dapat menimbulkan biaya jauh lebih besar daripada empat kali biaya satu panggilan. 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 produksi. Apa yang berubah?

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