Jinsi ya kuunda AI Agent kwenye n8n kwa kutumia VPS

AI Agent ya n8n ni nini, na inatofautiana vipi na chain

AI Agent ya n8n ni AI Agent node moja yenye sub-nodes zilizounganishwa nayo: chat model moja, zana (tools) moja au zaidi, na kumbukumbu (memory) ya hiari. Unaeleza lengo kwa lugha ya kawaida, na model huamua ni zana zipi za kutumia na kwa mpangilio upi hadi iweze kujibu. Kila kitu hapa chini ni usanidi unaozunguka wazo hilo moja.

Chain hufanya kazi kinyume chake. Katika Basic LLM Chain wewe ndiye unayeamua hatua, na model hujaza maandishi pekee. Katika agent, model ndiyo huamua hatua, kwa hivyo swali lilelile linaweza kugharimu wito mmoja wa model leo na tisa kesho. Tofauti hiyo moja ndiyo inayoongoza kila mpangilio katika mwongozo huu.

Hii inachukulia kuwa n8n tayari inaendeshwa nyuma ya HTTPS kwenye mashine unayoimiliki. Ikiwa sivyo, anza na self-hosting n8n on Docker with a real certificate, kwa sababu API key unayokaribia kuhifadhi inahitaji backup ya encryption-key ambayo mwongozo huo unasisitiza. Kwa mifumo isiyo ya agent, webhook summarizers na scheduled classifiers, angalia Claude and n8n workflow patterns.

Hakikisha toleo lako kabla ya kuamini jina lolote la sehemu hapa, kwa sababu n8n hubadilisha AI nodes mara kwa mara.

docker compose exec n8n n8n --version

Majina katika mwongozo huu yanaendana na toleo la sasa la n8n stable kufikia Julai 2026. Tangu toleo la 1.82.0 kila AI Agent node huendeshwa kama Tools Agent, kwa hivyo dropdown ya zamani ya agent-type haipo tena.

Hatua ya 1: chagua kichochezi (trigger)

Kwa wakala wa mazungumzo (conversational agent), ongeza nodi ya Chat Trigger. Acha chaguo la Make Chat Publicly Available likiwa limezimwa wakati unajenga, ili paneli ya mazungumzo ya mhariri pekee ndiyo iweze kuifikia. Iwashe wakati wakala amekamilika na umeamua kuhusu uthibitishaji (authentication).

Chat Trigger humpa wakala sehemu (field) inayoitwa chatInput. Jina hilo ni muhimu katika hatua ya 3, na kulikosea ndilo kosa la kwanza la kawaida zaidi.

Kwa wakala anayefanya kazi bila kusimamiwa (unattended agent), tumia nodi ya Schedule Trigger au Webhook badala yake. Hakuna kati ya hizo inayozalisha chatInput, kwa hivyo utaandika prompt mwenyewe.

Hatua ya 2: kitambulisho cha modeli

Weka nodi ya AI Agent kwenye turubai. n8n itaonyesha mara moja kiunganishi cha Chat Model tupu chini yake. Ambatanisha nodi ndogo ya Anthropic Chat Model hapo.

Tengeneza kitambulisho (credential) kutoka kwenye Anthropic Console katika platform.claude.com, chini ya Settings kisha API Keys. Ufunguo huu huonyeshwa mara moja tu. Matumizi ya API hulipiwa kwa kila token na ni tofauti na usajili wowote wa Claude.ai, kwa hivyo akaunti inahitaji kuwa na mfumo wa malipo uliosanidiwa kabla ya kuanza kutumia.

Chagua modeli kulingana na wakala (agent), si kulingana na kampuni. Wakala mwenye zana moja anayetafuta taarifa na kuiripoti hufanya kazi vizuri kwenye Haiku, ambayo kufikia Julai 2026 ina gharama ya $1 kwa kila milioni moja ya input tokens na $5 kwa kila milioni moja ya output tokens. Wakala anapokuwa na zana kadhaa na kuhitaji kupanga kazi kati ya zana hizo, hamia kwenye Sonnet. Kosa unaloliepuka ni kutumia modeli ya bei nafuu inayochagua zana isiyo sahihi mara nne, jambo ambalo ni ghali zaidi kuliko modeli ya bei ghali inayochagua zana sahihi mara moja.

Weka Maximum Number of Tokens katika chaguzi za nodi ndogo. Hii huweka ukomo wa urefu wa kila jibu linalotolewa na modeli. Ikiachwa kwenye thamani kubwa ya awali, mchakato mmoja uliokosewa unaweza kutoa jibu refu sana na kukusababishia gharama kubwa.

Tahadhari moja kutoka kwenye nyaraka za n8n inayowatatiza wengi: semi (expressions) ndani ya nodi ndogo hutatuliwa kila mara dhidi ya kipengee cha kwanza cha ingizo, si kwa kila kipengee. Weka semi za kila kipengee kwenye sehemu za prompt za nodi kuu.

Hatua ya 3: prompt inayopokelewa na wakala

Fungua node ya AI Agent. Parameter ya Prompt ina mipangilio miwili.

• Take from previous node automatically inatarajia uwanja unaoingia unaoitwa chatInput. Hili ndilo chaguo sahihi nyuma ya Chat Trigger.
• Define below inafungua uwanja wa Prompt (User Message) ambapo unaandika maandishi tuli au expression. Hili ndilo chaguo sahihi nyuma ya Schedule Trigger au node ya Webhook.

Ukiwa na node ya Webhook mbele, mwili wa POST hutua chini ya $json.body, kwa hivyo uwanja wa prompt unaonekana hivi.

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.

Hatua ya 4: mpe wakala zana moja

Node ya AI Agent isiyo na sub-node ya zana inakataa kufanya kazi. Anza na moja, kwa sababu zana moja inayofanya kazi inakufundisha zaidi kuliko nne zilizosanidiwa nusu.

Unganisha node ya HTTP Request kwenye kiunganishi cha Tool cha wakala. Isanidi kama unavyosanidi node ya kawaida ya HTTP Request, kisha jaribu endpoint hiyo kutoka kwenye shell kwanza.

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

Ikiwa curl hiyo itarejesha kosa au ukurasa wa kuingia wa HTML, wakala naye atafeli, na kosa hilo litaonekana kama tatizo la modeli wakati kiuhalisia ni tatizo la URL au uthibitishaji. Rekebisha kwenye shell, si kwenye node.

Sehemu ya Description ya zana si nyaraka kwa ajili ya wenzako. Ni kitu pekee ambacho modeli hukisoma inapojiamulia kama zana hii inafaa. Iandike kama taarifa rahisi ya kile kinachorejeshwa: "Returns the current up or down state and the downtime duration for one monitored service, as JSON."

Ili kuruhusu modeli ijaze sehemu ya ombi, tumia expression ya $fromAI(). Inafanya kazi tu kwenye zana zilizounganishwa kwenye node ya AI Agent, na haifanyi kazi kwenye zana ya Code.

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

Hoja zake ni key, ikifuatiwa na description, type na defaultValue za hiari. Ufunguo (key) lazima uwe na vibambo 1 hadi 64, ukitumia herufi, tarakimu, underscores na hyphens. Aina (type) ni mojawapo ya string, number, boolean au json, na chaguo-msingi ni string. Wito kamili unaonekana hivi.

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

Ufunguo ni dokezo, si rejeleo la data iliyopo. $fromAI('service') haisomi sehemu inayoitwa service kutoka popote. Inaiambia modeli "tengeneza thamani na uiite service", na modeli hutafuta kupitia mazungumzo, data ya ingizo na matokeo ya zana nyingine ili kuipata. Katika mtiririko wa gumzo, inaweza kumuuliza mtumiaji moja kwa moja.

Utafutaji wa wavuti ndiyo zana ya pili ya kawaida, na kwa kuwa ni endpoint nyingine tu ya HTTP, unaweza kuelekeza node hii hiyo kwenye instance yako ya SearXNG badala ya API ya utafutaji ya kulipia, mradi tu uchukulie kila ukurasa unaorejeshwa kama maandishi yasiyoaminika ambayo sasa yako ndani ya prompt yako.

Hatua ya 5: kumbukumbu, na kwa nini wakala husahau

Bila sub-node ya kumbukumbu, kila ujumbe huanza bila muktadha wowote. Unganisha sub-node ya Simple Memory ili kuhifadhi mazungumzo ya hivi karibuni.

Ina vigezo viwili. Session Key huamua mazungumzo haya ni yapi, hivyo watumiaji wawili wenye funguo tofauti hupata historia tofauti. Context Window Length ni idadi ya mwingiliano wa awali unaorudishwa kwenye prompt.

Context Window Length ni kipimo cha gharama na pia ubora, kwa sababu kila hatua inayokumbukwa hutumwa tena kama input tokens katika kila ombi linalofuata. Dirisha la 20 kwenye wakala anayezungumza sana linamaanisha unalipia ujumbe uleule wa awali mara ishirini.

Simple Memory haifanyi kazi katika workflow ya uzalishaji (production) wakati n8n inapoendeshwa katika queue mode, kwa sababu historia hukaa kwenye data ya workflow yenyewe badala ya kuhifadhiwa kwenye hifadhi ya pamoja. Kwenye instance ya queue-mode, tumia sub-node ya Postgres Chat Memory badala yake na uielekeze kwenye database ambayo mchakato mkuu na wafanyakazi (workers) wanaweza kuifikia.

Hatua ya 6: Ujumbe wa Mfumo (System Message)

Fungua Options za wakala na uongeze System Message. Hapa ndipo unapoweka maelezo ya kazi, na huu ndio ujumbe wenye nguvu zaidi katika mtiririko wa kazi.

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.

Amri ya "Always call the status tool before answering" inafanya kazi muhimu hapo. Bila hiyo, modeli inayodhani kuwa inajua jibu tayari itaruka zana hiyo na kujibu kwa kutumia kumbukumbu zake, jambo ambalo linaweza kuwa na makosa pale miundombinu yako inapobadilika.

Kwa nini wakala hujirudia, na nini kinachozuia hilo

Pia chini ya Options kuna Max Iterations, ambayo thamani yake ya awali ni 10. Iteration moja ni wito mmoja wa model pamoja na matokeo ya tool yaliyorejeshwa kwenye muktadha. Kwa hivyo, uendeshaji mmoja wa wakala si wito mmoja wa API, bali ni hadi kumi, na kila moja hubeba mazungumzo yote yanayokua kama ingizo.

Ipunguze. Mawakala wengi wa tool moja humaliza ndani ya iterations mbili, na kikomo cha 3 au 4 hubadilisha mzunguko usiodhibitiwa kuwa hitilafu safi unayoweza kuiona kwenye orodha ya utekelezaji.

Unapofanya debugging, washa Return Intermediate Steps. Matokeo ya mwisho kisha yanajumuisha wito wa tool ambao wakala alifanya njiani, ambayo ndiyo njia unayotumia kutofautisha kati ya "model haikuwahi kuita tool" na "tool haikurejesha kitu chochote chenye manufaa". Izime tena kabla ya kuanza kutumia huduma hiyo moja kwa moja (live), kwa sababu hatua hizo ni kelele kwa mtumiaji wa mwisho.

Fuatilia uendeshaji ukitokea kutoka kwenye shell.

docker compose logs -f n8n

Kuzuia wakala asiyesimamiwa kutumia gharama bila taarifa

Agent iliyo nyuma ya Chat Trigger ina binadamu anayefuatilia, na binadamu huyo huizuia jibu linapoonekana kuwa si sahihi. Agent iliyo nyuma ya Schedule Trigger haina mtu wa kuifuatilia. Kile unachofuatilia hapa ni matumizi ya modeli, si gharama ya leseni, kwa sababu nodes za agent, tool na memory zote hufanya kazi kwenye free self-hosted edition, na vipengele vinavyohitaji paid key ni hasa vya timu na governance. Maelezo kamili yanapatikana kwenye Udhibiti wa gharama za AI agent kwenye VPS inayowashwa muda wote. Settings nne ndizo hufanya kazi kubwa hapa.

• Weka kikomo cha Maximum Number of Tokens kwenye sub-node ya modeli, ili jibu lolote lisiweze kuwa refu kupita kiasi.
• Weka Max Iterations kwenye namba ndogo zaidi inayoweza kukamilisha kazi husika.
• Hakikisha majibu ya zana (tool responses) ni madogo. Zana inayorejesha JSON blob ya mistari 4,000 huweka yote hayo kwenye mwito wa modeli unaofuata, na kisha kwenye kila mwito baada ya hapo katika mzunguko huo huo.
• Jiulize kama wakala anahitaji ratiba (schedule) hata kidogo. Kazi inayotekelezwa kila baada ya dakika tano huwaka mara 288 kwa siku. Gharama yoyote ya utekelezaji mmoja, ndiyo namba unayopaswa kuzidisha.

Zima workflow wakati unafanya marekebisho. Workflow inayofanya kazi ikiwa na Schedule Trigger huendelea kutekelezwa dhidi ya toleo ambalo n8n imelihifadhi, ambalo si mara zote ni toleo lililo kwenye skrini yako.

FAQ

Kwa nini node yangu ya AI Agent inakataa kutekeleza kazi?

Node ya AI Agent inahitaji sub-node ya chat model na angalau sub-node moja ya tool. Node yenye model lakini bila tool itafeli kabla ya kufanya API call yoyote. Unganisha tool moja, hata kama ni rahisi, kisha iendeshe tena.

Agent anajibu, lakini haiti tool yangu. Nini tatizo?

Mara nyingi tatizo ni sehemu ya Description ya tool hiyo. Model huchagua tools kwa kusoma maelezo hayo, kwa hivyo maelezo kama "HTTP Request" hayamwambii chochote kuhusu wakati wa kutumia tool hiyo. Iandike upya ili ieleze ni data gani inarudi na katika hali gani ni muhimu, kisha ongeza mstari kwenye System Message ukimwagiza agent aite tool hiyo kabla ya kujibu.

Kwa nini swali lilelile linagharimu kiasi tofauti kila linapoendeshwa?

Kwa sababu model huchagua idadi ya hatua (steps). Kila iteration hutuma tena mazungumzo yote yaliyopita, ikiwemo matokeo ya tool za awali, kwa hivyo mchakato unaotumia iterations nne unagharimu zaidi ya mara nne ya call moja. Max Iterations ndiyo kikomo cha juu, na Return Intermediate Steps inakuonyesha ni hatua ngapi mchakato fulani umetumia.

Kumbukumbu yangu inafanya kazi kwenye editor lakini si kwenye production. Nini kimebadilika?

Angalia kama instance inaendeshwa katika queue mode. Simple Memory huhifadhi historia kwenye data ya utekelezaji ya workflow yenyewe, ambayo haibaki ikiwa itahamishiwa kwenye worker process tofauti, kwa hivyo workflow ya production inayofanya kazi hupoteza data hiyo. Badilisha na utumie sub-node ya Postgres Chat Memory, ambayo huhifadhi historia kwenye database inayoshirikiwa na kila worker.