SSD Nodes Learn Hosting plans →
Mwongozo Matt ConnorNa Matt Connor

Jinsi ya kuunda AI Agent kwenye n8n kwa kutumia VPS

Jifunze kuunda AI Agent ndani ya n8n kwa kutumia AI Agent node, Claude model, HTTP Request tool, na kumbukumbu. Pata usanidi sahihi wa kudhibiti gharama za API zako.

Wakala wa AI wa n8n ni nini, na unatofautianaje na chain

Wakala wa AI wa n8n ni node moja ya AI Agent iliyo na sub-node zilizounganishwa nayo: chat model moja, tool moja au zaidi, na memory ya hiari. Unaeleza lengo kwa lugha ya kawaida, kisha model huamua ni tool zipi itumie na kwa mpangilio gani hadi iweze kujibu. Kila kitu hapa chini ni usanidi unaozunguka wazo hilo moja.

Chain hufanya kazi kwa njia tofauti. Katika Basic LLM Chain, wewe huamua hatua na model hujaza maandishi pekee. Katika agent, model huamua hatua, kwa hiyo swali lilelile linaweza kutumia model call moja leo na tisa kesho. Tofauti hiyo moja ndiyo huathiri kila setting katika mwongozo huu. Ikiwa loop hiyo ni wazo jipya kwako badala ya kuwa feature ya n8n, inafaa kuiandika mwenyewe mara moja kabla ya kuiunda kwa kutumia nodes, kwa sababu node huficha sehemu halisi utakayotumia muda uliosalia wa mwongozo huu kuichanganua.

Hii inadhania kuwa n8n tayari inaendeshwa nyuma ya HTTPS kwenye mashine unayoidhibiti. Ikiwa haijaendeshwa hivyo, anza na kujiendeshea n8n kwenye Docker kwa certificate halisi, kwa sababu API key unayokaribia kuhifadhi inahitaji backup ya encryption-key ambayo mwongozo huo unasisitiza. Kwa mifumo isiyotumia agent, kama webhook summarizers na scheduled classifiers, tazama mifumo ya workflow ya Claude na n8n.

Kagua version yako kabla ya kuamini jina lolote la field hapa, kwa sababu n8n hubadilisha AI nodes mara kwa mara.

docker compose exec n8n n8n --version

Version 1.82.0 iliweka setting ya agent-type kuwa deprecated na kupendelea Tools Agent. Legacy v1 nodes bado zina setting hiyo; nyaraka za n8n zinaweka kuondolewa kwa node version hiyo kwenye n8n 3.0.

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 node ya AI Agent kwenye turubai. n8n itaonyesha mara moja kiunganishi cha Chat Model tupu chini yake. Ambatisha sub-node ya Anthropic Chat Model hapo.

Tengeneza kitambulisho (credential) kutoka kwenye Claude Console katika platform.claude.com, chini ya Settings kisha API keys. Ufunguo huonyeshwa mara moja tu. Console pia itakuomba uchague muda wa kuisha kwa ufunguo unapoitengeneza, na wakala anayefanya kazi bila kusimamiwa (unattended agent) ataacha kufanya kazi siku ufunguo wake utakapomalizika, kwa hivyo weka tarehe hiyo mahali ambapo utaiona. Kwa wakala asiyesimamiwa, tumia ufunguo wa service account uliowekewa wigo (scoped) kwenye workspace ili maombi yasihitaji header tofauti ya workspace.

Matumizi ya API hulipiwa kwa kila token, na jinsi unavyolipa inategemea mpango wako wa Claude, kuanzia tarehe 31 Oktoba 2026. Mipango ya Max, Ultra na Team inajumuisha API credits za kila mwezi: $100 kwenye Max, $200 kwenye Ultra, na hadi $500 zilizokusanywa kwenye Team. Unazidai kwa kuunganisha shirika la Console kwenye mpango huo kutoka Settings > Billing kwenye Max au Ultra au Organization settings > Billing kwenye Team, na huhitaji kuongeza njia ya malipo kwenye Console. Wasajili wapya wanaweza kudai baada ya siku 7 kwenye mpango, na credits zisizotumika huisha mwishoni mwa kila mzunguko wa malipo, au kila mwezi kwenye mipango ya mwaka. Credits zilizojumuishwa zinapoisha, maombi yanaendelea kutumia credits zilizonunuliwa, auto-reload inaweza kununua zaidi, na mashirika yanayopokea ankara hulipishwa kwa matumizi ya ziada. Maombi husimama wakati shirika la kulipia kabla halina credits zilizobaki; matumizi ya API hayatozwi kamwe kwenye mpango wako wa Claude. Mipango ya Free, Pro na Enterprise haijumuishi API credits za kila mwezi, kwa hivyo kwenye mipango hiyo API hulipiwa tofauti na usajili.

Chagua modeli kwa kila wakala, si kwa kila kampuni. Wakala mwenye zana moja anayetafuta kitu na kutoa ripoti hufanya kazi vizuri kwenye Haiku. Toleo la sasa, Haiku 5.5, linagharimu $0.10 kwa kila milioni ya input tokens na $0.50 kwa kila milioni ya output tokens kuanzia tarehe 12 Oktoba 2026, na kupanda hadi $0.50 na $2.50 kwa ombi lolote ambalo prompt yake inazidi token 100,000, jambo ambalo dirisha refu la kumbukumbu na matokeo makubwa ya zana yanaweza kukupelekea. Wakala anapokuwa na zana kadhaa na kulazimika kupanga kazi kati yao, hamia kwenye Sonnet. Hitilafu unayoiepuka ni modeli ya bei nafuu inayotumia zana isiyo sahihi mara nne, ambayo inagharimu zaidi kuliko modeli ya bei ghali inayotumia zana sahihi mara moja.

Weka Maximum Number of Tokens katika chaguzi za sub-node. Hii huweka ukomo wa urefu wa kila jibu ambalo modeli inazalisha. Ikiachwa kwenye thamani kubwa ya awali, mchakato mmoja uliokanganyikiwa unaweza kuzalisha jibu refu sana na kukutoza gharama kwa ajili hiyo.

Tahadhari moja kutoka kwenye nyaraka za n8n inayowatatiza watu wengi: expressions ndani ya sub-node hutatuliwa kila wakati dhidi ya item ya kwanza ya input, si kwa kila item. Weka expressions za kila item kwenye sehemu za prompt za node kuu.

Hatua ya 3: prompt inayopokelewa na agent

Fungua node ya AI Agent. Kigezo cha Source for Prompt (User Message) kina mipangilio miwili.

  • Connected Chat Trigger Node hutafuta field inayoingia yenye jina chatInput. Hili ndilo chaguo sahihi unapoitumia nyuma ya Chat Trigger.
  • Define below huonyesha field ya Prompt (User Message) ambapo unaandika maandishi tuli au expression. Hili ndilo chaguo sahihi unapoitumia nyuma ya Schedule Trigger au node ya Webhook.

Unapoweka node ya Webhook mbele, mwili wa POST huwekwa chini ya $json.body, hivyo field ya prompt huonekana 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 agent tool moja

Nyaraka za n8n zinasema lazima uunganishe angalau tool sub-node moja kwenye AI Agent node, ingawa node code ya sasa (version 3.1) hukataa tu kuendesha bila chat model. Anza na tool moja kwa vyovyote vile, kwa sababu tool moja inayofanya kazi hukufundisha zaidi kuliko tool nne zilizosanidiwa nusu, na agent isiyo na tool ni chain tu inayogharimu zaidi.

Ambatisha node ya HTTP Request kwenye connector ya Tool ya agent. Isanidi kama vile ungesanidi node ya kawaida ya HTTP Request, kisha kwanza ijaribu endpoint hiyo kutoka kwenye shell.

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

Ikiwa curl hiyo inarudisha error au ukurasa wa kuingia wa HTML, agent pia itashindwa, na failure itaonekana kama tatizo la model ilhali kwa kweli ni tatizo la URL au authentication. Rekebisha tatizo hilo kwenye shell, si kwenye node.

Sehemu ya Description ya tool si documentation kwa ajili ya wenzako. Model huisoma pamoja na jina la tool na parameter schema inapoamua kama tool hii inahusika. Iandike kama taarifa rahisi ya kile kinachorudishwa: "Hurejesha hali ya sasa ya up au down na muda wa downtime wa service moja inayofuatiliwa, kama JSON."

Ili kuiruhusu model kujaza sehemu ya request, tumia expression ya $fromAI(). Inafanya kazi tu kwenye tools zilizounganishwa kwenye AI Agent node, na haifanyi kazi kwenye Code tool.

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

Arguments ni key, kisha kwa hiari description, type na defaultValue. Key lazima iwe na urefu wa herufi 1 hadi 64, na itumie letters, digits, underscores na hyphens. Type ni mojawapo ya string, number, boolean au json, na default yake ni string. Call kamili zaidi inaonekana hivi.

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

Key ni hint, si reference ya data iliyopo. $fromAI('service') haisomi field inayoitwa service kutoka mahali popote. Huambia model "tengeneza value na uiite service", kisha model hutafuta value hiyo kwenye mazungumzo, input data na matokeo ya tools nyingine. Katika chat workflow, inaweza kumuuliza user moja kwa moja.

Web search ndiyo tool ya pili inayotumiwa kwa kawaida, na kwa kuwa ni HTTP endpoint nyingine tu, unaweza kuelekeza node hii hiyo kwenye instance yako ya SearXNG badala ya paid search API, mradi uchukulie kila page inayorudishwa kama maandishi yasiyoaminika ambayo sasa yako ndani ya prompt.

Hatua ya 5: memory, na kwa nini agent husahau

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

Ina vigezo viwili. Session Key huamua mazungumzo haya ni yapi, kwa hiyo watumiaji wawili walio na keys tofauti hupata historia tofauti. Context Window Length huonyesha ni miingiliano mingapi iliyotangulia itakayorejeshwa kwenye prompt.

Context Window Length ni kidhibiti cha gharama sawa na kilivyo kidhibiti cha ubora, kwa sababu kila turn iliyohifadhiwa hutumwa tena kama input tokens kwenye kila ombi linalofuata. Window ya 20 kwenye agent anayezungumza sana inamaanisha unalipia ujumbe uleule wa mwanzo mara ishirini.

Simple Memory haifanyi kazi katika workflow ya production inayotumika wakati n8n inaendeshwa katika queue mode, kwa sababu huhifadhi historia kwenye singleton Map iliyo ndani ya process na inayotumia workflow IDs na session IDs kama funguo, huku workers hazishiriki memory hiyo. Kwenye instance ya queue mode, tumia badala yake sub-node ya Postgres Chat Memory na uielekeze kwenye database ambayo main process na workers zinaweza 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 agent inaendelea kujirudia, na nini huizuia

Pia kwenye Options kuna Max Iterations, ambayo thamani yake ya kawaida ni 10. Iteration moja ni mwito mmoja wa model ambao huomba tools au kurudisha jibu la mwisho; matokeo ya tools huingizwa kwenye mwito unaofuata. Kwa hiyo, uendeshaji mmoja wa agent si mwito mmoja wa API, bali unaweza kuwa na hadi mialiko 10, na kila mwito hubeba mazungumzo yote yanayoongezeka kama ingizo.

Punguza thamani hiyo. Agents wengi wanaotumia tool moja humaliza ndani ya iterations mbili, na kikomo cha 3 au 4 hubadilisha loop isiyokwisha kuwa failure iliyo wazi ambayo unaweza kuiona kwenye orodha ya executions.

Wakati wa kufanya utatuzi, washa Return Intermediate Steps. Output ya mwisho itajumuisha tool calls ambazo agent ilifanya wakati wa mchakato. Hii hukusaidia kutofautisha kati ya “model haikuita tool kamwe” na “tool haikurudisha chochote chenye manufaa”. Izime kabla ya kuanza matumizi ya moja kwa moja, kwa sababu hatua hizo ni kelele zisizohitajika kwa mtumiaji wa mwisho.

Fuatilia uendeshaji kutoka kwenye shell.

docker compose logs -f n8n

Kuzuia agent asiye na uangalizi kutumia rasilimali bila kutambuliwa

Agent aliye nyuma ya Chat Trigger ana mtu anayemfuatilia, na mtu huyo humzuia jibu linapoonekana kuwa si sahihi. Agent aliye nyuma ya Schedule Trigger hana mtu wa kumwangalia. Hapa unafuatilia matumizi ya model, si gharama ya leseni, kwa sababu nodes za agent, tool na memory zote hufanya kazi kwenye toleo la bure la self-hosted, na vipengele vinavyohitaji key ya kulipia mara nyingi ni vya timu na usimamizi. Maelezo kamili yako kwenye Udhibiti wa gharama za AI agent kwenye VPS inayowaka muda wote. Mipangilio minne ndiyo hufanya sehemu kubwa ya kazi hapa.

  • Weka kikomo cha Maximum Number of Tokens kwenye model sub-node, ili jibu moja lisichukue muda mrefu.
  • Weka Max Iterations kuwa idadi ndogo zaidi inayokamilisha kazi.
  • Weka majibu ya tool kuwa mafupi. Tool inayorejesha JSON yenye mistari 4,000 huingiza yote kwenye model call inayofuata, kisha kwenye kila call inayofuata katika run hiyo hiyo.
  • Jiulize kama agent anahitaji schedule kabisa. Job inayotumika kila baada ya dakika tano huanza mara 288 kwa siku. Gharama ya run moja ikoje, hiyo ndiyo thamani utakayozidisha.

Ondoa workflow kwenye uchapishaji unapoiendeleza, au angalau kumbuka ni toleo gani lililo live. Workflow iliyochapishwa yenye Schedule Trigger huendelea kutumia toleo ulilochapisha mara ya mwisho, si draft iliyo kwenye skrini yako, kwa sababu n8n huhifadhi mabadiliko yako kama draft hadi uchapishe tena.

FAQ

Kwa nini nodi yangu ya AI Agent inakataa kutekeleza?

Kwanza, kagua connectors. Nodi ya AI Agent inahitaji sub-node ya chat model. Bila hiyo, husitisha utekelezaji kwa ujumbe "Please connect a model to the Chat Model input" kabla haijafanya API call yoyote. Nyaraka za n8n pia zinaorodhesha angalau sub-node moja ya tool kuwa hitaji. Kwa hiyo, ikiwa model imeunganishwa lakini nodi bado inakataa, ongeza tool moja, hata ikiwa ni rahisi sana, kisha uiendeshe tena.

Agent inajibu, lakini haiiti tool yangu. Tatizo ni nini?

Karibu kila mara tatizo huwa kwenye sehemu ya Description ya tool. Model huchagua tools kwa kusoma maelezo hayo. Kwa hiyo, maelezo kama "HTTP Request" hayaelezi tool hiyo inafaa kutumika lini. Yaandike upya ili yaeleze data inayorudishwa na hali ambayo tool hiyo inafaa kutumika. Kisha ongeza mstari kwenye System Message unaomwagiza agent kuiita tool hiyo kabla ya kujibu.

Kwa nini swali lilelile hugharimu kiasi tofauti kila linapoendeshwa?

Kwa sababu model huchagua idadi ya hatua. Kila iteration hutuma tena mazungumzo yote yaliyofanyika hadi wakati huo, pamoja na matokeo ya awali ya tool. Kwa hiyo, run inayochukua iterations nne hutozwa input tokens na output tokens za calls zote nne. Max Iterations huweka kikomo cha juu cha idadi hiyo. Return Intermediate Steps hukuonyesha idadi ya hatua ambazo run fulani ilitumia.

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

Kagua ikiwa instance inaendeshwa katika queue mode. Simple Memory huhifadhi historia kwenye singleton Map iliyo ndani ya process, ikiwa na workflow na session IDs kama funguo. Worker processes tofauti hazishirikiani Map hiyo. Tumia sub-node ya Postgres Chat Memory, ambayo huhifadhi historia kwenye database inayoshirikiwa na kila worker.

Je, makala hii ilikusaidia?