Vytváranie špecializovaných agentov a smerovača
Na tejto strane
Od teórie k praxi
Predchádzajúca lekcia predstavila koncept odovzdávania (handoffs). Teraz zostavíš celý systém v správnom poradí: najprv špecialisti, potom smerovač, následne prepojenie medzi nimi a nakoniec konverzácia, ktorá všetko uvedie do chodu. Toto poradie nie je náhodné – smerovač môže odkazovať len na agentov, ktorí už existujú.
Krok 1: Vytvorenie špecializovaných agentov
Každý agent dostane presne vymedzenú oblasť expertízy a nič viac.
from mistralai.client import Mistral
from mistralai.client.models import CompletionArgs, ResponseFormat, JSONSchema
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Agent na vyhľadávanie na webe
web_agent = client.beta.agents.create(
model="mistral-large-latest",
name="web-search-agent",
description="Agent, ktorý vyhľadáva informácie online.",
instructions="Vykonávaj presné vyhľadávania na webe. Vždy uvádzaj zdroje.",
tools=[{"type": "web_search"}]
)
# Finančný agent
finance_agent = client.beta.agents.create(
model="mistral-large-latest",
name="finance-agent",
description="Agent špecializovaný na finančné otázky.",
instructions="""Si finančný expert.
- Používaj numerické údaje
- Vysvetľuj koncepty jasne
- Označuj riziká"""
)
# Agent kalkulačka
calculator_agent = client.beta.agents.create(
model="mistral-large-latest",
name="calculator-agent",
description="Agent na podrobné matematické výpočty.",
instructions="Vysvetli každý krok výpočtu. Na zložité výpočty používaj interpret kódu.",
tools=[{"type": "code_interpreter"}]
)
Tieto štyri polia zohrávajú veľmi odlišné úlohy a jedno si zaslúži osobitnú pozornosť. name v tvare kebab-case slúži tebe: objavuje sa v tvojich logoch a testoch a čitateľný názov ťa ušetrí od porovnávania neprehľadných ID. instructions sa adresujú modelu, keď začne pracovať, preto musia byť špecifické pre danú doménu – „označuj riziká“ má zmysel pre finančného agenta, zatiaľ čo „buď nápomocný“ neznamená nič pre nikoho. tools sa riadia princípom prísnej nevyhnutnosti: vyššie uvedený finančný agent nemá žiadne nástroje, pretože usudzuje bez ich potreby, a poskytnutie nástrojov by len invitowało k zneužitiu. Nakoniec, description nie je dokumentácia: je to text, ktorý smerovač číta, aby sa rozhodol, či má úlohu presmerovať sem, alebo inam.
Krok 2: Vytvorenie agenta smerovača
Smerovač nemá žiadne nástroje. Jeho celá práca spočíva v analýze požiadavky a výbere príjemcu.
router_agent = client.beta.agents.create(
model="mistral-large-latest",
name="router-agent",
description="Smerovací agent, ktorý distribuuje požiadavky.",
instructions="""Si orchestrátor.
Analyzuj každú požiadavku a presmeruj ju na správneho agenta:
- Otázky vyžadujúce online údaje → web-search-agent
- Finančné otázky → finance-agent
- Výpočty a numerická analýza → calculator-agent
Nikdy neodpovedaj priamo – vždy presmeruj."""
)
Posledný riadok zabraňuje kolapsu systému. Bez neho by smerovač postavený na veľkom modeli odpovedal na otázky, ktoré sa mu zdajú jednoduché, obišiel by tvojich špecialistov a produkoval by odpovede bez nástrojov, ktoré by oni použili. Výsledkom by bola multi-agentná architektúra, kde by polovica agentov zostala nevyužitá.
Krok 3: Definovanie cieľov odovzdania
Teraz musíš smerovaču povedať, na ktorých agentov sa smie presmerovať.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
Parameter handoffs prijíma zoznam ID agentov a smerovač sa môže presmerovať na ktoréhokoľvek z nich. Nie je to výsada vyhradená len pre smerovač: aj špecialisti môžu deklarovať svoje vlastné ciele.
# Finančný agent sa môže presmerovať na vyhľadávanie na webe a kalkulačku
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Reťazec typu smerovač → financie → vyhľadávanie na webe → kalkulačka sa tak stáva možným. Keď finančný agent narazí na otázku, ktorá si vyžaduje aktuálny kurz, nevracia sa späť k smerovaču: ide priamo na špecialistu, ktorého potrebuje, presne ako konzultant, ktorý zavolá kolegovi, namiesto toho, aby sa vracal cez recepciu.
Krok 4: Spustenie konverzácie
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Nájdi aktuálnu základnú úrokovú sadzbu ECB a vypočítaj zložené úročenie na 10 rokov pre 100 000 €."
)
# Analýza toku
for entry in response.outputs:
if entry.type == "agent.handoff":
print(f"[HANDOFF] → {entry.next_agent_id}")
elif entry.type == "tool.execution":
print(f"[TOOL] {entry.tool_name}")
elif entry.type == "message.output":
print(f"[RESPONSE] {entry.content[:200]}...")
Spusť túto požiadavku a pozoruj stopu (trace) skôr, než sa pozrieš na odpoveď. Mal by si vidieť dve odovzdania a aspoň jedno vykonanie nástroja; ak neuvidíš žiadne, tvoj smerovač odpovedal sám a je čas sprísniť jeho inštrukcie.
Hlavná páka: popis (description)
Keď smerovanie zlyhá, takmer vždy je na vine popis. Smerovač nepozná tvoje úmysly; číta len tento text pre každého kandidátskeho agenta.
# Zlé – príliš vágne
description="Užitočný agent."
# Dobré – smerovač vie, kedy presmerovať
description="Agent, ktorý vyhľadáva aktuálne informácie na internete a uvádza svoje zdroje."
Napíš každý popis ako odpoveď na otázku „v akom prípade mám zavolať tohto agenta?“, nie ako zhrnutie toho, čo robí. Druhý príklad pomenúva situáciu – aktuálne informácie, na internete –, zatiaľ čo prvý necháva smerovača hádať. Tiež over, či sa žiadne dvojice popisov neprekrývajú: dvaja agenti opísaní podobnými termínmi budú produkovať nestabilné smerovanie z jedného spustenia na druhé.
Kompletný príklad
Tu je skrátená verzia, kde sú handoffs odovzdané priamo počas vytvárania smerovača, keďže špecialisti v tom momente už existujú.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Špecializovaní agenti
research = client.beta.agents.create(
model="mistral-large-latest",
name="research-agent",
description="Vyhľadávanie online informácií so zdrojmi.",
tools=[{"type": "web_search"}]
)
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="analyst-agent",
description="Analýza dát a výpočty pomocou Pythonu.",
tools=[{"type": "code_interpreter"}]
)
writer = client.beta.agents.create(
model="mistral-large-latest",
name="writer-agent",
description="Tvorba štruktúrovaných a profesionálnych správ.",
instructions="Píš jasné správy s úvodom, analýzou a odporúčaniami."
)
# 2. Smerovač s odovzdaniami
router = client.beta.agents.create(
model="mistral-large-latest",
name="router",
description="Orchestruje zložité požiadavky.",
instructions="Analyzuj požiadavku a presmeruj ju na príslušného špecialistu.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Spustenie
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analyzuj európsky trh cloud computingu v roku 2026: veľkosť, hráči, trendy."
)
Kľúčové poznatky
- Vytváraj špecializovaných agentov s presnými popismi orientovanými na úlohy
- Smerovač používa popisy na výber cieľového agenta
client.beta.agents.update(handoffs=[...])definuje ciele presmerovania- Odovzdania môžu byť vnorené (agent A → agent B → agent C)
- Popis každého agenta je hlavnou pákou pre kvalitu smerovania