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

Arhitektura API-ja za agente Mistral

Lekcija 3 od 18 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Tri temeljna objekta
  2. Objekt Agent
  3. Objekt Conversation
  4. Objekt Entry
  5. Odnosi između objekata
  6. Opcije razgovora
  7. Ključne točke

Ažurirano 3. studenoga 2026. Prethodni potpuni primjer agenta prosljeđivao je guardrails={"enabled": True}, format koji ne postoji: službeni parametar je popis konfiguracija moderation_llm_v2. Ulaz tool.execution izlaže naziv alata u entry.name, a ne u entry.tool_name, što je prethodno izazivalo AttributeError. Izvori: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

Tri temeljna objekta

API Mistral Agents oslanja se na tri međusobno povezana objekta: Agent, Conversation (razgovor) i Entry (unos). Većina pogrešaka u dizajnu na koje naiđeš na početku projekta—poput ponovnog stvaranja agenta za svaki zahtjev, ponovne upotrebe isteklog conversation_id-a ili parsiranja odgovora koje puca na neočekivani unos—proizlazi iz zabune između ove tri razine. Razumijevanje njihovih uloga i odnosa preduvjet je za pisanje ijedne linije koda.

Objekt Agent

Agent je skup konfiguracija koji definira ponašanje modela. Ne sadrži podatke o razgovoru: to je predložak koji stvoriš jednom, a na koji se može odnositi tisuće razgovora.

Za stvaranje su nužni barem model, naziv i opis.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # LLM model za korištenje
    name="My Agent",                     # Identifikator čitljiv čovjeku
    description="Agent for financial analysis"  # Opis usmjeren na zadatak
)

Parametar model označava model koji će pokretati agenta, odabran iz dostupnih modela za dovršavanje razgovora poput mistral-medium-latest ili mistral-large-latest. name je identifikator čitljiv čovjeku koji koristiš za pronalaženje i referenciranje agenta: u projektu s dvadeset njih, ovo te spašava od kopanja po logovima kako bi shvatio koji od njih odgovara korisnicima. description, s druge strane, usmjeren je na zadatak i služi više od samo interne dokumentacije—pomaže modelu razumjeti ulogu koja se od njega očekuje, što objašnjava formulaciju „agent za financijsku analizu“ umjesto nejasnog „agent broj 3“.

Ostalo se konfigurira opcionalno, a upravo tu agent dobiva svoju stvarnu osobnost.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Complete Agent",
    description="Agent with all parameters",
    instructions="You are a finance expert. Always respond with sources.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ],
    completion_args={"temperature": 0.3, "top_p": 0.95},
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
                "action": "block",
            },
        }
    ],
)
  • instructions — Sistemski upit agenta (definira njegovu osobnost, pravila i stil)
  • tools — Popis dostupnih alata: web_search, web_search_premium, code_interpreter, image_generation, document_library ili prilagođene funkcije
  • completion_args — Parametri uzorkovanja (temperature, top_p, max_tokens itd.)
  • guardrails — Popis konfiguracija moderacije (moderation_llm_v2) primijenjenih na dolaznu poruku svakog razgovora agenta; ovdje je probijanje zaštite (jailbreaking) blokirano iznad 0.2, a kategorija financial je onemogućena (prag 1), budući da je agent izgrađen za raspravu o financijama. Detalji su u tečaju AI Moderation and Security with Mistral.

U gornjem primjeru, financijski agent nasljeđuje zahtjev za navođenjem izvora iz svojih uputa, mogućnost provjere brojke iz svojih alata i nisku temperaturu koja ograničava kreativnost tamo gdje se očekuje rigoroznost.

Objekt Conversation

Conversation je povijest interakcija između korisnika i agenta—ili između korisnika i samog modela. Sadrži poruke, rezultate izvršavanja alata i događaje predaje (handoff).

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Analyze trends in the European AI market."
)

# Dohvati ID razgovora za kasnije nastavak
conversation_id = response.conversation_id

Ponašanje ovog objekta krije nekoliko iznenađenja. Razgovor je postojan: povijest se pohranjuje na strani Mistrala, osim ako ne proslijediš store=False. Neovisan je o agentu, što znači da razgovor može savršeno dobro postojati bez agenta, u izravnom načinu rada s modelom. Konačno, nepromjenjiv je: svako dodavanje vraća novi conversation_id, pri čemu stari ostaje dostupan. Ova posljednja točka je najiznenađujuća: ako pohraniš početni ID u svoju bazu podataka i ponovno ga upotrijebiš u trećem krugu, vratit ćeš se na kontekst prve razmjene.

Objekt Entry

Entry je pojedinačna radnja unutar razgovora: atomska jedinica povijesti. Kada primiš odgovor, polje outputs sadrži popis unosa čija vrsta ovisi o tome što je agent učinio. Unos message.output nosi tekstualni odgovor agenta, odnosno tekst koji će tvoje sučelje prikazati. Unos tool.execution nosi rezultat izvršavanja alata, poput koda ili web pretrage: pokrenutu skriptu i njezin izlaz ili stranice koje je vratio pogon. Unos agent.handoff signalizira događaj prijenosa drugom agentu, pa se stoga pojavljuje samo u scenarijima s više agenata.

Jedan odgovor često miješa ove vrste. Zatražiš li od agenta s alatima izračun, primit ćeš izvršenje, a zatim komentar koji ga prati: tvoj kod stoga mora iterirati kroz ovaj popis umjesto čitanja jednog polja.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Calculate the square root of 144"
)

for entry in response.outputs:
    print(f"Type: {entry.type}")
    if entry.type == "message.output":
        print(f"Message: {entry.content}")
    elif entry.type == "tool.execution":
        print(f"Tool: {entry.name}")

Odnosi između objekata

Sljedeći dijagram sažima povezivanje triju razina: konfiguracije koja se može ponovno koristiti, niti povijesti i jediničnih radnji.

Agent (configuration)
  ├── model, instructions, tools, guardrails
  └── Can be referenced by N conversations

Conversation (history)
  ├── Linked to 0 or 1 Agent (optional)
  ├── Contains N ordered entries
  └── Each append creates a new conversation_id

Entry (unit action)
  ├── message.output (text response)
  ├── tool.execution (tool result)
  └── agent.handoff (agent transfer)

Opcije razgovora

Pokretanje razgovora prihvaća postavke koje utječu na tvoju usklađenost jednako koliko i na tvoju arhitekturu, pa je bolje da ih ti odlučiš nego da trpiš posljedice. Prvo pohranjivanje: store=False sprječava bilo kakvo spremanje na strani Mistrala, što ćeš koristiti za obradu podataka koje tvoja interna politika zabranjuje napuštanje poslužitelja treće strane.

# Onemogući pohranu u oblaku
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

Druga postavka definira tko izvršava predaje (handoffs). U načinu server, zadanoj vrijednosti, Mistral lančano prenosi agente bez tvoje intervencije; u načinu client, primaš događaje predaje i zadržavaš kontrolu kako bi ih bilježio, filtrirao ili odbio.

# Način servera (zadano) — Mistral automatski rukuje predajama
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Način klijenta — Primaš događaje predaje i odlučuješ što učiniti
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Ključne točke

  • Agent = konfiguracija koja se može ponovno koristiti (model, upute, alati, guardrails)
  • Conversation = postojana povijest pohranjena na poslužitelju, neovisna o agentu
  • Entry = jedinična radnja (poruka, izvršavanje alata, predaja)
  • Razgovori mogu postojati bez agenta (izravni način rada s modelom)
  • Svako dodavanje razgovoru stvara novi conversation_id
  • Način store=False sprječava pohranu na strani Mistrala