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

L-Aħjar Prattiki u l-Passi Li Jmiss

Lezzjoni 18 / 18 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. X’Għamilt S’issa
  2. Iddisinja Aġenti Li Jiflu
  3. L-Immaniġġjar tal-Iżbalji
  4. Tara X’Qed Jiġri
  5. Ittestjar tar-Routing
  6. Arkitettura ta’ Referenza
  7. Fejn Imur Minn Hawn
  8. Punti Ewlenin
  9. Ittestja l-Għarfien Tiegħek

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.