Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Najbolje prakse i sljedeći koraci

Lekcija 18 od 18 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Što si naučio
  2. Dizajniranje agenata koji izdrže
  3. Rukovanje greškama
  4. Uvid u događaje
  5. Testiranje usmjeravanja
  6. Referentna arhitektura
  7. Kamo dalje
  8. Ključne točke
  9. Provjeri svoje znanje

Što si naučio

Prošao si kroz cijeli Mistral Agents API. Prije nego što zaronimo u prakse za produkciju, ponovimo ključne točke jer se svaki dio ovog tečaja nadovezuje na prethodni.

Prve tri lekcije postavile su temelje: AI agent je autonomni sustav s petljom percepcija-akcija; API se oslanja na tri objekta—Agent, Conversation i Entry; a ono što agenta razlikuje od chatbota jest trajnost, alati i prosljeđivanje (handoffs). Lekcije od 4 do 7 učinile su te objekte upotrebljivima: stvaranje i konfiguriranje agenata pomoću client.beta.agents.create(), održavanje trajnih razgovora s conversations.start() i conversations.append(), te korištenje izravnog načina bez agenta kada radiš prototipove i trajnost ne donosi vrijednost.

Lekcije od 8 do 11 dodale su nove mogućnosti. web_search ti daje pristup trenutnim informacijama s automatskim citatima; code_interpreter pokreće Python u izoliranom okruženju (sandbox), dajući agentu točne rezultate tamo gdje bi sam model samo aproksimirao; image_generation stvara vizuale iz tekstualnih upita; document_library donosi integrirani RAG za tvoje vlastite dokumente. Lekcije od 12 do 16 zatim su pokazale kako više agenata radi zajedno: prosljeđivanje (handoffs) prenosi kontrolu s jednog agenta na drugog, referentna arhitektura uparuje središnji usmjerivač sa specijalistima, serverski način automatizira tamo gdje te klijentski način drži u petlji, a neograničeno lančanje razlaže se na linearne, zvjezdaste i hibridne obrasce. Konačno, Lekcija 17 sve je zaokružila zaštitnim ogradama (guardrails), principom najmanjih povlastica i moderacijom na ulazu.

Dizajniranje agenata koji izdrže

Jedna rečenica sažima cijeli tečaj: jedan agent, jedna odgovornost, jedan opis koji govori kada ga treba pozvati. Kontrast u nastavku čini tu razliku opipljivom.

# DOBRO — specijalizirani agent s preciznim opisom
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]}]
)

# LOŠE — generički, nejasan 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"}]
)

Drugi agent će istovremeno failati na dva načina. Nijedan usmjerivač neće znati kada mu proslijediti zahtjev jer „pomoćni agent“ ne opisuje nikakvu situaciju. A kada se ipak pozove, njegova tri alata ostavljaju mu slobodu da pretražuje web za nešto što je trebao izračunati ili da ilustrira nešto što je trebao analizirati.

Rukovanje greškama

Mrežni pozivi prije ili kasnije zakažu. Ponovni pokušaj s eksponencijalnim kašnjenjem (exponential backoff) apsorbira prolazne incidente bez pretvaranja trenutnog usporavanja u vidljivi prekid rada.

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

Eksponencijalno kašnjenje—jedna sekunda, pa dvije, pa četiri—razlikuje civilizirani ponovni pokušaj od bombardiranja usluge koja se već muči. Imaj na umu i da konačni pokušaj ponovno podiže iznimku umjesto da vraća None: tvoj pozivatelj mora znati da je operacija nije uspjela.

Uvid u događaje

U produkciji, višestruki tijek rada s agentima koji ne možeš promatrati postaje nemoguć za otklanjanje grešaka. Klijentski način daje ti točno one hookove koji su ti potrebni.

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

Ta dva brojača vrijede više nego što njihova jednostavnost sugerira: odstupanje u prosječnom broju prosljeđivanja signalizira usmjerivač koji oklijeva; skok u pozivima alata ukazuje na skupe upite.

Kontrola troškova svodi se na konkretne odluke. Prati broj tokena po razgovoru jer je to stvarna jedinica naplate. Koristi mistral-medium-latest gdje god mistral-large-latest ne donosi ništa—prva razina podrške školski je primjer za to. Ograniči max_tokens u completion_args kako bi izbjegao beskonačne odgovore na jednostavna pitanja i onemogući pohranu s store=False kada trajnost nije potrebna.

Testiranje usmjeravanja

Testiraj sustav s više agenata kao bilo koju telefonsku centralu: nahrani ga slučajevima za koje znaš očekivano odredište i provjeri gdje završe.

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}"

Gradi ovaj skup testova tijekom vremena: svaki pogrešno usmjeren zahtjev koji uhvatiš u produkciji postaje još jedan redak u test_cases, i znat ćeš da prepisivanje opisa popravlja ciljni slučaj bez rušenja drugog.

Referentna arhitektura

Za produkcijski projekt, evo preporučene arhitekture:

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

Ona objedinjuje sve iz ovog tečaja: moderator filtrira prije bilo kakvog izvršenja, usmjerivač usmjerava bez da ikada sam odgovara, svaki specijalist nosi jedan alat i jednu odgovornost, a promatranje obavija cijeli sustav.

Kamo dalje

Četiri smjera proširuju ono što sada možeš učiniti. Function calling ti omogućuje izgradnju vlastitih prilagođenih alata izvan ugrađenih: pozovi poslovni API, upitaj bazu podataka, pokreni internu uslugu. MCP Servers integriraju Model Context Protocol, koji standardizira način na koji se alati izlažu. Structured outputs prisiljavaju odgovore u JSON shemu, što mijenja sve kada izlaz agenta napaja drugi sustav, a ne ljudskog čitatelja. Konačno, streaming vraća odgovore u stvarnom vremenu umjesto u jednom bloku—odlučujuće kod dugih lanaca gdje tiho čekanje postaje neugodno.

Tri resursa prate ovaj sljedeći korak: službena dokumentacija na docs.mistral.ai/agents, Mistral cookbooks koji pružaju kompletne primjere implementacije i API Reference koji detaljno dokumentira svaku krajnju točku.

Ključne točke

  • Specijaliziraj svoje agente—jedan agent = jedna odgovornost
  • Nadziraj—bilježi svako prosljeđivanje i izvršenje alata
  • Testiraj—validiraj usmjeravanje i odgovore svakog agenta
  • Osiguraj—zaštitne ograde, najmanje povlastice, moderacija na ulazu
  • Optimiziraj troškove—model prilagođene veličine, max_tokens, store=False kada je moguće
  • Mistral Agents su u beta fazi—prati promjene API-ja

Provjeri svoje znanje

Agenti, ugrađeni alati, prosljeđivanja: ima li Agents API još kakvih slijepih točaka?

1. Kada je agent nužan—a kada je chatbot dovoljan?

Odgovor: Agent je opravdan kada su ti potrebni alati, trajnost i višekoračne odluke; za jednostavna pitanja i odgovore, standardni razgovor je dovoljan—arhitektura slijedi potrebu.

2. Što upravljaju trajni razgovori u Agents API-ju?

Odgovor: Povijest na strani Mistrala: nastavljaš razgovor putem njegovog ID-a bez ponovnog slanja cijelog konteksta—stanje postaje usluga.

3. Nabroji dostupne ugrađene alate i njihovu upotrebu.

Odgovor: web_search (informacije u stvarnom vremenu), code_interpreter (pokretanje Pythona), image_generation (stvaranje slika), document_library (pitanja i odgovori na tvoje datoteke)—spremne mogućnosti, bez potrebe za implementacijom.

4. Kako radi sustav s više agenata s prosljeđivanjima?

Odgovor: Usmjerivač kvalificira zahtjev i prosljeđuje ga nadležnom specijaliziranom agentu; svaki agent ostaje jednostavan, orkestracija osigurava pokrivenost—a prosljeđivanja se lančano povezuju u dubinu.

5. Kako osiguravaš agente u produkciji?

Odgovor: Sa zaštitnim ogradama na ulazima/izlazima, usko definiranim alatima, sljedivošću radnji i ljudskom validacijom kod odluka visokog rizika—autonomija se zaslužuje kroz kontrolu.

Specijalizirani agenti, ugrađeni alati, usmjeravanje, zaštitne ograde: cijela arhitektura stane u četiri riječi—a ovaj tečaj naveo te je da izgradiš svaku od njih.