Il-Kodifikazzjoni Aġentika bit-Tisħiħ tal-Għodod
F'din il-paġna
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à