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

Legjobb gyakorlatok és következő lépések

18. lecke 18 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Amit átvettél
  2. Megbízható ügynökök tervezése
  3. Hibakezelés
  4. Láthatóság biztosítása
  5. Útválasztás tesztelése
  6. Referenciarchitektúra
  7. Merre tovább?
  8. Főbb megállapítások
  9. Teszteld a tudásod!

Amit átvettél

Végigmentél a teljes Mistral Agents API-n. Mielőtt belevágnánk az éles környezetre vonatkozó gyakorlatokba, foglaljuk össze az eddigieket, hiszen a tanfolyam minden része az előzőre épül.

Az első három lecke lefektette az alapokat: az AI-ügynök egy autonóm rendszer érzékelés-cselekvés ciklussal; az API három objektumra épül – Ügynök (Agent), Beszélgetés (Conversation) és Bejegyzés (Entry); és ami megkülönbözteti az ügynököt a chatbottól, az a perzisztencia, az eszközök és az átadások (handoffs). A 4-től 7-ig terjedő leckék használhatóvá tették ezeket az objektumokat: ügynökök létrehozása és konfigurálása a client.beta.agents.create() segítségével, perzisztens beszélgetések kezelése a conversations.start() és conversations.append() módszerekkel, valamint a közvetlen mód használata ügynök nélkül prototípuskészítéskor, amikor a perzisztencia nem ad hozzá értéket.

A 8-tól 11-ig terjedő leckék új képességeket adtak hozzá. A web_search hozzáférést biztosít a friss információkhoz automatikus hivatkozásokkal; a code_interpreter Pythont futtat egy homokozóban, így az ügynök pontos eredményeket kap ott, ahol a modell önmagában csak becslést adna; az image_generation vizuális tartalmakat állít elő szöveges leírások alapján; a document_library integrált RAG-ot (Retrieval-Augmented Generation) biztosít a saját dokumentumaidhoz. A 12-től 16-ig terjedő leckék ezután bemutatták, hogyan dolgozik együtt több ügynök: az átadások (handoffs) adják át a vezérlést egyik ügynökről a másikra, a referenciarchitektúra egy központi útválasztót párosít szakértőkkel, a szerver mód automatizál, míg a kliens mód bent tart a folyamatban, a korlátlan láncolás pedig lineáris, csillag és hibrid mintázatokra bontható. Végül a 17. lecke mindezt lezárta a korlátokkal (guardrails), a legkisebb jogosultság elvével és a bemeneti oldali moderációval.

Megbízható ügynökök tervezése

Egy mondat foglalja össze az egész tanfolyamot: egy ügynök, egy felelősség, egy leírás, amely megmondja, mikor kell hívni. Az alábbi kontraszt kézzelfoghatóvá teszi a különbséget.

# JÓ — specializált ügynök pontos leírással
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="invoice-processor",
    description="Processes invoices: extracts amounts, dates, vendors.",
    instructions="Extract invoice information into structured JSON.",
    tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)

# ROSSZ — általános, homályos ügynök
agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="helper",
    description="A helpful agent.",
    tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)

A második ügynök kétféleképpen is kudarcot vall egyszerre. Egy útválasztó sem fogja tudni, mikor kell hozzá irányítani egy kérést, mert a „segítőkész ügynök“ nem ír le egyetlen helyzetet sem. És amikor mégis meghívják, a három eszköze szabadságot ad neki, hogy a webet kutassa valami után, amit ki kellett volna számolnia, vagy illusztráljon valamit, amit elemeznie kellett volna.

Hibakezelés

Előbb-utóbb a hálózati hívások meghiúsulnak. Egy exponenciális visszalépéssel (exponential backoff) végrehajtott újrapróbálkozás elnyeli az átmeneti incidenseket anélkül, hogy a pillanatnyi lassulás látható kieséssé válna.

import time

def safe_conversation(agent_id, query, max_retries=3):
    """Beszélgetés hibakezeléssel és újrapróbálkozással."""
    for attempt in range(max_retries):
        try:
            response = client.beta.conversations.start(
                agent_id=agent_id,
                inputs=query
            )
            return response
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponenciális visszalépés
    return None

Az exponenciális visszalépés – egy másodperc, majd kettő, majd négy – megkülönbözteti a civilizált újrapróbálkozást attól, hogy egy már amúgy is küszködő szolgáltatást bombázz kérésekkel. Figyeld meg azt is, hogy az utolsó próbálkozás újra dobja a kivételt ahelyett, hogy None-t adna vissza: a hívód félnek tudnia kell, hogy a művelet meghiúsult.

Láthatóság biztosítása

Éles környezetben egy többrészes ügynöki munkafolyamat, amelyet nem lehet megfigyelni, lehetetlenné válik hibakeresés szempontjából. A kliens mód pontosan azokat a hookokat biztosítja, amelyekre szükséged van.

import logging
import time

logger = logging.getLogger("agents")

def monitored_conversation(agent_id, query):
    """Beszélgetés monitorozással."""
    start = time.time()

    response = client.beta.conversations.start(
        agent_id=agent_id,
        inputs=query,
        handoff_execution="client"
    )

    handoff_count = 0
    tool_count = 0

    for entry in response.outputs:
        if entry.type == "agent.handoff":
            handoff_count += 1
            logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
        elif entry.type == "tool.execution":
            tool_count += 1
            logger.info(f"Tool #{tool_count}: {entry.tool_name}")

    duration = time.time() - start
    logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")

    return response

Ez a két számláló többet ér, mint amit az egyszerűségük sugall: az átlagos átadások számának eltolódása azt jelzi, hogy az útválasztó habozik; az eszközhívások hirtelen növekedése pedig drága lekérdezésekre utal.

A költségek kontrollálása ezután konkrét döntéseken múlik. Monitorozd a tokenek számát beszélgetésenként, mivel ez a valódi számlázási egység. Használd a mistral-medium-latest modellt wherever a mistral-large-latest nem ad hozzá semmit – az első szintű támogatás erre tankönyvi példa. Korlátozd a max_tokens értékét a completion_args paraméterben, hogy elkerüld a végtelen válaszokat egyszerű kérdésekre, és tiltsd le a tárolást a store=False beállítással, amikor a perzisztencia nem szükséges.

Útválasztás tesztelése

Egy többrészes ügynöki rendszert úgy tesztelj, mint bármelyik kapcsolótáblát: tápláld be azokat az eseteket, amelyek várható célállomását ismered, és ellenőrizd, hová landolnak.

def test_agent_routing():
    """Ellenőrzi, hogy az útválasztó helyesen osztja-e szét a kéréseket."""
    test_cases = [
        ("What is the price of Bitcoin?", "web-search-agent"),
        ("Calculate 25 * 48", "calculator-agent"),
        ("Summarize this document", "doc-agent"),
    ]

    for query, expected_agent_name in test_cases:
        response = client.beta.conversations.start(
            agent_id=router.id,
            inputs=query,
            handoff_execution="client"
        )

        for entry in response.outputs:
            if entry.type == "agent.handoff":
                target = client.beta.agents.get(agent_id=entry.next_agent_id)
                assert target.name == expected_agent_name, \
                    f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"

Építsd fel ezt a tesztkészletet idővel: minden éles környezetben elkapott helytelenül útválasztott kérés egy új sor a test_cases listában, és így tudni fogod, hogy egy leírás átírása javítja a célzott esetet anélkül, hogy másikat törne el.

Referenciarchitektúra

Egy éles projekthez íme egy ajánlott architektúra:

Application
    │
    ▼
Moderator Agent (filters requests)
    │
    ▼
Router Agent (distributes to specialists)
    ├── Search Agent (web_search)
    ├── Analysis Agent (code_interpreter)
    ├── Documents Agent (document_library)
    └── Creation Agent (image_generation)
    │
    ▼
Logging + Monitoring + Alerting

Ez egyesíti a tanfolyam minden elemét: a moderátor szűr a végrehajtás előtt, az útválasztó irányít anélkül, hogy valaha is maga válaszolna, minden szakértő egyetlen eszközt és egyetlen felelősséget hordoz, a megfigyelés pedig körbeveszi az egész rendszert.

Merre tovább?

Négy irány terjeszti ki azt, amit most már képes vagy megtenni. A függvényhívás (function calling) lehetővé teszi, hogy saját egyedi eszközöket építs a beépítetteken túl: hívj meg egy üzleti API-t, kérdezz le egy adatbázist, vagy indíts el egy belső szolgáltatást. Az MCP Servers integrálja a Model Context Protocolt, amely szabványosítja az eszközök közzétételének módját. A strukturált kimenetek (structured outputs) JSON sémába kényszerítik a válaszokat, ami mindent megváltoztat, amikor egy ügynök kimenete egy másik rendszert táplál, nem pedig egy emberi olvasót. Végül a streaming valós időben adja vissza a válaszokat egyetlen blokk helyett – ez döntő fontosságú hosszú láncok esetén, ahol a csendes várakozás kellemetlenné válik.

Három forrás kíséri ezt a következő lépést: a hivatalos dokumentáció a docs.mistral.ai/agents címen, a Mistral cookbooks, amelyek teljes implementációs példákat tartalmaznak, és az API Reference, amely részletesen dokumentál minden végpontot.

Főbb megállapítások

  • Specializáld az ügynökeidet – egy ügynök = egy felelősség
  • Monitorozz – naplózz minden átadást és eszközvégrehajtást
  • Tesztelj – validáld az útválasztást és az egyes ügynökök válaszait
  • Biztosíts – korlátok (guardrails), legkisebb jogosultság elve, bemeneti oldali moderáció
  • Optimalizáld a költségeket – megfelelő méretű modell, max_tokens, store=False, amikor lehetséges
  • A Mistral Agents még béta verzióban van – tartsd naprakészen magad az API változásaival

Teszteld a tudásod!

Ügynökök, beépített eszközök, átadások: maradt-e vakfolt az Agents API-ban?

1. Mikor szükséges egy ügynök – és mikor elég egy chatbot?

Válasz: Egy ügynök akkor indokolt, ha eszközökre, perzisztenciára és többlépéses döntésekre van szükség; egyszerű kérdés-felelet típusú feladatokhoz egy szabványos beszélgetés elég – az architektúra követi az igényt.

2. Mit kezelnek a perzisztens beszélgetések az Agents API-ban?

Válasz: A történetet a Mistral oldalán: egy beszélgetést az ID-je alapján folytatsz anélkül, hogy újra elküldenéd az egész kontextust – az állapot szolgáltatássá válik.

3. Sorold fel a rendelkezésre álló beépített eszközöket és használatukat!

Válasz: web_search (valós idejű információk), code_interpreter (Python futtatása), image_generation (képek létrehozása), document_library (kérdés-felelet a saját fájlokon) – használatra kész képességek, implementáció nélkül.

4. Hogyan működik egy többrészes ügynöki rendszer átadásokkal?

Válasz: Egy útválasztó minősíti a kérést, és átadja az illetékes szakértő ügynöknek; minden ügynök egyszerű marad, az orchestráció biztosítja a lefedettséget – és az átadások mélységében láncolódnak.

5. Hogyan biztosítod az ügynököket éles környezetben?

Válasz: Bemeneti/kimeneti korlátokkal, szűken meghatározott hatókörű eszközökkel, műveletek nyomon követhetőségével és emberi jóváhagyással a nagy tétű döntéseknél – az autonómia a kontroll révén earnedhető ki.

Specializált ügynökök, beépített eszközök, útválasztás, korlátok: a teljes architektúra négy szóba sűríthető – és ebben a tanfolyamban mindegyiket te építetted fel.