Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

A Mistral Agents API architektúrája

3. lecke 18 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. A három alapvető objektum
  2. Az Agent objektum
  3. A Conversation objektum
  4. Az Entry objektum
  5. Kapcsolatok az objektumok között
  6. Beszélgetési beállítások
  7. Főbb megállapítások

Frissítve: 2026. november 3. A korábbi teljes ügynök példa a guardrails={"enabled": True} paramétert használta, ami nem létező formátum: a hivatalos paraméter a moderation_llm_v2 konfigurációk listája. A tool.execution bemenet az eszköz nevét az entry.name mezőben adja vissza, nem az entry.tool_name-ben, ami korábban AttributeError hibát okozott. Források: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

A három alapvető objektum

A Mistral Agents API három egymással kölcsönhatásban álló objektumra épül: Agent (ügynök), Conversation (beszélgetés) és Entry (bejegyzés). A projektek elején elkövetett tervezési hibák többsége – például minden kéréshez új ügynök létrehozása, egy lejárt conversation_id újrafelhasználása, vagy egy váratlan bejegyzés miatt összeomló válaszfeldolgozás – e három szint közötti zavarból ered. Szerepük és kapcsolataik megértése előfeltétele annak, hogy akár csak egy sor kódot is írj.

Az Agent objektum

Az Agent egy konfigurációs készlet, amely meghatározza a modell viselkedését. Nem tartalmaz beszélgetési adatokat: ez egy újrahasználható sablon, amelyet egyszer hozol létre, és amelyre beszélgetések ezrei hivatkozhatnak.

Létrehozásához legalább egy modell, egy név és egy leírás szükséges.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # Használandó LLM modell
    name="My Agent",                     # Ember által olvasható azonosító
    description="Agent for financial analysis"  # Feladatorientált leírás
)

A model paraméter azt a modellt jelöli ki, amely az ügynököt működteti; ezt a rendelkezésre álló chat-kiegészítő modellek közül választod ki, mint például a mistral-medium-latest vagy a mistral-large-latest. A name egy ember által olvasható azonosító, amelyet az ügynök megtalálására és hivatkozására használsz: ha egy projektben húsz ilyen van, ez ment meg attól, hogy naplófájlokat böngéssz, hogy kiderítsd, melyik válaszol az ügyfeleknek. A description ezzel szemben feladatorientált, és többet szolgál, mint a belső dokumentáció: segít a modellnek megérteni a tőle elvárt szerepet, ami megmagyarázza a „pénzügyi elemzésre specializálódott ügynök“ megfogalmazást egy homályos „3-as számú ügynök“ helyett.

A többi beállítás opcionális, és itt nyeri el az ügynök a valódi személyiségét.

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 — Az ügynök rendszerpromptja (meghatározza a személyiségét, szabályait és stílusát)
  • tools — Elérhető eszközök listája: web_search, web_search_premium, code_interpreter, image_generation, document_library vagy egyedi függvények
  • completion_args — Mintavételezési paraméterek (hőmérséklet, top_p, max_tokens stb.)
  • guardrails — Moderációs konfigurációk (moderation_llm_v2) listája, amelyeket az ügynök minden beszélgetésének bejövő üzeneteire alkalmaznak; itt a jailbreakinget 0,2 felett blokkolja a rendszer, a financial kategória pedig letiltásra kerül (küszöbérték 1), mivel az ügynököt pénzügyi témákra építették. A részleteket az AI Moderation and Security with Mistral című kurzus tartalmazza.

A fenti példában a pénzügyi ügynök örökli a forrásmegjelölési kötelezettséget az utasításaiból, képes ellenőrizni egy számot az eszközei segítségével, és egy alacsony hőmérséklettel rendelkezik, amely korlátozza a kreativitást ott, ahol szigorúságra van szükség.

A Conversation objektum

A Conversation a felhasználó és egy ügynök – vagy csak egy felhasználó és egy modell – közötti interakciók előzménye. Üzeneteket, eszközvégrehajtási eredményeket és átadási eseményeket (handoff) tartalmaz.

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

# A conversation_id lekérése a későbbi folytatáshoz
conversation_id = response.conversation_id

Ennek az objektumnak a viselkedése tartogat meglepetéseket. A beszélgetés tartós: az előzményeket a Mistral szerverein tárolja, hacsak nem adod meg a store=False paramétert. Független az ügynöktől, ami azt jelenti, hogy egy beszélgetés tökéletesen létezhet ügynök nélkül is, közvetlen modell módban. Végül pedig változatlan (immutable): minden hozzáadás egy új conversation_id-t hoz létre, miközben a régi továbbra is elérhető marad. Ez utóbbi pont a legmeglepőbb: ha az eredeti ID-t elmented az adatbázisodba, és a harmadik körben újra felhasználod, akkor visszakerülsz az első váltás kontextusába.

Az Entry objektum

Az Entry a beszélgetésen belüli egyes művelet: az előzmények atomi egysége. Amikor választ kapsz, az outputs mező olyan bejegyzések listáját tartalmazza, amelyek típusa attól függ, mit tett az ügynök. Egy message.output típusú bejegyzés az ügynök szöveges válaszát hordozza, vagyis azt a szöveget, amelyet a felületed megjelenít. Egy tool.execution típusú bejegyzés egy eszköz végrehajtási eredményét tartalmazza, például kódot vagy webes keresést: a futtatott szkriptet és annak kimenetét, vagy a motor által visszaadott oldalakat. Egy agent.handoff típusú bejegyzés egy másik ügynöknek történő átadás eseményét jelzi, így csak többügynökös forgatókönyvekben jelenik meg.

Egyetlen válasz gyakran vegyíti ezeket a típusokat. Ha egy eszközökkel felszerelt ügynöktől kérsz egy számítást, megkapod a végrehajtást, majd az azt kísérő kommentárt: a kódodnak ezért iterálnia kell ezen a listán, ahelyett, hogy egyetlen mezőt olvasna be.

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}")

Kapcsolatok az objektumok között

Az alábbi diagram összefoglalja a három szint összekapcsolódását: egy újrahasználható konfiguráció, egy előzményszál és az egyes műveletek.

Agent (konfiguráció)
  ├── modell, utasítások, eszközök, guardrails
  └── N számú beszélgetés hivatkozhat rá

Conversation (előzmény)
  ├── 0 vagy 1 Agenthez kapcsolódik (opcionális)
  ├── N számú rendezett bejegyzést tartalmaz
  └── Minden hozzáadás új conversation_id-t hoz létre

Entry (egyes művelet)
  ├── message.output (szöveges válasz)
  ├── tool.execution (eszköz eredménye)
  └── agent.handoff (ügynök átadás)

Beszélgetési beállítások

Egy beszélgetés indításakor olyan beállításokat adhatsz meg, amelyek ugyanolyan mértékben befolyásolják a megfelelőségedet, mint az architektúrádat, és jobb, ha te döntesz róluk, mintsem hogy elszenveded a következményeket. Először a tárolás: a store=False megakadályozza bármilyen adat mentését a Mistral oldalán; ezt akkor használod, ha olyan adatokat dolgozol fel, amelyeket a belső szabályzatod tilt harmadik fél szerverén tárolni.

# Felhőalapú tárolás letiltása
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

A második beállítás határozza meg, ki hajtja végre az átadásokat (handoff). A server módban, ami az alapértelmezett érték, a Mistral a te beavatkozásod nélkül láncolja össze az ügynök-átadásokat; a client módban viszont te kapod meg az átadási eseményeket, és nálad marad az irányítás a naplózás, szűrés vagy elutasítás érdekében.

# Szerver mód (alapértelmezett) — A Mistral automatikusan kezeli az átadásokat
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Kliens mód — Te kapod meg az átadási eseményeket, és te döntesz a továbblépésről
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Főbb megállapítások

  • Agent = újrahasználható konfiguráció (modell, utasítások, eszközök, guardrails)
  • Conversation = a szerveren tárolt tartós előzmény, független az ügynöktől
  • Entry = egyes művelet (üzenet, eszközvégrehajtás, átadás)
  • A beszélgetések ügynök nélkül is létezhetnek (közvetlen modell mód)
  • A beszélgetéshez való minden hozzáadás egy új conversation_id-t hoz létre
  • A store=False mód megakadályozza a tárolást a Mistral oldalán