Oħloq aġenti speċjalizzati u router
F'din il-paġna
Mit-teorija għall-prattika
Il-lezzjoni ta’ qabel introduċiet il-kunċett ta’ trasferimenti (handoffs). Issa se tibni s-sistema sħiħa fl-ordni reali tal-kostruzzjoni: l-ewwel l-ispeċjalisti, imbagħad ir-router, wara l-konnessjonijiet bejniethom, u fl-aħħar il-konversazzjoni li tħaddem kollox. Dan l-ordni mhix arbitrarja—ir-router jista’ jipponta biss lejn aġenti li diġà jeżistu.
Pass 1: Oħloq l-aġenti speċjalisti
Kull aġent jirċievi qasam preċiż ta’ kompetenza u xejn aktar.
from mistralai.client import Mistral
from mistralai.client.models import CompletionArgs, ResponseFormat, JSONSchema
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Aġent ta' tfittxija fuq il-web
web_agent = client.beta.agents.create(
model="mistral-large-latest",
name="web-search-agent",
description="Aġent li jfittex informazzjoni online.",
instructions="Wettaq tfittxijiet preċiżi fuq il-web. Iċċita dejjem is-sorsi tiegħek.",
tools=[{"type": "web_search"}]
)
# Aġent finanzjarju
finance_agent = client.beta.agents.create(
model="mistral-large-latest",
name="finance-agent",
description="Aġent speċjalizzat f'mistoqsijiet finanzjarji.",
instructions="""Inti espert finanzjarju.
- Uża data numerika
- Spjega l-kunċetti b'mod ċar
- Issiġġala r-riskji"""
)
# Aġent kalkolatur
calculator_agent = client.beta.agents.create(
model="mistral-large-latest",
name="calculator-agent",
description="Aġent għal kalkoli matematiċi dettaljati.",
instructions="Spjega kull pass tal-kalkolu. Uża l-interpretatur tal-kodiċi għal kalkoli kumplessi.",
tools=[{"type": "code_interpreter"}]
)
Dawn l-erba’ oqsma għandhom rwoli differenti ħafna, u wieħed minnhom jeħtieġ attenzjoni speċjali. L-isem (name) fil-format kebab-case huwa għalik: jidher fil-logs u t-testijiet tiegħek, u isem li jinqara jiffrankalek milli tqabbel IDs opaki. L-instructions jindirizzaw lill-mudell ladarba jibda jaħdem, allura jridu jkunu speċifiċi għad-dominju—“issiġġala r-riskji” ifisser xi ħaġa għal aġent finanzjarju, filwaqt li “kun ta’ għajnuna” ma tfisser xejn għal ħadd. L-għodod (tools) isegwu l-prinċipju tan-neċessità stretta: l-aġent finanzjarju hawn fuq m’għandux għodod għax jirraġuna mingħajr ma jeħtieġhom, u li tagħtih għodod sempliċiment tistieden użu ħażin. Fl-aħħar nett, id-description mhix dokumentazzjoni: hija t-test li l-aqra r-router biex jiddeċiedi jekk jittrasferixxix hawn jew f’post ieħor.
Pass 2: Oħloq l-aġent router
Ir-router m’għandux għodod. Ix-xogħol kollu tiegħu jikkonsisti fl-analiżi tat-talba u l-għażla tar-riċevitur.
router_agent = client.beta.agents.create(
model="mistral-large-latest",
name="router-agent",
description="Aġent router li jqassam it-talbiet.",
instructions="""Inti orkestratur.
Analiża kull talba u ttrasferixxi lill-aġent it-tajjeb:
- Mistoqsijiet li jeħtieġu data online → web-search-agent
- Mistoqsijiet finanzjarji → finance-agent
- Kalkoli u analiżi numerika → calculator-agent
Qatt ma twieġeb direttament—dejjem ittrasferixxi."""
)
Dik l-aħħar linja tipprevjeni s-sistema milli tiġi fi tmiemha. Mingħajrha, router mibni fuq mudell kbir se jwieġeb mistoqsijiet li jidhlu faċli għalih, jibypassja l-ispeċjalisti tiegħek, u jipproduċi tweġibiet mingħajr l-għodod li kienu jużaw. tispiċċa b’arkitettura multi-aġent fejn nofs l-aġenti qatt ma jintużaw.
Pass 3: Iddefinixxi l-miri tat-trasferiment
Issa trid tgħid lir-router liema aġenti huwa permess li jittrasferixxi lejhom.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
Il-parametru handoffs jieħu lista ta’ IDs ta’ aġenti, u r-router jista’ jittrasferixxi għal kwalunkwe wieħed minnhom. Dan mhuwiex privileġġ riżervat għar-router: l-ispeċjalisti jistgħu wkoll jiddikjaraw il-miri tagħhom stess.
# L-aġent finanzjarju jista' jittrasferixxi għat-tfittxija fuq il-web u l-kalkolatur
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Katina bħal router → finanzja → tfittxija fuq il-web → kalkolatur issir possibbli. Meta l-aġent finanzjarju jiffaċċja mistoqsija li teħtieġ rata attwali, ma jerġax lura għar-router: imur direttament għall-ispeċjalista li jeħtieġ, eżatt bħal konsulent li ċempel lil kollega minflok ma jerġa’ jgħaddi mir-reċezzjoni.
Pass 4: Ibda l-konversazzjoni
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Sib ir-rata tal-imgħax ewlenija attwali tal-BĊE u kkalkula l-imgħax kompost fuq 10 snin għal €100,000."
)
# Analiża tal-fluss
for entry in response.outputs:
if entry.type == "agent.handoff":
print(f"[HANDOFF] → {entry.next_agent_id}")
elif entry.type == "tool.execution":
print(f"[TOOL] {entry.tool_name}")
elif entry.type == "message.output":
print(f"[RESPONSE] {entry.content[:200]}...")
Esegwixxi din it-talba u osserva t-traċċa qabel ma tħares lejn it-tweġiba. Għandek tara żewġ trasferimenti u mill-inqas eżekuzzjoni waħda ta’ għodda; jekk ma tarax xejn, ir-router tiegħek wieġeb waħdu, u wasal iż-żmien li tissaħħaħ l-istruzzjonijiet tiegħu.
Il-leva ewlenija: id-deskrizzjoni
Meta r-routing ifalli, id-deskrizzjoni hija kważi dejjem il-ħatija. Ir-router ma jafx l-intenzjonijiet tiegħek; jaqra biss dan it-test għal kull aġent kandidat.
# Ħażin — wisq vag
description="Aġent utli."
# Tajjeb — ir-router jmeta jrid jittrasferixxi
description="Aġent li jfittex informazzjoni attwali fuq l-Internet u jiċċita s-sorsi tiegħu."
Ikteb kull deskrizzjoni bħala tweġiba għall-mistoqsija “f’liema każ għandi nsejjaħ lil dan l-aġent?” minflok bħala sommarju ta’ x’inhu. It-tieni eżempju jsemmi s-sitwazzjoni—informazzjoni attwali, fuq l-Internet—filwaqt li l-ewwel iħalli lir-router jissuspetta. Ivverifika wkoll li l-ebda par ta’ deskrizzjonijiet ma jikkoinċidi: żewġ aġenti deskritti b’termini simili se jipproduċu routing instabbli minn eżekuzzjoni għall-oħra.
Eżempju sħiħ
Hawnhekk hija l-verżjoni kkondensata, b’handoffs mgħoddija direttament waqt il-ħolqien tar-router peress li l-ispeċjalisti diġà jeżistu f’dak il-punt.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Aġenti speċjalisti
research = client.beta.agents.create(
model="mistral-large-latest",
name="research-agent",
description="Tfittxija ta' informazzjoni online b'sorsi.",
tools=[{"type": "web_search"}]
)
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="analyst-agent",
description="Analiżi tad-data u kalkoli b'Python.",
tools=[{"type": "code_interpreter"}]
)
writer = client.beta.agents.create(
model="mistral-large-latest",
name="writer-agent",
description="Abbozzar ta' rapporti strutturati u professjonali.",
instructions="Ikteb rapporti ċari b'introduzzjoni, analiżi u rakkomandazzjonijiet."
)
# 2. Router b'trasferimenti
router = client.beta.agents.create(
model="mistral-large-latest",
name="router",
description="Jorkestra talbiet kumplessi.",
instructions="Analiża t-talba u ttrasferixxi lill-ispeċjalista xieraq.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Tnedija
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analiża s-suq Ewropew tal-cloud computing fl-2026: daqs, atturi, tendenzi."
)
Punti Ewlenin
- Oħloq aġenti speċjalisti b’deskrizzjonijiet preċiżi u orjentati lejn il-kompitu
- Ir-router juża d-deskrizzjonijiet biex jagħżel l-aġent fil-mira
client.beta.agents.update(handoffs=[...])jiddefinixxi l-miri tat-trasferiment- It-trasferimenti jistgħu jkunu mbejjna (aġent A → aġent B → aġent C)
- Id-deskrizzjoni ta’ kull aġent hija l-leva primarja għall-kwalità tar-routing