Architektura API agentů Mistral
Na této stránce
Aktualizováno 3. listopadu 2026. Předchozí úplný příklad agenta předával
guardrails={"enabled": True}, což je formát, který neexistuje: oficiálním parametrem je seznam konfiguracímoderation_llm_v2. Vstuptool.executionzpřístupňuje název nástroje ventry.name, nikoli ventry.tool_name, což dříve vyvolávalo chybuAttributeError. Zdroje: Agents & Conversations · Moderation & Guardrailing · SDKmistralai3.7.0.
Tři základní objekty
API agentů Mistral stojí na třech vzájemně propojených objektech: Agent, Conversation (konverzace) a Entry (záznam). Většina chyb, na které narazíš na začátku projektu – jako je vytváření nového agenta pro každý požadavek, opakované použití vypršelého conversation_id nebo parsování odpovědí, které spadne na neočekávaný typ záznamu – pramení z nepochopení rozdílu mezi těmito třemi úrovněmi. Pochopení jejich rolí a vztahů je nutným předpokladem pro napsání byť jediného řádku kódu.
Objekt Agent
Agent je sada konfigurací, která definuje chování modelu. Neobsahuje žádná data z konverzace: je to šablona, kterou vytvoříš jednou a na kterou se může odkazovat tisíce konverzací.
Vytvoření vyžaduje minimálně model, název a popis.
agent = client.beta.agents.create(
model="mistral-large-latest", # LLM model k použití
name="My Agent", # Čitelný identifikátor pro člověka
description="Agent for financial analysis" # Popis orientovaný na úkol
)
Parametr model určuje model, který bude agenta pohánět; vybíráš z dostupných modelů pro dokončování chatu, jako jsou mistral-medium-latest nebo mistral-large-latest. Parametr name je čitelný identifikátor, který používáš k vyhledání a odkazování na agenta: pokud máš v projektu dvacet agentů, právě toto ti ušetří prohrabávání se logy, abys zjistil, který z nich odpovídá zákazníkům. Parametr description je orientován na úkol a sloučí k více než jen interní dokumentaci – pomáhá modelu pochopit roli, která se od něj očekává, což vysvětluje formulaci „agent pro finanční analýzu“ místo vágního „agent číslo 3“.
Zbytek se konfiguruje volitelně a právě zde získává agent svou skutečnou 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– Systémový prompt agenta (definuje jeho osobnost, pravidla a styl)tools– Seznam dostupných nástrojů:web_search,web_search_premium,code_interpreter,image_generation,document_librarynebo vlastní funkcecompletion_args– Parametry vzorkování (teplota, top_p, max_tokens atd.)guardrails– Seznam konfigurací moderace (moderation_llm_v2) aplikovaných na příchozí zprávu každé konverzace agenta; zde je jailbreaking blokován nad prahem 0,2 a kategoriefinancialje deaktivována (prahová hodnota1), protože je agent určen k diskusi o financích. Podrobnosti najdeš v kurzu AI Moderation and Security with Mistral.
Ve výše uvedeném příkladu dědí finanční agent z instrukcí požadavek na uvádění zdrojů, ze svých nástrojů schopnost ověřit údaj a nízkou teplotu, která omezuje kreativitu tam, kde je očekávána přesnost.
Objekt Conversation
Conversation je historie interakcí mezi uživatelem a agentem – nebo mezi uživatelem a samotným modelem. Obsahuje zprávy, výsledky provádění nástrojů a události předání (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Získej ID konverzace pro pokračování později
conversation_id = response.conversation_id
Chování tohoto objektu skrývá několik překvapení. Konverzace je perzistentní: historie je uložena na straně Mistralu, pokud nepředáš store=False. Je nezávislá na agentovi, což znamená, že konverzace může klidně existovat bez agenta, v režimu přímého modelu. Nakonec je neměnná: každé přidání vrací nové conversation_id, přičemž to staré zůstává přístupné. Tento poslední bod je nejvíce překvapivý: pokud uložíš počáteční ID do své databáze a znovu jej použiješ ve třetím kole, vrátíš se ke kontextu první výměny.
Objekt Entry
Entry je jednotlivá akce v rámci konverzace: atomární jednotka historie. Když obdržíš odpověď, pole outputs obsahuje seznam záznamů, jejichž typ závisí na tom, co agent provedl. Záznam typu message.output nese textovou odpověď od agenta, tedy text, který zobrazí tvé rozhraní. Záznam typu tool.execution nese výsledek provedení nástroje, jako je kód nebo webové vyhledávání: spuštěný skript a jeho výstup, nebo stránky vrácené vyhledávačem. Záznam typu agent.handoff signalizuje událost předání jinému agentovi, a proto se objevuje pouze ve scénářích s více agenty.
Jediná odpověď běžně kombinuje tyto typy. Pokud požádáš agenta s nástroji o výpočet, obdržíš provedení a následně komentář, který jej doprovází: tvůj kód proto musí iterovat tímto seznamem, místo aby četl jediné pole.
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}")
Vztahy mezi objekty
Následující diagram shrnuje provázání tří úrovní: opakovaně použitelná konfigurace, vlákno historie a jednotkové akce.
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 konverzace
Spuštění konverzace přijímá nastavení, která ovlivňují jak tvůj soulad s předpisy, tak architekturu, a je lepší se pro ně rozhodnout vědomě, než abys jim podlehl. Nejprve ukládání: store=False zabrání jakémukoli ukládání na straně Mistralu, což využiješ ke zpracování dat, která ti interní politika zakazuje opouštět servery třetích stran.
# Zakázat cloudové ukládání
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
Druhé nastavení definuje, kdo provádí předání (handoffs). V režimu server, což je výchozí hodnota, Mistral řetězí předání agentů bez tvého zásahu; v režimu client obdržíš události handoff a zachováš si kontrolu pro jejich logování, filtrování nebo odmítnutí.
# Režim server (výchozí) — Mistral automaticky zpracovává handoffy
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Režim client — Obdržíš události handoff a rozhodneš se, co dělat
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Klíčové poznatky
- Agent = opakovaně použitelná konfigurace (model, instrukce, nástroje, guardrails)
- Conversation = perzistentní historie uložená na serveru, nezávislá na agentovi
- Entry = jednotková akce (zpráva, provedení nástroje, handoff)
- Konverzace mohou existovat bez agenta (režim přímého modelu)
- Každé přidání do konverzace vytvoří nové
conversation_id - Režim
store=Falsezabraňuje ukládání na straně Mistralu