Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Parimad tavad ja järgmised sammud

Õppetund 18 / 18 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Mida sa õppisid
  2. Agentide kujundamine, mis peavad vastu
  3. Vigade käsitlemine
  4. Toimuva jälgimine
  5. Ruutimise testimine
  6. Referentsarhitektuur
  7. Kuhu edasi minna
  8. Peamised punktid
  9. Testi oma teadmisi

Mida sa õppisid

Sa käisid läbi kogu Mistral Agents API. Teeme kokkuvõtte enne, kui sukeldume tootmiskeskkonna tavadesse, sest iga osa selles kursuses tugineb eelnevale.

Esimesed kolm õppetundi lõid aluse: tehisintellekti agent on autonoomne süsteem taju-tegevuse tsükliga; API põhineb kolmel objektil – Agent, Conversation ja Entry; ning see, mis eristab agenti vestlusrobotist, on püsivus, tööriistad ja üleandmised. Õppetunnid 4 kuni 7 tegid need objektid kasutatavaks: agentide loomine ja konfigureerimine käsuga client.beta.agents.create(), püsivate vestluste haldamine käsudega conversations.start() ja conversations.append() ning otsese režiimi kasutamine ilma agentita, kui lood prototüüpi ja püsivus ei too lisaväärtust.

Õppetunnid 8 kuni 11 lisasid võimekusi. web_search annab juurdepääsu aktuaalsele infole automaatsete viidetega; code_interpreter käivitab Pythoni liivakastis, pakkudes agendile täpseid tulemusi seal, kus mudel üksinda annaks vaid ligikaudse hinnangu; image_generation loob visuaale tekstisisendite põhjal; document_library toob integreeritud RAG-i sinu enda dokumentidesse. Õppetunnid 12 kuni 16 näitasid seejärel mitme agendi koostööd: üleandmised kannavad juhtimise ühelt agendilt teisele, referentsarhitektuur paigutab keskse ruuteri koos spetsialistidega, serverirežiim automatiseerib protsesse, samas kui kliendirežiim hoiab sind otsustusprotsessis sees, ja piiramatu aheldamine jaguneb lineaarseteks, tähe- ja hübriidmustriteks. Lõpuks võttis õppetund 17 kõik kokku kaitseraudteede, minimaalsete õiguste printsiibi ja sisendmoderatsiooniga.

Agentide kujundamine, mis peavad vastu

Üks lause võtab kokku kogu kursuse: üks agent, üks vastutus, üks kirjeldus, mis ütleb, millal seda kutsuda. Allpool toodud kontrast teeb erinevuse käegakatsutavaks.

# HEA – spetsialiseerunud agent täpse kirjeldusega
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]}]
)

# HALB – üldine, ebamäärane 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"}]
)

Teine agent ebaõnnestub korraga kahel viisil. Ükski ruuter ei tea, millal talle päringut edasi suunata, sest „abivalmis agent“ ei kirjelda ühtegi konkreetset olukorda. Ja kui seda siiski kutsutakse, võimaldavad selle kolm tööriista tal otsida veebist midagi, mida ta oleks pidanud arvutama, või illustreerida midagi, mida paluti analüüsida.

Vigade käsitlemine

Võrgupäringud ebaõnnestuvad varem või hiljem. Korduvkatse eksponentsiaalse taganemisega neelab ajutised intsidentid, muutmata hetkelist aeglustumist nähtavaks katkestuseks.

import time

def safe_conversation(agent_id, query, max_retries=3):
    """Vestlus veakäitluse ja korduvkatsega."""
    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)  # Eksponentsiaalne taganemine
    return None

Eksponentsiaalne taganemine – üks sekund, siis kaks, siis neli – eristab viisakat korduvkatset teenuse pommitamisest, mis niigi raskustes on. Pane tähele ka seda, et viimane katse viskab erandi uuesti välja, selle asemel et tagastada None: sinu kutsuja peab teadma, et operatsioon ebaõnnestus.

Toimuva jälgimine

Tootmiskeskkonnas muutub mitme agendiga töövoog, mida sa jälgida ei saa, võimatuks siluda. Kliendirežiim annab sulle täpselt need konksud, mida vajad.

import logging
import time

logger = logging.getLogger("agents")

def monitored_conversation(agent_id, query):
    """Vestlus jälgimisega."""
    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

Need kaks loendurit on väärtuslikumad, kui nende lihtsus esmapilgul vihjab: keskmine üleandmiste arvu kõrvalekalle annab märku ruuterist, mis kõhkleb; tööriistakutsete tipp viitab kallitele päringutele.

Kulude kontroll taandub seejärel konkreetsetele otsustele. Jälgi tokenite arvu vestluse kohta, sest see on tegelik arveldusühik. Kasuta mistral-medium-latest seal, kus mistral-large-latest midagi ei lisa – esimene tugitase on selle õpikunäide. Piira max_tokens väärtust completion_args sees, et vältida lõpmatuid vastuseid lihtsatele küsimustele, ja keela salvestamine parameetriga store=False, kui püsivust ei vajata.

Ruutimise testimine

Testi mitme agendiga süsteemi nagu ükskõik millist kommutaatorit: sööda sellele juhtumeid, mille oodatav sihtkoht on teada, ja kontrolli, kuhu need jõuavad.

def test_agent_routing():
    """Kontrollib, kas ruuter jaotab päringuid õigesti."""
    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}"

Koosta see testikomplekt aja jooksul: iga tootmises tabatud valesti suunatud päring muutub uueks reaks test_cases loendis ja sa tead, et kirjelduse ümberkirjutamine parandab sihtjuhtumi, rikkumata seejuures teisi.

Referentsarhitektuur

Tootmisprojekti jaoks on siin soovitatav arhitektuur:

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

See toob kokku kõik sellest kursusest õpitu: moderaator filtreerib enne igasugust täitmist, ruuter suunab ilma ise kunagi vastamata, iga spetsialist kannab üht tööriista ja üht vastutust ning jälgimine ümbritseb kogu süsteemi.

Kuhu edasi minna

Neli suunda laiendavad seda, mida sa nüüd teha saad. Function calling võimaldab sul luua oma kohandatud tööriistu lisaks sisseehitatutele: kutsu äpi, päri andmebaasi või käivita sisene teenus. MCP Servers integreerivad Model Context Protocoli, mis standardiseerib tööriistade avaldamise viisi. Structured outputs sunnivad vastused JSON skeemi, mis muudab kõike, kui agendi väljund toidab teist süsteemi, mitte inimlugejat. Lõpuks, streaming tagastab vastused reaalajas ühe ploki asemel – otsustava tähtsusega pikkades ahelates, kus vaikne ootamine muutub ebamugavaks.

Selle järgmise sammuga kaasnevad kolm ressurssi: ametlik dokumentatsioon aadressil docs.mistral.ai/agents, Mistrali kokaraamatud, mis pakuvad terviklikke rakendusnäiteid, ja API referents, mis dokumenteerib iga lõpp-punkti üksikasjalikult.

Peamised punktid

  • Spetsialiseeri oma agente – üks agent = üks vastutus
  • Jälgi – logi iga üleandmine ja tööriista käivitamine
  • Testi – valideeri ruutimist ja iga agendi vastuseid
  • Turva – kaitseraudteed, minimaalsed õigused, sisendmoderatsioon
  • Optimeeri kulusid – õige suurusega mudel, max_tokens, store=False kui võimalik
  • Mistral Agents on beetaversioonis – püsi API muudatustega kursis

Testi oma teadmisi

Agendid, sisseehitatud tööriistad, üleandmised: kas Agents API-l on veel pimedaid laike?

1. Millal on agent vajalik ja millal piisab vestlusrobotist?

Vastus: Agent on õigustatud, kui vajad tööriistu, püsivust ja mitmeastmelisi otsuseid; lihtsate küsimuste ja vastuste jaoks piisab tavalisest vestlusest – arhitektuur järgib vajadust.

2. Mida haldavad püsivad vestlused Agents API-s?

Vastus: Ajalugu Mistrali poolel: sa jätkad vestlust selle ID järgi, saatmata kogu konteksti uuesti – olek muutub teenuseks.

3. Loetle saadaolevad sisseehitatud tööriistad ja nende kasutusvaldkond.

Vastus: web_search (reaalaja info), code_interpreter (Pythoni käivitamine), image_generation (piltide loomine), document_library (küsimused ja vastused sinu failide põhjal) – valmis võimekused, mida ei pea ise rakendama.

4. Kuidas töötab mitme agendiga süsteem üleandmistega?

Vastus: Ruuter kvalifitseerib päringu ja edastab selle pädevale spetsialist-agendile; iga agent jääb lihtsaks, orkestreerimine tagab katvuse ja üleandmised ahelduvad sügavuti.

5. Kuidas turvad agente tootmiskeskkonnas?

Vastus: Sisendi/väljundi kaitseraudteede, kitsalt määratletud tööriistade, tegevuste jälgitavuse ja inimkinnitusega kõrge riskiga otsustel – autonoomia teenitakse kontrolli kaudu.

Spetsialiseerunud agendid, sisseehitatud tööriistad, ruutimine, kaitseraudteed: kogu arhitektuur mahub nelja sõnasse – ja see kursus pani sind üks ühele need üles ehitama.