Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Il-Kodifikazzjoni Aġentika bit-Tisħiħ tal-Għodod

Lezzjoni 6 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. X’inhi l-kodifikazzjoni aġentika?
  2. Iċ-ċiklu aġentiku
  3. Eżempju prattiku: tiswija ta’ bug
  4. L-użu tal-għodod fil-prattika
  5. Ċiklu aġentiku multi-turn
  6. Punti Ewlenin

Lezzjoni aġġornata fit-2 ta’ Novembru, 2026. L-eżempji oriġinali kienu jużaw Devstral, li tneħħa mill-API fil-31 ta’ Lulju, 2026. Issa jużaw Mistral Small 4 (mistral-small-2603), u ċ-ċiklu aġentiku jsegwi l-mudell tad-dokumentazzjoni ta’ Mistral (is-sejħiet kollha tal-għodod f’tweġiba jiġu pproċessati sakemm tintlaħaq it-tweġiba finali). Sors: Function calling.

X’inhi l-kodifikazzjoni aġentika?

Il-kodifikazzjoni aġentika tbiddel in-natura ta’ dak li titlob lill-mudell jagħmel. Minflok ma titlob biċċa kodiċi, imbagħad oħra, imbagħad it-tieleta, u tgħaqqadhom int stess, inti tassenja kompitu sħiħ. Il-mudell isolvih billi jgħaqqad il-passi waħdu: esplorazzjoni, ippjanar, implimentazzjoni u verifika. Int tibqa’ d-deċiżur dwar x’għandu jsir, iżda tieqaf timmaniġġja kull mossa fid-dettall.

Il-mudelli Devstral inbnew għal dan il-fluss tax-xogħol; il-mudelli ġenerali attwali, immexxija minn Mistral Small 4, jittrattawh permezz tas-sejħa tal-għodod (tool calling). Aġent ma jwieġibx biss mistoqsija; huwa jaġixxi fuq ir-repożitorju.

Iċ-ċiklu aġentiku

Fażi 1 — Fehim

L-aġent dejjem jibda billi jorjenta ruħu. Jaqra l-istruttura tal-folders u tal-fajls, jidentifika fajls rilevanti għall-kompitu mitlub, isegwi d-dipendenzi bejn il-moduli biex jara x’jista’ jaffettwa bidla, u jinnota konvenzjonijiet eżistenti—ismijiet, organizzazzjoni tat-testijiet u mudelli rikorrenti. Din il-fażi tidher mhux produttiva għax ma tikteb l-ebda kodiċi, madankollu tiddetermina jekk il-kodiċi li jirriżulta jidhirx bħal tiegħek jew bħal ta’ barrani.

Fażi 2 — Ippjanar

Qabel ma jikteb linja waħda, l-aġent ifformula pjan. Jifred il-kompitu f’sottokompiti ordnati, jiddistingwi l-fajls li għandhom jiġu mmodifikati minn dawk li għandhom jinħolqu, jantiċipa effetti sekondarji u riskji ta’ regressjoni, u jistabbilixxi approċċ tekniku. Dan huwa meta l-intervent tiegħek huwa l-irħas: li tikkoreġi pjan jieħu tletin sekonda; li tikkoreġi għaxar fajls li diġà ktibt tieħu ħafna iktar żmien.

Fażi 3 — Eżekuzzjoni

L-implimentazzjoni tiżvolġi l-pjan pass pass. L-aġent jeditja fajls eżistenti, joħloq oħrajn ġodda meta l-istruttura teħtieġ dan, jaġġorna l-importazzjonijiet u d-dipendenzi mċaqalqa mill-bidliet tiegħu, u jaġġusta fajls ta’ konfigurazzjoni matul it-triq. Il-konsistenza f’dawn il-bidliet hija eżattament dak li mudell ta’ tlestija (completion model) ma jistax jiggarantixxi.

Fażi 4 — Verifika

Fl-aħħar tiġi l-prova li x-xogħol jiflaħ. L-aġent iħaddem is-suite eżistenti tat-testijiet, jikteb testijiet ġodda għall-kodiċi li għadu kemm żied, jiżgura li l-bini (build) jgħaddi, u jerġa’ jirrevedi d-diff tiegħu stess għal żbalji jew modifiki stray. Aġent li jaqbeż din il-fażi jipproduċi kodiċi plawżibbli, mhux kodiċi korrett.

Eżempju prattiku: tiswija ta’ bug

Ejja ngħidu li tgħid lill-aġent: “L-utenti jirċievu żball 500 meta jissottomettu form b’email li fiha ’+’.” Iċ-ċiklu mbagħad jieħu din il-forma:

1. FEHIM
   -> Fittex fajls relatati mal-form (fittex "email" fil-kodiċi)
   -> Aqra l-kontroller li jimmaniġġja s-sottomissjoni
   -> Aqra l-funzjoni ta' validazzjoni tal-email
   -> Identifika r-regex li jiċħad '+'

2. IPPJANAR
   -> Immodifika r-regex tal-validazzjoni biex jaċċetta '+'
   -> Żid test tal-unità għal emails b'+'
   -> Ivvverifika li l-ebda parti oħra tal-kodiċi ma tifiltra '+'

3. EŻEKUZZJONI
   -> Immodifika src/validators/email.py: irranġa l-mudell regex
   -> Oħloq tests/test_email_validation.py: żid każijiet b'+'
   -> Immodifika src/controllers/form.py: żid log għad-debugging

4. VERIFIKA
   -> Ħaddem pytest -> it-testijiet kollha jgħaddu
   -> Iċċekkja d-diff -> il-bidliet huma konsistenti u minimi

Innota t-tielet linja tal-pjan: l-aġent mhux biss jissewwa fejn il-bug jidher; jiċċekkja li l-ebda filtru ieħor ma jiċħad il-karattru xi mkien ieħor. Din it-tfittxija għall-kawża primarja, minflok biss għas-sintomu, hija dak li jiddistingwi tiswija aġentika minn patch puntwali.

L-użu tal-għodod fil-prattika

L-aġent jaġixxi fuq l-ambjent tiegħu permezz ta’ sejħiet ta’ funzjonijiet. Int tiddikjara l-għodod disponibbli fit-talba, inkluż l-isem, id-deskrizzjoni u l-iskema tal-parametri tagħhom; il-mudell jagħżel liema sejħiet jagħmel u b’liema argumenti.

# Eżempju ta' konversazzjoni aġentika
messages = [
    {
        "role": "user",
        "content": "Żid validazzjoni b'saħħitha tal-password fil-modulu tal-auth."
    }
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Aqra l-kontenut ta' fajl tal-proġett",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "Mogħdija tal-fajl"}
                },
                "required": ["path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "write_file",
            "description": "Ikteb jew immodifika fajl tal-proġett",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string"},
                    "content": {"type": "string"}
                },
                "required": ["path", "content"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "run_command",
            "description": "Eżegwixxi kumand tal-shell",
            "parameters": {
                "type": "object",
                "properties": {
                    "command": {"type": "string"}
                },
                "required": ["command"]
            }
        }
    }
]

response = client.chat.complete(
    model="mistral-small-2603",
    messages=messages,
    tools=tools,
    tool_choice="auto",   # valur default: il-mudell jiddeċiedi jekk isejħix għodda
)

Għal din it-talba, is-sekwenza tipika tibda b’read_file("src/auth/validators.py") biex tifhem il-kodiċi eżistenti, tkompli b’read_file("tests/test_auth.py") biex tara l-format tat-testijiet attwali, imbagħad tgħaddi għall-kitba: write_file("src/auth/validators.py", ...) bir-regola ta’ validazzjoni miżjuda, write_file("tests/test_auth.py", ...) bil-każijiet il-ġodda, u finalment run_command("pytest tests/test_auth.py") biex tivverifika. L-ordni hija importanti: billi tiftaħ iż-żewġ fajls qabel ma tmiss karattru wieħed, l-aġent jilqa’ l-konvenzjonijiet tiegħek u jirriproduċihom, minflok ma jimporta dawk li ra xi mkien ieħor.

Ċiklu aġentiku multi-turn

L-ebda waħda minn dawn ma sseħħ f’sejħa waħda. Il-qalba tal-kodifikazzjoni aġentika hija ċ-ċiklu multi-turn: il-mudell jipproponi azzjoni, il-kodiċi tiegħek jeżegwixxiha, u inti tibgħat ir-riżultat lura biex ikun jista’ jiddeċiedi dwar il-pass li jmiss. Int iżżomm il-kontroll tal-eżekuzzjoni attwali, li sservi wkoll bħala l-gwardja tas-sigurtà tiegħek.

import json

TOOLS = {"read_file": read_file, "write_file": write_file, "run_command": run_command}

response = client.chat.complete(model="mistral-small-2603", messages=messages, tools=tools)
messages.append(response.choices[0].message)

for _ in range(30):   # gwardja: aġent qatt m'għandu jdur bla waqfien
    tool_calls = response.choices[0].message.tool_calls
    if not tool_calls:
        break         # l-ebda sejħa oħra tal-għodda: it-tweġiba finali waslet
    for tool_call in tool_calls:   # tweġiba tista' fiha sejħiet multipli
        name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        result = TOOLS[name](**arguments)
        messages.append({
            "role": "tool",
            "name": name,
            "content": str(result),
            "tool_call_id": tool_call.id,
        })
    response = client.chat.complete(model="mistral-small-2603", messages=messages, tools=tools)
    messages.append(response.choices[0].message)

print(response.choices[0].message.content)

Tliet dettalji huma importanti. Il-messaġġ tal-aġent u kull riżultat tal-għodda jerġgħu jiddaħħlu fl-istorja, mqabbla permezz ta’ tool_call_id: ħassar wieħed minnhom, u l-aġent jitlif il-fil, u jerġa’ jsejjaħ l-istess għodod fi ċiklu. Tweġiba waħda tista’ fiha sejħiet multipli tal-għodod, peress li sejħiet paralleli huma permessi b’mod default (parallel_tool_calls=False jipprojbixxihom): ipproċessahom kollha. Fl-aħħar, illimita n-numru ta’ dawriet u ħalli bniedem jivvalida l-kumandi tal-shell u l-kitbiet tal-fajls: aġent li jeżegwixxi kull ma jipproponi huwa riskju, mhux iffrankar ta’ ħin.

Punti Ewlenin

  • Il-kodifikazzjoni aġentika ssegwi ċiklu: fehem, ippjana, eżegwixxi, ivverifika
  • L-aġent jaġixxi fuq ir-repożitorju permezz tas-sejħa tal-għodod (tools, tool_choice)
  • Iċ-ċiklu multi-turn jippermetti lill-aġent jirrepeti sakemm jinkiseb riżolviment sħiħ
  • L-aġent jimmodifika fajls multipli b’mod konsistenti f’kompitu wieħed
  • Il-fażi ta’ verifika (testijiet, build) hija essenzjali għall-affidabbiltà