Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Architektura API agentů Mistral

Lekce 3 z 18 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Tři základní objekty
  2. Objekt Agent
  3. Objekt Conversation
  4. Objekt Entry
  5. Vztahy mezi objekty
  6. Možnosti konverzace
  7. Klíčové poznatky

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. Vstup tool.execution zpřístupňuje název nástroje v entry.name, nikoli v entry.tool_name, což dříve vyvolávalo chybu AttributeError. Zdroje: Agents & Conversations · Moderation & Guardrailing · SDK mistralai 3.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_library nebo vlastní funkce
  • completion_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 kategorie financial je deaktivována (prahová hodnota 1), 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=False zabraňuje ukládání na straně Mistralu