Legjobb gyakorlatok és következő lépések
Ezen az oldalon
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.