Vytvoření specializovaných agentů a směrovače
Na této stránce
Od teorie k praxi
Minulá lekce ti představila koncept předávání úloh (handoffs). Nyní postavíš kompletní systém v přesném pořadí vývoje: nejprve specialisté, poté směrovač, následně propojení mezi nimi a nakonec konverzace, která vše uvede do chodu. Toto pořadí není náhodné – směrovač může odkazovat pouze na agenty, kteří již existují.
Krok 1: Vytvoření specializovaných agentů
Každý agent obdrží přesně vymezenou oblast odbornosti a nic navíc.
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 pro vyhledávání na webu
web_agent = client.beta.agents.create(
model="mistral-large-latest",
name="web-search-agent",
description="Agent that searches for information online.",
instructions="Perform precise web searches. Always cite your sources.",
tools=[{"type": "web_search"}]
)
# Finanční agent
finance_agent = client.beta.agents.create(
model="mistral-large-latest",
name="finance-agent",
description="Agent specialized in financial questions.",
instructions="""You are a financial expert.
- Use numerical data
- Explain concepts clearly
- Flag risks"""
)
# Kalkulační agent
calculator_agent = client.beta.agents.create(
model="mistral-large-latest",
name="calculator-agent",
description="Agent for detailed mathematical calculations.",
instructions="Explain each step of the calculation. Use the code interpreter for complex calculations.",
tools=[{"type": "code_interpreter"}]
)
Tyto čtyři pole hrají velmi odlišné role a jedno z nich si zaslouží zvláštní pozornost. Hodnota name ve formátu kebab-case slouží tobě: objevuje se v logách a testech a čitelný název ti ušetří porovnávání neprůhledných ID. Pole instructions oslovuje model, jakmile začne pracovat, proto musí být specifické pro danou doménu – „označ rizika“ má pro finančního agenta smysl, zatímco „buď nápomocný“ neznamená nic pro nikoho. Nástroje (tools) se řídí principem přísné nezbytnosti: výše uvedený finanční agent žádné nástroje nemá, protože usuzuje bez jejich potřeby, a jejich přidání by jen lákalo ke zneužití. Nakonec, description není dokumentace: je to text, který směrovač čte, aby se rozhodl, zda úkol předat sem, nebo jinam.
Krok 2: Vytvoření agenta-směrovače
Směrovač nemá žádné nástroje. Jeho jediným úkolem je analyzovat požadavek a vybrat příjemce.
router_agent = client.beta.agents.create(
model="mistral-large-latest",
name="router-agent",
description="Router agent that distributes requests.",
instructions="""You are an orchestrator.
Analyze each request and transfer to the right agent:
- Questions requiring online data → web-search-agent
- Financial questions → finance-agent
- Calculations and numerical analysis → calculator-agent
Never answer directly—always transfer."""
)
Poslední řádek zabraňuje kolapsu systému. Bez něj by směrovač postavený na velkém modelu odpovídal na otázky, které se mu zdají snadné, obešel by tvé specialisty a produkoval by odpovědi bez použití nástrojů, které by oni využili. Výsledkem by byla architektura více agentů, kde by polovina z nich nikdy nepřišla ke slovu.
Krok 3: Definice cílů předávání úloh
Nyní musíš směrovači sdělit, na které agenty smí úlohy předávat.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
Parametr handoffs přijímá seznam ID agentů a směrovač může předávat úlohy kterémukoli z nich. Není to výsada vyhrazená pouze směrovači: specialisté mohou také deklarovat své vlastní cíle.
# Finanční agent může předávat úlohy vyhledávání na webu a kalkulačnímu agentovi
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Řetězec typu směrovač → finance → vyhledávání na webu → kalkulačka se tak stává možným. Když finanční agent narazí na otázku vyžadující aktuální kurz, nevrací se zpět ke směrovači: jde přímo za specialistou, kterého potřebuje, stejně jako konzultant, který zavolá kolegovi, místo aby se vracel přes recepci.
Krok 4: Spuštění konverzace
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Find the current ECB key interest rate and calculate compound interest over 10 years for €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ť tento požadavek a pozoruj stopu (trace) předtím, než se podíváš na odpověď. Měl bys vidět dvě předání úloh a alespoň jedno provedení nástroje; pokud neuvidíš žádné, tvůj směrovač odpověděl sám a je čas zpřísnit jeho instrukce.
Hlavní páka: popis (description)
Když směrování selže, téměř vždy za to může popis. Směrovač nezná tvé záměry; čte pouze tento text pro každého kandidátského agenta.
# Špatně — příliš vágní
description="A useful agent."
# Dobře — směrovač ví, kdy předat úlohu
description="Agent that searches for current information on the Internet and cites its sources."
Každý popis piš jako odpověď na otázku „v jakém případě mám tohoto agenta zavolat?“, nikoliv jako shrnutí toho, co dělá. Druhý příklad pojmenovává situaci – aktuální informace, na internetu –, zatímco první nechává směrovače tápat. Také ověř, že se žádné dva popisy nepřekrývají: dva agenti popsaní podobnými termíny budou produkovat nestabilní směrování od jednoho spuštění k druhému.
Kompletní příklad
Zde je zkrácená verze, kde jsou handoffs předány přímo při vytváření směrovače, protože specialisté v tu chvíli již existují.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Specializovaní agenti
research = client.beta.agents.create(
model="mistral-large-latest",
name="research-agent",
description="Online information search with sources.",
tools=[{"type": "web_search"}]
)
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="analyst-agent",
description="Data analysis and calculations with Python.",
tools=[{"type": "code_interpreter"}]
)
writer = client.beta.agents.create(
model="mistral-large-latest",
name="writer-agent",
description="Drafting structured and professional reports.",
instructions="Write clear reports with an introduction, analysis, and recommendations."
)
# 2. Směrovač s definovanými předáními
router = client.beta.agents.create(
model="mistral-large-latest",
name="router",
description="Orchestrates complex requests.",
instructions="Analyze the request and transfer to the appropriate specialist.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Spuštění
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analyze the European cloud computing market in 2026: size, players, trends."
)
Klíčové poznatky
- Vytvářej specializované agenty s přesnými popisy orientovanými na úkoly
- Směrovač používá popisy k výběru cílového agenta
client.beta.agents.update(handoffs=[...])definuje cíle předávání úloh- Předávání úloh může být vnořené (agent A → agent B → agent C)
- Popis každého agenta je hlavním nástrojem pro kvalitu směrování