Arhitektura API-ja za agente Mistral
Na ovoj stranici
Ažurirano 3. studenoga 2026. Prethodni potpuni primjer agenta prosljeđivao je
guardrails={"enabled": True}, format koji ne postoji: službeni parametar je popis konfiguracijamoderation_llm_v2. Ulaztool.executionizlaže naziv alata uentry.name, a ne uentry.tool_name, što je prethodno izazivaloAttributeError. Izvori: Agents & Conversations · Moderation & Guardrailing ·mistralaiSDK 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_libraryili prilagođene funkcijecompletion_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 kategorijafinancialje onemogućena (prag1), 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=Falsesprječava pohranu na strani Mistrala