Architektúra API agentov Mistral
Na tejto strane
Aktualizované 3. novembra 2026. Predchádzajúci úplný príklad agenta odovzdával
guardrails={"enabled": True}, čo je formát, ktorý neexistuje: oficiálnym parametrom je zoznam konfiguráciímoderation_llm_v2. Vstuptool.executionexpose názov nástroja ventry.name, nie ventry.tool_name, čo predtým vyvolávalo chybuAttributeError. Zdroje: Agents & Conversations · Moderation & Guardrailing · SDKmistralai3.7.0.
Tri základné objekty
API agentov Mistral stojí na troch interagujúcich objektoch: Agent, Conversation (konverzácia) a Entry (záznam). Väčšina chýb v dizajne, na ktoré narazíš na začiatku projektu – vytváranie nového agenta pre každú požiadavku, opätovné použitie expirovaného conversation_id alebo parsovanie odpovede, ktoré spadne na neočakávaný záznam – pramení z pomýlenia si týchto troch úrovní. Pochopenie ich rolí a vzťahov je nevyhnutným predpokladom ešte pred napísaním prvého riadku kódu.
Objekt Agent
Agent je sada konfigurácií, ktorá definuje správanie modelu. Neobsahuje žiadne údaje z konverzácie: je to znovupoužiteľná šablóna, ktorú vytvoríš raz a na ktorú sa môže odkazovať tisíce konverzácií.
Vytvorenie vyžaduje minimálne model, názov a popis.
agent = client.beta.agents.create(
model="mistral-large-latest", # LLM model na použitie
name="My Agent", # Čitateľný identifikátor pre človeka
description="Agent for financial analysis" # Popis orientovaný na úlohu
)
Parameter model určuje model, ktorý bude poháňať agenta, vybraný z dostupných modelov na dokončovanie chatu, ako sú mistral-medium-latest alebo mistral-large-latest. name je čitateľný identifikátor, ktorý používaš na nájdenie a odkazovanie na agenta: v projekte s dvadsiatimi agentmi je to práve toto, čo ťa zachráni pred prehrabávaním sa v logoch, aby si zistil, ktorý z nich odpovedá zákazníkom. description je medzitým orientovaný na úlohu a slúži nielen ako interná dokumentácia – pomáha modelu pochopiť očakávanú rolu, čo vysvetľuje formuláciu „agent pre finančnú analýzu“ namiesto vágneho „agent číslo 3“.
Zvyšok sa konfiguruje voliteľne a práve tu nadobúda agent svoju skutočnú osobnosť.
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– Systémový prompt agenta (definuje jeho osobnosť, pravidlá a štýl)tools– Zoznam dostupných nástrojov:web_search,web_search_premium,code_interpreter,image_generation,document_libraryalebo vlastné funkciecompletion_args– Parametre vzorkovania (teplota, top_p, max_tokens atď.)guardrails– Zoznam konfigurácií moderovania (moderation_llm_v2) aplikovaných na prichádzajúcu správu každej konverzácie agenta; tu je jailbreaking blokovaný nad hodnotou 0,2 a kategóriafinancialje deaktivovaná (prah1), keďže agent je stavaný na diskusie o financiách. Podrobnosti nájdeš v kurze AI Moderácia a bezpečnosť s Mistral.
Vo vyššie uvedenom príklade finančný agent dedí požiadavku na uvádzanie zdrojov zo svojich inštrukcií, schopnosť overiť údaj zo svojich nástrojov a nízku teplotu, ktorá obmedzuje kreativitu tam, kde sa očakáva presnosť.
Objekt Conversation
Conversation je história interakcií medzi používateľom a agentom – alebo medzi používateľom a samotným modelom. Obsahuje správy, výsledky vykonania nástrojov a udalosti odovzdania (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Získaj ID konverzácie na pokračovanie neskôr
conversation_id = response.conversation_id
Správanie tohto objektu prináša niekoľko prekvapení. Konverzácia je perzistentná: história je uložená na strane Mistral, pokiaľ neprejdeš parameter store=False. Je nezávislá od agenta, čo znamená, že konverzácia môže pokojne existovať bez agenta, v režime priameho modelu. Nakoniec je nemeniteľná (immutable): každé pridanie vráti nové conversation_id, pričom staré zostáva dostupné. Tento posledný bod je najprekvapivejší: ak uložíš počiatočné ID do svojej databázy a použiješ ho znovu pri treťom kole, vrátiš sa ku kontextu prvej výmeny.
Objekt Entry
Entry je individuálna akcia v rámci konverzácie: atómová jednotka histórie. Keď dostaneš odpoveď, pole outputs obsahuje zoznam záznamov, ktorých typ závisí od toho, čo agent urobil. Záznam typu message.output nesie textovú odpoveď od agenta, teda text, ktorý zobrazí tvoje rozhranie. Záznam typu tool.execution nesie výsledok vykonania nástroja, ako je kód alebo webové vyhľadávanie: spustený skript a jeho výstup, alebo stránky vrátené vyhľadávačom. Záznam typu agent.handoff signalizuje udalosť presunu na iného agenta, a preto sa objavuje len v scenároch s viacerými agentmi.
Jedna odpoveď bežne kombinuje tieto typy. Ak požiadaš agenta s nástrojmi o výpočet, dostaneš najprv vykonanie a potom komentár, ktorý ho sprevádza: tvoj kód preto musí iterovať cez tento zoznam namiesto čítania jedného poľa.
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}")
Vzťahy medzi objektmi
Nasledujúci diagram sumarizuje prepojenie troch úrovní: znovupoužiteľná konfigurácia, vlákno histórie a jednotkové akcie.
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 konverzácie
Spustenie konverzácie prijíma nastavenia, ktoré ovplyvňujú tvoju zhodu s predpismi rovnako ako tvoju architektúru, a je lepšie ich rozhodnúť zámerne, než trpieť ich dôsledkami. Najprv ukladanie: store=False zabráni akémukoľvek ukladaniu na strane Mistral, čo využiješ na spracovanie údajov, ktoré tvoja interná politika zakazuje opúšťať servery tretej strany.
# Zakáž ukladanie v cloude
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
Druhé nastavenie definuje, kto vykonáva odovzdania (handoffs). V režime server, čo je predvolená hodnota, Mistral reťazí presuny agentov bez tvojho zásahu; v režime client dostávaš udalosti handoff a zachovávaš si kontrolu na ich zaznamenávanie, filtrovanie alebo odmietnutie.
# Režim server (predvolený) — Mistral automaticky vybaví handoffs
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Režim client — Dostávaš udalosti handoff a rozhoduješ, čo robiť
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Kľúčové poznatky
- Agent = znovupoužiteľná konfigurácia (model, inštrukcie, nástroje, guardrails)
- Conversation = perzistentná história uložená na serveri, nezávislá od agenta
- Entry = jednotková akcia (správa, vykonanie nástroja, handoff)
- Konverzácie môžu existovať bez agenta (režim priameho modelu)
- Každé pridanie do konverzácie vytvorí nové
conversation_id - Režim
store=Falsezabraňuje ukladaniu na strane Mistral