Specializált ügynökök és egy útválasztó létrehozása
Ezen az oldalon
Az elmélettől a gyakorlatig
Az előző leckében megismerkedtél az átadások (handoffs) fogalmával. Most felépíted a teljes rendszert a helyes sorrendben: először a szakértőket, majd az útválasztót, ezt követően a közöttük lévő kapcsolatot, végül pedig azt a beszélgetést, amely mindent elindít. Ez a sorrend nem önkényes: az útválasztó csak olyan ügynökökre mutathat, amelyek már léteznek.
1. lépés: A szakértő ügynökök létrehozása
Minden ügynök egy pontosan meghatározott szakterületet kap, és semmi mást.
from mistralai.client import Mistral
from mistralai.client.models import CompletionArgs, ResponseFormat, JSONSchema
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Webes kereső ügynök
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"}]
)
# Pénzügyi ügynök
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"""
)
# Számológép ügynök
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"}]
)
Ez a négy mező nagyon különböző szerepet tölt be, és közülük egy kiemelt figyelmet érdemel. A name (kötőjeles formátumban) neked szól: ez jelenik meg a naplóidban és tesztjeidben, és egy olvasható név megkímél attól, hogy átláthatatlan azonosítókat hasonlíts össze. Az instructions a modellhez szólnak, mihelyt az munkához lát, ezért ezeknek domainspecifikusnak kell lenniük – a „kockázatok jelzése“ valamit jelent egy pénzügyi ügynöknek, míg a „légy segítőkész“ senkinek sem mond semmit. A tools a szigorú szükségesség elvét követi: a fenti pénzügyi ügynöknek nincsenek eszközei, mert eszközök nélkül is képes következtetni, és eszközök biztosítása csak visszaélésre adna lehetőséget. Végül a description nem dokumentáció: ez az a szöveg, amelyet az útválasztó olvas, hogy eldöntse, ide vagy máshova továbbítsa-e a kérést.
2. lépés: Az útválasztó ügynök létrehozása
Az útválasztónak nincsenek eszközei. Teljes feladata abból áll, hogy elemezze a kérést, és kiválassza a címzettet.
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."""
)
Az utolsó sor akadályozza meg a rendszer összeomlását. Enélkül egy nagy modellen alapuló útválasztó megválaszolná azokat a kérdéseket, amelyek számára könnyűnek tűnnek, megkerülné a szakértőket, és olyan válaszokat produkálna, amelyekhez hiányoznak azok az eszközök, amelyeket a szakértők használtak volna. Így egy olyan többügynökös architektúrát kapnál, ahol az ügynökök fele sosem kerül felhasználásra.
3. lépés: Az átadási célok meghatározása
Most meg kell mondanod az útválasztónak, hogy mely ügynököknek továbbíthat kéréseket.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
A handoffs paraméter ügynök-azonosítók listáját várja, és az útválasztó bármelyiküknek továbbíthat. Ez nem az útválasztó kiváltsága: a szakértők is deklarálhatják a saját céljaikat.
# A pénzügyi ügynök továbbíthat a webes keresőnek és a számológépnek is
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Így lehetővé válik egy olyan láncolat, mint: útválasztó → pénzügy → webes keresés → számológép. Amikor a pénzügyi ügynök olyan kérdéssel szembesül, amelyhez aktuális árfolyamra van szükség, nem adja vissza a kérést az útválasztónak: közvetlenül ahhoz a szakértőhöz fordul, akire szüksége van, pontosan úgy, ahogy egy tanácsadó közvetlenül hívja fel a kollégáját, ahelyett, hogy visszamenne a portára.
4. lépés: A beszélgetés elindítása
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."
)
# A folyamat elemzése
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]}...")
Futtasd ezt a kérést, és figyeld meg a nyomkövetést, mielőtt megnéznéd a választ. Két átadást és legalább egy eszközvégrehajtást kell látnod; ha egyiket sem látod, az útválasztód egyedül válaszolt, és itt az ideje, hogy szigorítsd az utasításait.
A fő eszköz: a leírás
Amikor az útválasztás meghibásodik, az szinte mindig a leírás hibája. Az útválasztó nem ismeri a szándékaidat; csak ezt a szöveget olvassa el minden jelölt ügynöknél.
# Rossz — túl általános
description="A useful agent."
# Jó — az útválasztó tudja, mikor kell továbbítania
description="Agent that searches for current information on the Internet and cites its sources."
Minden leírást úgy írj meg, mint választ arra a kérdésre, hogy „milyen esetben hívjam meg ezt az ügynököt?“, ne pedig úgy, mint ami összefoglalja, hogy mi is az. A második példa megnevezi a helyzetet – aktuális információk, az interneten –, míg az első találgatásra kényszeríti az útválasztót. Arra is ügyelj, hogy ne legyen átfedés egyetlen leíráspár között sem: két hasonló kifejezésekkel leírt ügynök instabil útválasztást eredményez egyik futtatásról a másikra.
Teljes példa
Íme a tömörített változat, ahol a handoffs paramétert közvetlenül az útválasztó létrehozásakor adjuk meg, mivel a szakértők ekkorra már léteznek.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Szakértő ügynökök
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. Útválasztó átadásokkal
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. Indítás
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analyze the European cloud computing market in 2026: size, players, trends."
)
Főbb megállapítások
- Hozz létre szakértő ügynököket pontos, feladatorientált leírásokkal
- Az útválasztó a leírások alapján választja ki a célügynököt
- A
client.beta.agents.update(handoffs=[...])határozza meg az átadási célokat - Az átadások egymásba ágyazhatók (A ügynök → B ügynök → C ügynök)
- Minden ügynök leírása az útválasztás minőségének elsődleges eszköze