Ustvari specializirane agente in usmerjevalnik
Na tej strani
Od teorije do prakse
Prejšnja lekcija je uvedla koncept predaj (handoffs). Zdaj boš zgradil celoten sistem v pravilnem vrstnem redu gradnje: najprej specialiste, nato usmerjevalnik, nato povezave med njimi in nazadnje pogovor, ki vse sproži. Ta vrstni red ni poljuben – usmerjevalnik lahko kaže le na agente, ki že obstajajo.
1. korak: Ustvari specializirane agente
Vsak agent prejme natančno določeno področje strokovnosti in nič drugega.
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 za spletno iskanje
web_agent = client.beta.agents.create(
model="mistral-large-latest",
name="web-search-agent",
description="Agent, ki išče informacije na spletu.",
instructions="Izvajaj natančna spletna iskanja. Vedno navedi svoje vire.",
tools=[{"type": "web_search"}]
)
# Finančni agent
finance_agent = client.beta.agents.create(
model="mistral-large-latest",
name="finance-agent",
description="Agent, specializiran za finančna vprašanja.",
instructions="""Si finančni strokovnjak.
- Uporabljaj numerične podatke
- Jasno razlagaj koncepte
- Opozori na tveganja"""
)
# Agent za kalkulator
calculator_agent = client.beta.agents.create(
model="mistral-large-latest",
name="calculator-agent",
description="Agent za podrobne matematične izračune.",
instructions="Razloži vsak korak izračuna. Za kompleksne izračune uporabi interpreter kode.",
tools=[{"type": "code_interpreter"}]
)
Ta štiri polja igrajo zelo različne vloge in eno si zasluži posebno pozornost. name v kebab-case je zate: pojavlja se v tvojih dnevnikih in testih, berljivo ime pa ti prihrani primerjanje nejasnih ID-jev. instructions nagovarjajo model, ko začne delovati, zato morajo biti specifične za domeno – „opozori na tveganja” nekaj pomeni finančnemu agentu, medtem ko „bodi uporaben” ne pomeni ničesar nikomur. tools sledijo načelu stroge nujnosti: zgornji finančni agent nima orodij, ker razmišlja brez potrebe po njih, in dajanje orodij bi le povabilo v zlorabo. Nazadnje, description ni dokumentacija: to je besedilo, ki ga usmerjevalnik prebere, da se odloči, ali naj prenese sem ali drugam.
2. korak: Ustvari agentskega usmerjevalnika
Usmerjevalnik nima orodij. Njegovo edino delo je analizirati zahtevo in izbrati prejemnika.
router_agent = client.beta.agents.create(
model="mistral-large-latest",
name="router-agent",
description="Usmerjevalni agent, ki distribuira zahteve.",
instructions="""Si koordinator.
Analiziraj vsako zahtevo in jo prenesi pravemu agentu:
- Vprašanja, ki zahtevajo spletne podatke → web-search-agent
- Finančna vprašanja → finance-agent
- Izračuni in numerična analiza → calculator-agent
Nikoli ne odgovarjaj neposredno – vedno prenesi."""
)
Zadnja vrstica preprečuje kolaps sistema. Brez nje bi usmerjevalnik, zgrajen na velikem modelu, odgovarjal na vprašanja, ki se mu zdijo enostavna, obšel tvoje specialiste in proizvedel odgovore brez orodij, ki bi jih ti uporabili. Končaš z arhitekturo več agentov, kjer polovica agentov nikoli ne pride do uporabe.
3. korak: Določi cilje predaje
Zdaj moraš usmerjevalniku povedati, na katere agente sme prenašati.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
Parameter handoffs sprejme seznam ID-jev agentov in usmerjevalnik lahko prenese na katerega koli od njih. To ni privilegij, rezerviran samo za usmerjevalnik: tudi specialisti lahko deklarirajo svoje cilje.
# Finančni agent lahko prenese na spletno iskanje in kalkulator
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Veriga, kot je usmerjevalnik → finance → spletno iskanje → kalkulator, tako postane mogoča. Ko se finančni agent sooči z vprašanjem, ki zahteva trenutni tečaj, se ne vrne k usmerjevalniku: gre neposredno k specialistu, ki ga potrebuje, tako kot svetovalec, ki pokliče kolega, namesto da bi šel nazaj skozi recepcijo.
4. korak: Začni pogovor
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Poišči trenutno ključno obrestno mero ECB in izračunaj obrestno obrestovanje za 10 let za 100.000 €."
)
# Analiziraj tok
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]}...")
Zaženi to zahtevo in opazuj sled, preden pogledaš odgovor. Videti bi moral dve predaji in vsaj eno izvršitev orodja; če ne vidiš nobene, je tvoj usmerjevalnik odgovoril sam in čas je, da zaostríš njegova navodila.
Glavni vzvod: opis
Ko usmerjanje odpove, je skoraj vedno kriv opis. Usmerjevalnik ne pozna tvojih namenov; prebere le to besedilo za vsakega kandidata.
# Slabo — preveč ohlapno
description="Uporaben agent."
# Dobro — usmerjevalnik ve, kdaj prenesti
description="Agent, ki išče trenutne informacije na internetu in navaja svoje vire."
Vsak opis napiši kot odgovor na vprašanje „v katerem primeru naj pokličem tega agenta?” namesto kot povzetek tega, kaj je. Drugi primer imenuje situacijo – trenutne informacije, na internetu –, medtem ko prvi pušča usmerjevalnika v ugibanju. Prav tako preveri, da se noben par opisov ne prekriva: dva agenta, opisana s podobnimi izrazi, bosta proizvedla nestabilno usmerjanje od ene izvedbe do druge.
Celoten primer
Tukaj je kondenzirana različica, kjer so handoffs podani neposredno ob ustvarjanju usmerjevalnika, saj specialisti do takrat že obstajajo.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Specializirani agenti
research = client.beta.agents.create(
model="mistral-large-latest",
name="research-agent",
description="Iskanje spletnih informacij z viri.",
tools=[{"type": "web_search"}]
)
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="analyst-agent",
description="Analiza podatkov in izračuni s Pythonom.",
tools=[{"type": "code_interpreter"}]
)
writer = client.beta.agents.create(
model="mistral-large-latest",
name="writer-agent",
description="Priprava strukturiranih in profesionalnih poročil.",
instructions="Piši jasna poročila z uvodom, analizo in priporočili."
)
# 2. Usmerjevalnik s predajami
router = client.beta.agents.create(
model="mistral-large-latest",
name="router",
description="Koordinira kompleksne zahteve.",
instructions="Analiziraj zahtevo in jo prenesi ustreznemu specialistu.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Zagon
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analiziraj evropski trg računalništva v oblaku leta 2026: velikost, akterji, trendi."
)
Ključne ugotovitve
- Ustvari specializirane agente s preciznimi opisi, usmerjenimi v nalogo
- Usmerjevalnik uporablja opise za izbiro ciljnega agenta
client.beta.agents.update(handoffs=[...])določa cilje prenosa- Predaje so lahko gnezdene (agent A → agent B → agent C)
- Opis vsakega agenta je glavni vzvod za kakovost usmerjanja