Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Arhitektura API-ja za agente Mistral

Lekcija 3 od 18 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Tri temeljni objekti
  2. Objekt Agent
  3. Objekt Conversation
  4. Objekt Entry
  5. Odnosi med objekti
  6. Možnosti pogovora
  7. Ključne ugotovitve

Posodobljeno 3. novembra 2026. Prejšnji popoln primer agenta je uporabljal guardrails={"enabled": True}, kar je neveljaven format: uradni parameter je seznam konfiguracij moderation_llm_v2. Vnos tool.execution ime orodja izpostavi v entry.name, ne v entry.tool_name, kar je prej povzročalo napako AttributeError. Viri: Agents & Conversations · Moderation & Guardrailing · SDK mistralai 3.7.0.

Tri temeljni objekti

API za agente Mistral temelji na treh medsebojno povezanih objektih: Agent, Conversation (pogovor) in Entry (vnos). Večina napak pri načrtovanju, na katere naletiš zgodaj v projektu – kot so ustvarjanje novega agenta za vsako zahtevo, ponovna uporaba poteklega conversation_id ali razčlenjevanje odgovorov, ki se sesuje ob nepričakovanem vnosu – izvira iz zamenjave teh treh ravni. Razumevanje njihovih vlog in odnosov je predpogoj za zapisovanje katere koli vrstice kode.

Objekt Agent

Agent je nabor konfiguracij, ki določa obnašanje modela. Ne vsebuje podatkov o pogovoru: gre za predlogo za večkratno uporabo, ki jo ustvariš enkrat, nanjo pa se lahko sklicuje na tisoče pogovorov.

Za ustvarjanje potrebuješ vsaj model, ime in opis.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # Model LLM za uporabo
    name="My Agent",                     # Človeku berljiv identifikator
    description="Agent for financial analysis"  # Opis, usmerjen v nalogo
)

Parameter model določa model, ki bo poganjal agenta; izbereš ga med razpoložljivimi modeli za dokončanje klepeta, kot sta mistral-medium-latest ali mistral-large-latest. name je človeku berljiv identifikator, ki ga uporabljaš za iskanje in sklicevanje na agenta: v projektu z dvajsetimi agenti te reši brskanja po dnevnikih, da bi ugotovil, kateri odgovarja strankam. description je medtem usmerjen v nalogo in služi več kot le interni dokumentaciji – pomaga modelu razumeti pričakovano vlogo, kar pojasnjuje frazo „agent za finančno analizo” namesto nejasnega „agent številka 3”.

Ostalo nastaviš opcijsko in prav tu dobi agent svojo pravo osebnost.

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 poziv agenta (določa njegovo osebnost, pravila in slog)
  • tools – Seznam razpoložljivih orodij: web_search, web_search_premium, code_interpreter, image_generation, document_library ali funkcije po meri
  • completion_args – Parametri vzorčenja (temperature, top_p, max_tokens itd.)
  • guardrails – Seznam konfiguracij za moderiranje (moderation_llm_v2), ki se uporabijo za vhodno sporočilo vsakega pogovora tega agenta; tukaj je prebijanje zaščit (jailbreaking) blokirano nad pragom 0,2, kategorija financial pa onemogočena (prag 1), saj je agent zasnovan za razprave o financah. Podrobnosti so v tečaju AI Moderation and Security with Mistral.

V zgornjem primeru finančni agent podeduje zahtevo po navajanju virov iz svojih navodil, možnost preverjanja številk prek svojih orodij in nizko temperaturo, ki omejuje ustvarjalnost tam, kjer je potrebna strogost.

Objekt Conversation

Conversation je zgodovina interakcij med uporabnikom in agentom – ali med uporabnikom in samim modelom. Vsebuje sporočila, rezultate izvajanja orodij in dogodke predaje (handoff).

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

# Pridobi ID pogovora za nadaljevanje kasneje
conversation_id = response.conversation_id

Obnašanje tega objekta skriva nekaj presenečenj. Pogovor je trajen: zgodovina je shranjena na strani Mistrala, razen če posreduješ store=False. Je neodvisen od agenta, kar pomeni, da lahko pogovor obstaja tudi brez agenta, v neposrednem načinu z modelom. Nazadnje, je nespremenljiv: vsak dodatek vrne nov conversation_id, stari pa ostane dostopen. Zadnja točka je najbolj presenetljiva: če začetni ID shraniš v svojo zbirko podatkov in ga ponovno uporabiš pri tretjem obratu, se boš vrnil v kontekst prve izmenjave.

Objekt Entry

Entry je posamezno dejanje znotraj pogovora: atomska enota zgodovine. Ko prejmeš odgovor, polje outputs vsebuje seznam vnosov, katerih vrsta je odvisna od tega, kaj je agent storil. Vnos message.output nosi besedni odgovor agenta, torej besedilo, ki ga bo prikazal tvoj vmesnik. Vnos tool.execution nosi rezultat izvajanja orodja, kot sta koda ali spletno iskanje: zagnani skript in njegov izpis ali strani, ki jih je vrnil iskalnik. Vnos agent.handoff signalizira dogodek predaje drugemu agentu in se zato pojavi le v scenarijih z več agenti.

En sam odgovor pogosto združuje te vrste. Če agentu z orodji zastaviš vprašanje za izračun, boš prejel izvajanje in nato komentar, ki ga spremlja: tvoja koda mora zato iterirati skozi ta seznam, namesto da bi brala eno samo polje.

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 med objekti

Naslednji diagram povzema povezavo med tremi ravnmi: konfiguracijo za večkratno uporabo, nit zgodovine in atomska dejanja.

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)

Možnosti pogovora

Začetek pogovora sprejema nastavitve, ki vplivajo tako na tvojo skladnost kot na arhitekturo, zato je bolje, da se o njih odločiš sam, kot da trpiš posledice. Najprej shranjevanje: store=False prepreči kakršno koli shranjevanje na strani Mistrala, kar boš uporabil za obdelavo podatkov, ki jih tvoja interna politika prepoveduje pošiljati na strežnik tretje strani.

# Onemogoči shranjevanje v oblaku
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

Druga nastavitev določa, kdo izvaja predaje (handoffs). V načinu server, ki je privzeta vrednost, Mistral samodejno veriži predaje agentov brez tvojega posredovanja; v načinu client prejmeš dogodke predaje in obdržiš nadzor, da jih zabeležiš, filtriraš ali zavrneš.

# Način server (privzeto) — Mistral samodejno obravnava predaje
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Način client — Prejmeš dogodke predaje in se odločiš, kaj storiti
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Ključne ugotovitve

  • Agent = konfiguracija za večkratno uporabo (model, navodila, orodja, guardrails)
  • Conversation = trajna zgodovina, shranjena na strežniku, neodvisna od agenta
  • Entry = atomsko dejanje (sporočilo, izvajanje orodja, predaja)
  • Pogovori lahko obstajajo brez agenta (neposredni način z modelom)
  • Vsak dodatek k pogovoru ustvari nov conversation_id
  • Način store=False prepreči shranjevanje na strani Mistrala