Crearea agenților specializați și a unui router
Pe această pagină
De la teorie la practică
Lecția anterioară a introdus conceptul de transferuri (handoffs). Acum veți construi sistemul complet în ordinea reală de execuție: mai întâi specialiștii, apoi routerul, ulterior conexiunile dintre ei și, în final, conversația care pune totul în mișcare. Această ordine nu este arbitrară: routerul poate indica doar agenți care există deja.
Pasul 1: Crearea agenților specializați
Fiecare agent primește un domeniu precis de expertiză și nimic altceva.
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 de căutare web
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"}]
)
# Agent financiar
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"""
)
# Agent calculator
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"}]
)
Aceste patru câmpuri joacă roluri foarte diferite, iar unul dintre ele merită o atenție specială. Câmpul name în format kebab-case este pentru dumneavoastră: apare în jurnalele de activitate (logs) și în teste, iar un nume lizibil vă scutește de compararea unor ID-uri opace. Câmpul instructions se adresează modelului odată ce acesta începe să lucreze, așa că trebuie să fie specific domeniului — „semnalează riscurile“ are sens pentru un agent financiar, în timp ce „fii util“ nu înseamnă nimic pentru nimeni. Câmpul tools respectă principiul necesității stricte: agentul financiar de mai sus nu are instrumente deoarece raționează fără a avea nevoie de ele, iar oferirea unor instrumente ar invita doar la utilizări abuzive. În final, câmpul description nu este documentație: este textul pe care routerul îl citește pentru a decide dacă transferă aici sau în altă parte.
Pasul 2: Crearea agentului router
Routerul nu are instrumente. Întreaga sa sarcină constă în analizarea cererii și alegerea destinatarului.
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."""
)
Această ultimă linie previne colapsul sistemului. Fără ea, un router construit pe un model mare va răspunde la întrebări care i se par ușoare, va ocoli specialiștii dumneavoastră și va produce răspunsuri fără instrumentele pe care aceștia le-ar fi folosit. Veți ajunge cu o arhitectură multi-agent în care jumătate din agenți nu sunt niciodată utilizați.
Pasul 3: Definirea țintelor de transfer
Acum trebuie să indicați routerului către ce agenți are voie să transfere.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
Parametrul handoffs primește o listă de ID-uri de agenți, iar routerul poate transfera către oricare dintre ei. Acest lucru nu este un privilegiu rezervat routerului: specialiștii își pot declara, de asemenea, propriile ținte.
# Agentul financiar poate transfera către căutarea web și calculator
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Un lanț de tip router → finanțe → căutare web → calculator devine astfel posibil. Când agentul financiar se confruntă cu o întrebare care necesită o rată actuală, nu se întoarce la router: merge direct la specialistul de care are nevoie, exact ca un consultant care sună un coleg în loc să treacă din nou prin recepție.
Pasul 4: Inițierea conversației
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."
)
# Analiza fluxului
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]}...")
Executați această cerere și observați urma (trace) înainte de a privi răspunsul. Ar trebui să vedeți două transferuri și cel puțin o execuție de instrument; dacă nu vedeți niciunul, routerul a răspuns singur și este momentul să îi strângeți instrucțiunile.
Pârghia principală: descrierea
Când rutarea eșuează, descrierea este aproape întotdeauna de vină. Routerul nu vă cunoaște intențiile; el citește doar acest text pentru fiecare agent candidat.
# Rău — prea vag
description="A useful agent."
# Bine — routerul știe când să transfere
description="Agent that searches for current information on the Internet and cites its sources."
Scrieți fiecare descriere ca un răspuns la întrebarea „în ce caz ar trebui să apel acest agent?“ mai degrabă decât ca un rezumat al ceea ce este acesta. Al doilea exemplu numește situația — informații actuale, pe Internet — în timp ce primul îl lasă pe router să ghicească. Verificați, de asemenea, ca nicio pereche de descrieri să nu se suprapună: doi agenți descriși în termeni similari vor produce o rutare instabilă de la o execuție la alta.
Exemplu complet
Iată versiunea condensată, cu handoffs transmise direct în timpul creării routerului, deoarece specialiștii există deja în acel moment.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Agenți specializați
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. Router cu transferuri
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. Lansare
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analyze the European cloud computing market in 2026: size, players, trends."
)
Puncte cheie
- Creați agenți specializați cu descrieri precise, orientate spre sarcini
- Routerul folosește descrierile pentru a alege agentul țintă
client.beta.agents.update(handoffs=[...])definește țintele de transfer- Transferurile pot fi imbricate (agent A → agent B → agent C)
- Descrierea fiecărui agent este pârghia principală pentru calitatea rutării