L-Aħjar Prattiki u l-Passi Li Jmiss
F'din il-paġna
X’Għamilt S’issa
Mxejt matul l-API tal-Aġenti ta’ Mistral kollu. Ejja nagħmlu rikapitolu qabel ma nidħlu fil-prattiki tal-produzzjoni, peress li kull parti ta’ dan il-kors tibni fuq dik ta’ qabilha.
L-ewwel tliet lezzjonijiet poġġew il-fondazzjoni: aġent tal-AI huwa sistema awtonoma b’ċiklu ta’ percezzjoni-azzjoni; l-API tistrieħ fuq tliet oġġetti—Agent, Conversation, u Entry; u dak li jifred aġent minn chatbot huwa l-persistenza, l-għodod, u l-handoffs. Il-lezzjonijiet 4 sa 7 għamlu dawn l-oġġetti użabbli: ħolqot u kkonfigurat aġenti b’client.beta.agents.create(), żammejt konversazzjonijiet persistenti b’conversations.start() u conversations.append(), u użajt il-modalità diretta mingħajr aġent meta tkun qed tipprototipa u l-persistenza ma żżidx valur.
Il-lezzjonijiet 8 sa 11 żiedu kapaċitajiet. web_search jagħtik aċċess għal informazzjoni attwali b’ċitazzjonijiet awtomatiċi; code_interpreter iħaddem Python f’sandbox, u jagħti lill-aġent riżultati eżatti fejn il-mudell waħdu kien japprossima biss; image_generation jipproduċi viżwali minn prompts tat-test; document_library iġib RAG integrat għad-dokumenti tiegħek stess. Imbagħad, il-lezzjonijiet 12 sa 16 wrew diversi aġenti jaħdmu flimkien: l-handoffs jittrasferixxu l-kontroll minn aġent għal ieħor, l-arkitettura ta’ referenza tgħaqqad router ċentrali ma’ speċjalisti, il-modalità server tawtomatizza fejn il-modalità client iżommek fiċ-ċiklu, u l-katina illimitata timxi f’mudelli lineari, bi stilel (star), u ibridi. Fl-aħħar nett, il-Lezzjoni 17 għalqet kollox bil-guardrails, il-prinċipju tal-inqas privileġġ, u l-moderazzjoni upstream.
Iddisinja Aġenti Li Jiflu
Sentenza waħda tiġbor il-kors kollu: aġent wieħed, responsabbiltà waħda, deskrizzjoni waħda li tgħid meta għandek isejħilu. Il-kuntrast hawn taħt jagħmel id-differenza tanġibbli.
# GOOD — specialized agent with precise description
agent = client.beta.agents.create(
model="mistral-large-latest",
name="invoice-processor",
description="Processes invoices: extracts amounts, dates, vendors.",
instructions="Extract invoice information into structured JSON.",
tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)
# BAD — generic, vague agent
agent = client.beta.agents.create(
model="mistral-large-latest",
name="helper",
description="A helpful agent.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)
It-tieni aġent se jfalli f’żewġ modi fl-istess ħin. L-ebda router ma jkun jaf meta għandu jgħaddi talba lilu, għax “aġent li jgħin” ma jiddeskrivi l-ebda sitwazzjoni. U meta jiġi msejjaħ, it-tliet għodod tiegħu jħalluh liberu li jfittex fil-web għal xi ħaġa li kellu jikkalkula, jew li juri b’immaġni xi ħaġa li ntalab janalizza.
L-Immaniġġjar tal-Iżbalji
Is-sejħiet tan-network ifallu qabel jew wara. Retry b’backoff esponenzjali jassorbi inċidenti tranżitorji mingħajr ma jibdel tnaqqis fil-veloċità f’interruzzjoni viżibbli.
import time
def safe_conversation(agent_id, query, max_retries=3):
"""Conversation with error handling and retry."""
for attempt in range(max_retries):
try:
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Exponential backoff
return None
Il-backoff esponenzjali—sekonda, imbagħad tnejn, imbagħad erbgħa—jiddistingwi retry ċivili milli tħabbat fuq servizz li diġà qed isofri. Innota wkoll li l-aħħar tentattiv jerġa’ jqajjem l-eċċezzjoni minflok ma jirritorna None: min sejjaħlek irid ikun jaf li l-operazzjoni falliet.
Tara X’Qed Jiġri
Fil-produzzjoni, fluss ta’ ħidma multi-aġent li ma tistax tosserva jsir impossibbli li tiddibbuggjah. Il-modalità client tagħtik eżattament il-hooks li għandek bżonn.
import logging
import time
logger = logging.getLogger("agents")
def monitored_conversation(agent_id, query):
"""Conversation with monitoring."""
start = time.time()
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query,
handoff_execution="client"
)
handoff_count = 0
tool_count = 0
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_count += 1
logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
elif entry.type == "tool.execution":
tool_count += 1
logger.info(f"Tool #{tool_count}: {entry.tool_name}")
duration = time.time() - start
logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")
return response
Dawk iż-żewġ kontituri jiswew aktar milli tissuġġerixxi s-sempliċità tagħhom: devjazzjoni fin-numru medju ta’ handoffs tissuġġerixxi router li qed jittardja; qawmien f’daqqa f’sejħiet tal-għodod jindika mistoqsijiet għaljin.
Il-kontroll tal-ispejjeż imbagħad jinżel għal deċiżjonijiet konkreti. Immonitorja t-tokens għal kull konversazzjoni, peress li dik hija l-unità reali tal-fatturazzjoni. Uża mistral-medium-latest kull fejn mistral-large-latest ma jżidx xejn—l-ewwel livell ta’ appoġġ huwa eżempju klassiku. Illimita max_tokens f’completion_args biex tevita tweġibiet bla tmiem għal mistoqsijiet sempliċi, u ddiżattiva l-ħażna b’store=False meta l-persistenza mhix meħtieġa.
Ittestjar tar-Routing
Ittestja sistema multi-aġent bħal kull ċentralin: agħtiha każijiet li taf fejn għandhom imorru, u vverifika fejn jinżlu.
def test_agent_routing():
"""Verifies that the router distributes correctly."""
test_cases = [
("What is the price of Bitcoin?", "web-search-agent"),
("Calculate 25 * 48", "calculator-agent"),
("Summarize this document", "doc-agent"),
]
for query, expected_agent_name in test_cases:
response = client.beta.conversations.start(
agent_id=router.id,
inputs=query,
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target = client.beta.agents.get(agent_id=entry.next_agent_id)
assert target.name == expected_agent_name, \
f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"
Ibni din is-suite ta’ testijiet maż-żmien: kull talba mgħoddija ħażin li taqbad fil-produzzjoni ssir linja oħra f’test_cases, u tkun taf li l-kitba mill-ġdid ta’ deskrizzjoni tissewwa l-każ fil-mira mingħajr ma tkisser ieħor.
Arkitettura ta’ Referenza
Għal proġett tal-produzzjoni, hawnhekk arkitettura rrakkomandata:
Application
│
▼
Moderator Agent (filters requests)
│
▼
Router Agent (distributes to specialists)
├── Search Agent (web_search)
├── Analysis Agent (code_interpreter)
├── Documents Agent (document_library)
└── Creation Agent (image_generation)
│
▼
Logging + Monitoring + Alerting
Tiġbor flimkien kollox minn dan il-kors: il-moderatur jiffiltra qabel kull eżekuzzjoni, ir-router jidderieġi mingħajr qatt ma jwieġeb huwa stess, kull speċjalista jġorr għodda waħda u responsabbiltà waħda, u l-osservazzjoni ddur mas-sistema kollha.
Fejn Imur Minn Hawn
Erba’ direzzjonijiet jestendu dak li tista’ tagħmel issa. Function calling jħallik tibni l-għodod personalizzati tiegħek lil hinn minn dawk integrati: sejjaħ API tan-negozju, staqsi database, attiva servizz intern. MCP Servers jintegraw il-Model Context Protocol, li jistandardizza kif l-għodod jiġu esposti. Structured outputs jfurzaw it-tweġibiet f’skema JSON, li tbiddel kollox meta l-output ta’ aġent jingħata lil sistema oħra minflok qarrej uman. Fl-aħħar nett, streaming jirritorna tweġibiet f’ħin reali minflok f’blokk wieħed—deċiżiv fuq katini twal, fejn l-istennija silenzjuża ssir skomda.
Tliet riżorsi jakkumpanjaw dan il-pass li jmiss: id-dokumentazzjoni uffiċjali fuq docs.mistral.ai/agents, il-cookbooks ta’ Mistral li jipprovdu eżempji sħaħ ta’ implimentazzjoni, u r-Referenza tal-API li tiddokumenta kull endpoint fid-dettall.
Punti Ewlenin
- Speċjalizza l-aġenti tiegħek—aġent wieħed = responsabbiltà waħda
- Immonitorja—irreġistra kull handoff u eżekuzzjoni ta’ għodda
- Ittestja—ivvalida r-routing u t-tweġibiet ta’ kull aġent
- Issikra—guardrails, inqas privileġġ possibbli, moderazzjoni upstream
- Ottimizza l-ispejjeż—mudell tad-daqs it-tajjeb, max_tokens, store=False meta possibbli
- L-Aġenti ta’ Mistral huma fil-beta—żomm ruħek aġġornat mal-bidliet tal-API
Ittestja l-Għarfien Tiegħek
Aġenti, għodod integrati, handoffs: fadal xi punti għomja fl-API tal-Aġenti?
1. Meta huwa meħtieġ aġent—u meta biżżejjed chatbot?
Tweġiba: Aġent huwa ġustifikat meta għandek bżonn għodod, persistenza, u deċiżjonijiet f’diversi passi; għal mistoqsijiet u tweġibiet sempliċi, konversazzjoni standard hija biżżejjed—l-arkitettura ssegwi l-ħtieġa.
2. X'jimmaniġġjaw il-konversazzjonijiet persistenti fl-API tal-Aġenti?
Tweġiba: L-istorja fuq in-naħa ta’ Mistral: tkompli konversazzjoni bl-ID tagħha mingħajr ma terġa’ tibgħat il-kuntest kollu—l-istat isir servizz.
3. Elenska l-għodod integrati disponibbli u l-użu tagħhom.
Tweġiba: web_search (informazzjoni f’ħin reali), code_interpreter (ħaddem Python), image_generation (oħloq immaġnijiet), document_library (mistoqsijiet u tweġibiet dwar il-fajls tiegħek)—kapaċitajiet lesti għall-użu, mingħajr bżonn ta’ implimentazzjoni.
4. Kif taħdem sistema multi-aġent b'handoffs?
Tweġiba: Router jikkwalifika t-talba u jgħaddiha lill-aġent speċjalista kompetenti; kull aġent jibqa’ sempliċi, l-orkestrazzjoni tipprovdi kopertura—u l-handoffs jgħaqqdu fil-fond.
5. Kif tissikra l-aġenti fil-produzzjoni?
Tweġiba: B’guardrails fuq l-inputs/outputs, għodod b’ambitu ristrett, traċċabbiltà tal-azzjonijiet, u validazzjoni umana fuq deċiżjonijiet b’riskju għoli—l-awtonomija tinkiseb permezz tal-kontroll.
Aġenti speċjalizzati, għodod integrati, routing, guardrails: l-arkitettura sħiħa tidħol f’erba’ kliem—u dan il-kors ħallek tibni kull wieħed minnhom.