Jinsi ya kujifunza AI agents kuanzia mwanzo

Njia ya hatua sita

Ili kujifunza AI agents kuanzia mwanzo, pitia hatua sita kwa mpangilio: dhana, mzunguko wako wa kwanza, zana, kumbukumbu, usanifu wa mzunguko, na usalama. Kila hatua ina kitu kimoja unachojenga kwa mikono yako mwenyewe. Kuruka hatua ni sababu ya kawaida inayowafanya watu kukwama, kwa sababu framework huficha sehemu hasa uliyohitaji kuiona.

AI agent ni mzunguko unaozunguka language model inayoruhusiwa kutumia zana. Sentensi hiyo ndiyo mada nzima. Kila kitu kinachofuata ni maelezo kuhusu kile kinachoingia kwenye mzunguko, kile ambacho zana zinaweza kugusa, na jinsi unavyosimamisha mzunguko huo unapoharibika. Ikiwa unaweza kumwelezea mtu mwingine mzunguko huo, umelijua jambo hilo. Ikiwa unaweza kutaja tu framework, hujajifunza.

Mpango ufuatao unachukulia kuwa unajifunza kwa kujenga. Soma hatua, jenga kitu kidogo, kiharibu kwa makusudi, kisha endelea. Hatua uliyosoma tu ni hatua ambayo hujafanya.

Unachohitaji hasa kabla ya hatua ya 1

Orodha ya kweli ya mahitaji ya awali ni fupi, na ni fupi kuliko inavyopendekezwa na kurasa nyingi za kozi.

• Unaweza kusoma na kuandika Python au TypeScript katika kiwango cha hati ya mistari hamsini.
• Unajiamini katika Linux shell: kusakinisha kifurushi, kuhariri faili, kusoma log.
• Una API key ya model inayohudumiwa (hosted), au mashine inayoweza kuendesha model ya ndani (local).

Hiyo ndiyo orodha nzima. Huhitaji nadharia ya machine learning, na huhitaji kuwa umefunza (train) model yoyote. Hakuna kitu katika kazi ya mawakala (agents) kinachohusisha gradients au data ya mafunzo. Kadi ya michoro (graphics card) ni muhimu tu ikiwa utaamua kuendesha model mwenyewe, ambayo ni ujuzi tofauti unaoweza kujifunza baadaye kupitia hosting Ollama on a VPS to self host an LLM.

Watu wanachokidharau ni nusu ya shell. Mawakala hushindwa kufanya kazi kwa sababu ya ruhusa (permissions), njia za faili (paths), environment variables, na michakato (processes) inayokufa kimya kimya. Ikiwa stack trace kuhusu PATH au mode ya faili inakufanya ufunge terminal, tumia wikendi kujifunza misingi ya Linux kwanza. Itakuokoa mwezi mzima baadaye.

Hatua ya 1: wakala ni nini, na si nini

Anza na API call moja bila loop. Tuma prompt, chapisha jibu, kagua idadi ya token kwenye jibu hilo. Sasa unaelewa kipimo cha gharama na kipimo cha latency.

Kisha jifunze matumizi ya zana (tool use), ambayo ndiyo wazo jipya la kweli katika nyanja hii nzima. Unafafanua function kwa model kama jina, maelezo, na JSON (JavaScript object notation) schema kwa ajili ya inputs zake. Model haitekelezi chochote. Inajibu kwa ombi lililopangwa: ita run_command na arguments hizi. Code yako inaendesha function hiyo, inatuma output kurudi kama ujumbe, na kumuuliza model tena. Model ni mpangaji anayesoma maandishi na kuandika maandishi. Code yako ndiyo kitu chenye mikono. Code iliyo upande wako wa mabadilishano hayo ina jina pindi unapoanza kulinganisha usanifu: hiyo ni the agent harness, loop na zana na ruhusa zilizofungwa kuzunguka model ambayo haina zake yenyewe.

Chatbot huishia baada ya jibu moja. Wakala hurudia mabadilishano hayo hadi model iache kuomba zana. Urudiaji huo ndio tofauti nzima, na ndiyo sababu njia za kufeli (failure modes) pia hutofautiana. Chatbot hutoa jibu lisilo sahihi mara moja. Wakala huchukua hatua kulingana na jibu lisilo sahihi mara kadhaa kabla ya mtu yeyote kugundua.

Hatua ya 2: andika loop mwenyewe, mara moja

Usianze na framework. Andika takriban mistari 30 ya Python ili uwe na umiliki wa muundo wa kitu hicho.

sudo apt update && sudo apt install -y python3-venv
python3 -m venv ~/agent
source ~/agent/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=your-key-here

import subprocess
import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "run_command",
    "description": "Run a read only shell command and return its output.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

messages = [{"role": "user", "content": "How much disk space is free here?"}]

while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            done = subprocess.run(
                block.input["command"], shell=True,
                capture_output=True, text=True, timeout=10,
            )
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": done.stdout or done.stderr,
            })
    messages.append({"role": "user", "content": results})

print(next(b.text for b in response.content if b.type == "text"))

Iendeshe kwa kutumia python3 agent.py. Uendeshaji mzuri huchapisha aya moja inayotaja mifumo yako ya faili (filesystems) na nafasi iliyo wazi, kwa sababu modeli iliuliza df -h, msimbo wako uliiiendesha, na pasi ya pili ikageuza jedwali hilo kuwa sentensi. Ikiwa haichapishi chochote, loop iliisha kabla ya kizuizi cha maandishi kufika. Ongeza print(response.stop_reason) ndani ya loop na uangalie thamani zikibadilika.

Sasa iharibu kwa makusudi. Futa mstari wa tool_use_id na usome kosa (error), kwa sababu matokeo ya zana yasiyo na id inayolingana hukataliwa na API na hilo ndilo kosa la kawaida zaidi kwa wanaoanza. Uliza swali linalohitaji amri mbili na uangalie loop ikijirudia mara mbili. Uliza kitu kisichowezekana na uangalie kama inakata tamaa au inazunguka milele.

Onyo moja kuhusu mfano huu. Inapitisha matokeo ya modeli moja kwa moja kwenye shell kwa kutumia shell=True, jambo ambalo linafaa kwenye mashine ya majaribio unayoweza kuijenga upya, lakini ni kosa mahali pengine popote. Hatua ya 6 inarekebisha hilo. Dhana zilizo chini ya loop zimefafanuliwa kwa kina zaidi katika kujenga wakala wako wa AI kwenye VPS.

Hatua ya 3: zana ambazo wakala hakuwa nazo awali

Zana yako ya run_command inafanya kazi, lakini wakala halisi anahitaji zana zinazofikia nje ya mfumo: mfumo wa tiketi, hifadhidata, au hazina ya msimbo. Kuandika kanga (wrapper) maalum kwa kila huduma, kwa kila wakala, hakukui kulingana na mahitaji.

Model Context Protocol (MCP) ndiyo jibu ambalo sekta imekubaliana nalo. Seva ya MCP hufichua seti ya zana kupitia usafirishaji wa kawaida, na wakala yeyote anayeelewa MCP anaweza kuitumia bila hitaji la viunganishi maalum. Seva ya marejeleo ya mfumo wa faili ni amri moja tu:

npx -y @modelcontextprotocol/server-filesystem /home/you/projects

Hii inahitaji Node kusakinishwa, na hoja ya saraka ndiyo njia pekee ambayo seva itagusa. Huu ni mfano wa usalama kwa ufupi: seva ndiyo huamua mipaka, siyo modeli. Elekeza mteja kwenye seva hiyo na wakala wako atapata uwezo wa kusoma na kuandika faili ambazo hukuziandikia. Kuendesha hizi ipasavyo, chini ya akaunti ya huduma na kwa chaguzi za usafirishaji zilizoelezwa, imeshughulikiwa katika kuendesha seva za MCP kwenye VPS kwa ajili ya mawakala wa uandishi wa msimbo wa AI. Kwa seva ya pili inayoelekeza kwenye data halisi badala ya saraka ya muda, kujihudumia openGym, kifuatiliaji cha mazoezi inatoa seva ya kusoma pekee, ili uweze kufanya mazoezi ya kuuliza maswali kuhusu historia yako ya mazoezi bila kumpa wakala kitu chochote anachoweza kuharibu.

Somo la hatua hii ni kwamba usanifu wa zana ndiyo kazi halisi. Maelezo yasiyo wazi humfanya modeli kubahatisha. Zana inayorejesha vibambo elfu arobaini huchafua dirisha la muktadha. Zana inayoweza kufuta vitu hatimaye itafuta vitu.

Hatua ya 4: kumbukumbu, ambayo kimsingi ni faili tu

Wanaoanza hutumia vector database katika hatua hii. Usifanye hivyo, angalau si kwa sasa.

Wakala (agent) hana kumbukumbu kati ya wito mmoja na mwingine. Unatuma tena mazungumzo yote kila wakati, ndiyo sababu kipindi kirefu cha mazungumzo hugharimu zaidi kwa kila hatua kuliko kile kifupi. Kwa hivyo, kumbukumbu hugawanyika katika matatizo mawili. La kwanza ni kile kinachotosha kwenye context window kwa sasa, ambacho unakidhibiti kwa kufanya muhtasari, kupunguza matokeo ya zamani ya zana (tool output), na kwa kuhifadhi (caching) sehemu ya mwanzo ya prompt yako ili ulipe gharama ndogo kwa ajili yake. La pili ni kile kinachobaki baada ya kuanzisha upya (restart), ambacho ni hifadhi (storage).

Kwa tatizo la pili, faili rahisi ya markdown ambayo wakala anaweza kusoma na kuandika ni bora kuliko vector database kwa karibu kila mradi wa kwanza. Mpe faili moja, mweleze muundo wake, mwambie asome faili hiyo kabla ya kuanza na aisasishe anapojifunza kitu kipya. Unapata manufaa mengi, na unaweza kufungua faili hiyo na kuona kile wakala wako anachoamini. Tumia embeddings na retrieval wakati madokezo yanapoacha kutoshea kwenye context window, na si kabla ya hapo.

Hatua ya 5: kitanzi ndicho bidhaa

Kufikia sasa unaweza kutengeneza wakala (agent) anayefanya kazi wakati unamwangalia. Hatua ya 5 ni kumfanya afanye kazi wakati humwangalii.

Maswali manne huamua kama wakala asiyesimamiwa yuko salama kuachwa peke yake. Ni nini kinachomchochea (trigger), ili asifanye kazi bila sababu. Anafanyia kazi ndani ya mipaka gani, ili kosa dogo lisilete madhara makubwa. Matokeo yanathibitishwaje, kwa sababu wakala anayejipima mwenyewe hufaulu kila wakati. Ni bajeti gani inamzuia, kwa kutumia tokens au muda wa saa. Kubuni mambo hayo manne kwa makusudi ndiyo nidhamu inayoelezewa katika uhandisi wa vitanzi (loop engineering), na kile ambacho ufafanuzi huo unahusu.

Zoezi: chukua wakala wako wa hatua ya 2, mpe kazi inayohitaji hatua nne au tano, na uweke kikomo cha marudio (iteration cap). Kisha ondoa kikomo hicho na uangalie kile ambacho kitanzi kisicho na kikomo kinafanya kwa bili yako ya tokens. Fanya hivyo mara moja kwa bajeti ndogo ili usije ukafanya hivyo kwa bahati mbaya ukiwa na bajeti kubwa.

Hatua ya 6: usalama, siri, na gharama

Hatua hii si ya hiari, na imewekwa mwisho kwa sababu huwezi kuhisi hatari hadi uwe umejenga kitu kinachofanya kazi.

Endesha wakala kama mtumiaji wake mwenyewe asiye na upendeleo, kamwe usitumie root na kamwe usitumie akaunti yako binafsi, ili eneo la athari liwe saraka moja badala ya mashine nzima. Weka vitambulisho mbali na uwezo wa modeli, kwa sababu chochote kilichopo kwenye dirisha la muktadha kinaweza kunukuliwa nje kupitia wito wa zana, na suluhisho ni kutumia tokeni za muda mfupi zilizolindwa nyuma ya msaidizi kama ilivyoelezwa katika kuepusha siri kwenye AI agents zako. Weka kikomo cha juu cha matumizi, kwa sababu kitanzi kisichosimamiwa hutoza kila mzunguko bila mtu yeyote kutazama, na viwango vya juu na uwekaji wa bechi vinavyoiweka katika hali ya busara viko katika udhibiti wa gharama za AI agent kwenye VPS inayowaka kila wakati.

Ikiwa wakala wako anaendeshwa ndani ya mfumo wa usimamizi badala ya hati uliyoandika mwenyewe, sehemu ya hatua hii ni usanidi badala ya msimbo, na programu jalizi za DeepSeek Harness zinazofaa kusakinishwa hushughulikia mambo mengi yanayofanana na vikomo vya bajeti, sheria za ruhusa za zana, na uchanganuzi wa sindikizo (injection).

Gharama inastahili namba moja thabiti. Kufikia Julai 2026, Claude Opus 5 hutoza $5 kwa kila milioni moja ya tokeni za kuingiza na $25 kwa kila milioni moja ya tokeni za kutoa, na wakala anayepiga gumzo akituma tena mazungumzo yanayokua anaweza kusukuma tokeni laki kadhaa kupitia kazi moja. Uwekaji wa akiba wa prompt (prompt caching), na modeli ndogo kwa hatua za kawaida, hubadilisha hesabu hiyo zaidi kuliko marekebisho yoyote ya prompt.

Sindikizo la prompt (prompt injection) linahusika hapa pia. Ikiwa wakala wako anasoma ukurasa wa wavuti, kifuatiliaji cha masuala, au kikasha, basi yeyote aliyeandika maandishi hayo pia anaandika maagizo kwa wakala wako. Utafutaji wa wavuti kwa kawaida ndio zana inayofungua mlango huu kwanza, na kuelekeza wakala kwenye mfano wako wa SearXNG kunaonyesha muunganisho na eneo la sindikizo linaloundwa kando yake. Ulinzi si prompt ya mfumo yenye werevu zaidi. Ni mpaka, kwa sababu wakala asiyeweza kufuta hazina (repository) hawezi kushawishiwa kuifuta.

Ni ramani ipi unapaswa kufuata?

Chagua mtaala mmoja na uumalize badala ya kujaribu sita. Hifadhi ya ai-agents-for-beginners ya Microsoft ndiyo iliyo kamili zaidi bila malipo, kozi ya masomo kumi na nane ambayo imevuka nyota 70,000 kufikia Julai 2026, na inalingana vizuri na hatua zilizo hapo juu. Orodha za hifadhi za mawakala zinazovuma ni muhimu kwa kuona kile kilichopo lakini hazifai sana kama mtaala, kwa sababu orodha iliyopangwa kwa nyota hupangwa kwa umaarufu badala ya mpangilio wa kufundishia.

Unapotaka mradi halisi wa kufanyia mazoezi, wakala wa uandishi wa kanuni (coding agent) ndilo lengo la kwanza bora zaidi: mrejesho ni wa papo hapo, zana ni dhahiri, na makosa ni rahisi kurekebisha. Kuendesha wakala wa AI wa uandishi wa kanuni kwenye VPS inaelezea mchakato mzima kuanzia mwanzo hadi mwisho. Ikiwa unapendelea kusoma mifumo inayofanya kazi badala ya kujenga kutoka sifuri, ulinganisho katika mawakala bora wa AI wanaojiendesha (self-hosted) unaonyesha jinsi miradi kadhaa inavyotatua kitanzi kimoja kwa njia tofauti.

Inachukua muda gani?

Kwa mtu ambaye tayari anajua kupanga programu, hatua ya 1 na ya 2 huchukua jioni moja. Hatua ya 3 huchukua wikendi nzima, ambapo muda mwingi hutumika kusoma maelezo ya zana badala ya itifaki. Hatua ya 4 na ya 5 huchukua wiki chache za matumizi ya kweli, kwa sababu unajifunza mambo ambayo wakala wako anasahau kwa kumtazama akisahau. Hatua ya 6 haimaliziki kamwe, kwa maana kwamba kila uwezo mpya unaompa wakala hufungua hatua hiyo upya.

Miezi miwili ya kufanya kazi kila jioni huwezesha watu wengi kuwa na wakala anayefanya kazi, mwenye mipaka, na muhimu. Wale wanaotumia mwaka mzima mara nyingi ni wale walioendelea kusoma badala ya kujenga.

FAQ

Je, nahitaji kujua machine learning ili kujenga AI agent?

Hapana. Kujenga agent kunamaanisha kuita model kupitia API na kuunganisha maombi yake ya zana (tool requests) kwenye functions halisi, jambo ambalo ni programu ya kawaida ya kompyuta. Hutaigusa kamwe sehemu ya training, gradients, au datasets. Ujuzi unaoamua kama agent wako atafanya kazi vizuri ni usanifu wa schema kwa ajili ya zana, ushughulikiaji wa makosa (error handling), na ruhusa za Linux. Nadharia ya machine learning inakuwa na umuhimu tu ikiwa utaamua kufanya fine-tuning ya model, ambayo ni kazi tofauti yenye mahitaji tofauti.

Je, nianze na framework kama LangChain au CrewAI?

Andika loop ya kwanza wewe mwenyewe (raw loop), kisha ndipo utumie framework. Framework hubadilisha mistari thelathini ya hatua ya 2 na kuwa kitu kimoja cha configuration, jambo ambalo ni rahisi ukishajua kile kilichobadilishwa, lakini linachanganya usipokijua. Wakati agent wako anapofanya kazi vibaya, lazima uchanganue orodha ya ujumbe na matokeo ya zana moja kwa moja, na hilo ni gumu zaidi ikiwa hujawahi kuyaona. Baada ya kuandika loop moja mwenyewe, framework itakuokoa muda badala ya kuficha utaratibu wa ndani.

Inagharimu kiasi gani kujifunza AI agents?

Ni kidogo kuliko watu wengi wanavyotarajia, ukiweka mipaka. API key inayotolewa na huduma ya mtandaoni na VPS ndogo vinatosha kwa hatua hizi zote sita. Hatari halisi si gharama ya kila saa, bali ni loop isiyo na kikomo inayotoza malipo kila inapoendelea wakati umelala. Weka kikomo cha matumizi kwenye akaunti yako ya API siku ya kwanza, ongeza kikomo cha marudio (iteration cap) kwenye kila loop unayoandika, na tumia model ya bei nafuu kwa hatua za kawaida. Kuendesha model ndani ya kompyuta yako (locally) huondoa gharama za token na badala yake huhitaji vifaa bora vya kompyuta.

Kuna tofauti gani kati ya AI agent na chatbot?

Chatbot hujibu mara moja. Agent hurudia mzunguko: model huomba zana, code yako huiendesha, matokeo hurudi, na model huamua nini cha kufanya baadaye. Kurudia huko ndiko kunakomwezesha agent kumaliza kazi yenye hatua kadhaa, na ndiyo sababu agents wanahitaji mipaka ambayo chatbots hazihitaji. Jibu lisilo sahihi kutoka kwa chatbot ni aya mbaya tu. Jibu lisilo sahihi kutoka kwa agent ni aya mbaya pamoja na chochote alichokifanya kuhusiana na jibu hilo.