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 kuu inayofanya 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 pale mambo yanapoharibika. Ikiwa unaweza kumwelezea mtu mwingine mzunguko huo, umelijua jambo hilo. Ikiwa unaweza kutaja tu framework, hujajua.

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 mahitaji ya msingi ni fupi, na ni fupi kuliko kurasa nyingi za kozi zinavyopendekeza.

• Unaweza kusoma na kuandika Python au TypeScript katika kiwango cha script 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. Huna haja ya nadharia ya machine learning, na huna haja ya kuwa umefunza (train) model. 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 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, na uangalie idadi ya token kwenye response. 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. Unaelezea function kwa model kama jina, maelezo, na JSON (JavaScript object notation) schema kwa ajili ya inputs zake. Model haiendeshi kitu chochote. Inajibu kwa ombi lililopangwa: ita run_command kwa 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.

Chatbot huishia baada ya jibu moja. Wakala hurudia mabadilishano hayo hadi model iache kuomba zana. Kurudia huko ndiko tofauti nzima, na ndiyo sababu aina za kufeli (failure modes) pia hutofautiana. Chatbot hutoa jibu lisilo sahihi mara moja. Wakala hufanyia kazi jibu lisilo sahihi mara kadhaa kabla ya mtu yeyote kugundua.

Hatua ya 2: andika loop mwenyewe, mara moja

Usianze na framework. Andika takriban mistari thelathini 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 uliofanikiwa huchapisha aya moja inayotaja mifumo yako ya faili (filesystems) na nafasi iliyo wazi, kwa sababu modeli iliuliza df -h, msimbo wako uliitekeleza, 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 maadili yakibadilika.

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 itaacha au itazunguka 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 zinazoweza kufikia nje ya mfumo: mfumo wa tiketi, database, au repository. Kuandika wrapper maalum kwa kila huduma, kwa kila wakala, hakukui kulingana na mahitaji.

Model Context Protocol (MCP) ndiyo suluhisho ambalo sekta imekubaliana nalo. Seva ya MCP hutoa seti ya zana kupitia usafirishaji wa kawaida, na wakala yeyote anayeelewa MCP anaweza kuitumia bila kuhitaji muunganisho maalum. Seva ya kumbukumbu ya faili (filesystem server) ni amri moja tu:

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

Hii inahitaji Node kusakinishwa, na hoja ya saraka (directory argument) ndiyo njia pekee ambayo seva itagusia. Huu ndio mfano wa usalama kwa ufupi: seva ndiyo huamua mipaka, siyo modeli. Elekeza mteja (client) kwenye seva hiyo na wakala wako atapata uwezo wa kusoma na kuandika faili ambazo hukuziandika wewe. Kuendesha hizi vizuri, chini ya akaunti ya huduma na kwa chaguzi za usafirishaji zilizoelezwa, kimefunikwa katika kuendesha seva za MCP kwenye VPS kwa ajili ya mawakala wa uandishi wa AI.

Somo la hatua hii ni kwamba usanifu wa zana ndio kazi halisi. Maelezo yasiyo wazi humfanya modeli kubahatisha. Zana inayorejesha herufi elfu arobaini huchafua dirisha la muktadha (context window). Zana inayoweza kufuta vitu hatimaye itafuta vitu.

Hatua ya 4: kumbukumbu, ambayo kimsingi ni faili tu

Wanaoanza hapa hukimbilia kutumia vector database. Usifanye hivyo, angalau si kwa sasa.

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

Kwa tatizo la pili, faili la kawaida la markdown ambalo wakala anaweza kusoma na kuandika linashinda vector database kwa karibu kila mradi wa kwanza. Mpe faili moja, mwambie muundo wake, mwambie asome faili hilo kabla ya kuanza na alisasishe anapojifunza kitu kipya. Unapata manufaa mengi, na unaweza kufungua faili hilo 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 huku ukimwangalia. Hatua ya 5 ni kuifanya kazi hiyo iendelee hata usipokuwepo.

Maswali manne huamua kama wakala anayefanya kazi bila kusimamiwa yuko salama kuachwa peke yake. Nini kinachomchochea (trigger), ili asifanye kazi bila sababu. Je, anafanya kazi ndani ya mipaka ipi, ili kosa dogo lisilete madhara makubwa. Matokeo yanathibitishwaje, kwa sababu wakala anayejipima mwenyewe kazi zake atajipa alama za juu kila wakati. Ni bajeti ipi inayomzuia, iwe ni kwa idadi ya 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 unakijumuisha.

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 ukomo kinachofanya kwenye bili yako ya tokens. Fanya hivyo mara moja ukiwa na 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 asiye na upendeleo (unprivileged user), kamwe usiiendeshe kama root wala kama akaunti yako binafsi, ili wigo wa madhara uishie kwenye saraka (directory) badala ya mashine nzima. Weka vitambulisho (credentials) mbali na uwezo wa modeli, kwa sababu chochote kilichopo kwenye context window kinaweza kunukuliwa na kutolewa nje kupitia tool call, na suluhisho lake ni kutumia token zenye muda mfupi wa kuishi nyuma ya kisaidizi kama ilivyoelezwa katika kuzuia siri zisifikiwe na AI agents wako. Weka kikomo cha juu cha matumizi ya fedha, kwa sababu kitanzi (loop) kisichosimamiwa hutoa bili kwa kila mzunguko bila mtu yeyote kuangalia, na vikomo pamoja na batching vinavyoiweka katika hali ya usalama viko katika udhibiti wa gharama za AI agent kwenye VPS inayowaka muda wote.

Gharama inastahili namba moja kamili. Kufikia Julai 2026, Claude Opus 5 inatoza $5 kwa kila milioni moja ya input tokens na $25 kwa kila milioni moja ya output tokens, na wakala anayepiga gumzo akituma tena mazungumzo yanayokua anaweza kusukuma mamia ya maelfu ya tokens kupitia kazi moja. Prompt caching, na modeli ndogo kwa ajili ya hatua za kawaida, hubadilisha hesabu hiyo zaidi kuliko marekebisho yoyote ya prompt.

Prompt injection pia inahusika hapa. Ikiwa wakala wako anasoma ukurasa wa wavuti, mfumo wa kufuatilia masuala (issue tracker), au kikasha cha barua pepe, basi yeyote aliyeandika maandishi hayo anatoa maagizo pia kwa wakala wako. Ulinzi wake si mfumo wa prompt wenye ujanja zaidi. Ulinzi ni mipaka, kwa sababu wakala asiyeweza kufuta hazina (repository) hawezi kushawishiwa kufuta moja.

Ni mtaala upi unapaswa kuufuata?

Chagua mtaala mmoja na uumalize badala ya kujaribu sita kwa wakati mmoja. Hifadhi ya ai-agents-for-beginners ya Microsoft ndiyo iliyo kamili zaidi bila malipo, ikiwa na kozi ya masomo kumi na nane ambayo imevuka nyota 70,000 kufikia Julai 2026, na inalingana vyema na hatua zilizotajwa hapo juu. Orodha za hifadhi za mawakala (agents) zinazovuma ni muhimu kwa kuona kile kilichopo, lakini hazifai sana kama mtaala, kwa sababu orodha iliyopangwa kwa nyota hufuata 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 kurekebishika. 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, ulinganifu katika mawakala bora wa AI wanaojiendesha (self-hosted) unaonyesha jinsi miradi kadhaa inavyotatua kitanzi kilekile kwa njia tofauti.

Inachukua muda gani?

Kwa mtu ambaye tayari anajua kupanga programu, hatua ya 1 na 2 huchukua jioni moja. Hatua ya 3 huchukua wikendi nzima, ambapo muda mwingi hutumika kusoma maelezo ya zana badala ya itifaki yenyewe. Hatua ya 4 na 5 huchukua wiki chache za matumizi ya kweli, kwa sababu unajifunza kile ambacho 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 yako itafanya kazi ni usanifu wa schema kwa ajili ya zana, ushughulikiaji wa makosa (error handling), na ruhusa za Linux. Nadharia ya machine learning inakuwa muhimu 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 bila kutumia maktaba za nje, 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 kabla ya hapo. Wakati agent yako inapofanya kazi vibaya, inabidi uchunguze orodha ya ujumbe na matokeo ya zana moja kwa moja, na hilo ni gumu zaidi ikiwa hujawahi kuyaona. Baada ya kuandika loop yako mwenyewe mara moja, framework itakuokoa muda badala ya kuficha utaratibu wa ndani.

Gharama ya kujifunza AI agents ni kiasi gani?

Ni ndogo kuliko watu wengi wanavyotarajia, ukiweka mipaka. API key ya huduma ya mtandaoni na VPS ndogo vinatosha kwa hatua hizi zote sita. Hatari halisi si gharama ya saa, bali ni loop isiyo na kikomo inayotoa bili kila mzunguko wakati umelala. Weka kikomo cha matumizi kwenye akaunti yako ya API siku ya kwanza, ongeza kikomo cha mzunguko (iteration cap) kwenye kila loop unayoandika, na tumia model ya bei nafuu kwa hatua za kawaida. Kuendesha model kwenye mashine yako (locally) huondoa bili ya tokens na kuibadilisha na mahitaji ya vifaa (hardware).

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 kunakoiwezesha agent kumaliza kazi yenye hatua kadhaa, na ndiyo sababu agents zinahitaji 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 ilichokifanya kuhusiana na jibu hilo.