Създаване на специализирани агенти и насочващ агент (router)
На тази страница
От теория към практика
Предходният урок въведе концепцията за предаване на контрола (handoffs). Сега ще изградите цялата система в реалния ред на създаване: първо специализираните агенти, след това насочващият агент (router), после връзките между тях и накрая разговорът, който привежда всичко в действие. Този ред не е произволен – насочващият агент може да сочи само към агенти, които вече съществуват.
Стъпка 1: Създаване на специализираните агенти
Всеки агент получава точно определена област на експертиза и нищо друго.
from mistralai.client import Mistral
from mistralai.client.models import CompletionArgs, ResponseFormat, JSONSchema
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Агент за уеб търсене
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"}]
)
# Финансов агент
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"""
)
# Агент калкулатор
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"}]
)
Тези четири полета играят много различни роли и едно от тях заслужава специално внимание. Полето name в кебаб-кейс (kebab-case) е за Вас: то се появява във Вашите логове и тестове, а четливо име Ви спестява сравняването на неясни идентификатори. Полето instructions се адресира до модела, щом той започне работа, затова трябва да бъде специфично за областта – „отбелязвайте рисковете“ има смисъл за финансов агент, докато „бъдете полезни“ не означава нищо за никого. Инструментите (tools) следват принципа на строгата необходимост: горният финансов агент няма инструменти, защото разсъждава, без да се нуждае от тях, и предоставянето им би поканило само злоупотреба. Накрая, description не е документация: това е текстът, който насочващият агент чете, за да реши дали да прехвърли задачата тук или някъде другаде.
Стъпка 2: Създаване на насочващия агент (router)
Насочващият агент няма инструменти. Цялата му работа се състои в анализиране на заявката и избор на получател.
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."""
)
Последният ред предотвратява срива на системата. Без него насочващият агент, изграден върху голям модел, ще отговаря на въпроси, които му се струват лесни, ще заобикаля Вашите специалисти и ще произвежда отговори без инструментите, които те биха използвали. В резултат получавате многоагентна архитектура, в която половината агенти никога не се използват.
Стъпка 3: Дефиниране на цели за предаване на контрола (handoff targets)
Сега трябва да кажете на насочващия агент към кои агенти му е позволено да прехвърля задачите.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
Параметърът handoffs приема списък с идентификатори на агенти и насочващият агент може да прехвърля към всеки от тях. Това не е привилегия, запазена само за насочващия агент: специализираните агенти също могат да декларират свои собствени цели.
# Финансовият агент може да прехвърля към уеб търсене и калкулатора
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Тогава верига като насочващ агент → финансов агент → уеб търсене → калкулатор става възможна. Когато финансовият агент се сблъска с въпрос, изискващ текущ курс, той не се връща към насочващия агент: той отива директно при специалиста, от който се нуждае, точно както консултант се обажда на колега, вместо да минава отново през рецепцията.
Стъпка 4: Стартиране на разговора
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."
)
# Анализ на потока
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]}...")
Изпълнете тази заявка и наблюдавайте следа (trace), преди да погледнете отговора. Трябва да видите две предавания на контрола и поне едно изпълнение на инструмент; ако не виждате нито едно, Вашият насочващ агент е отговорил сам и е време да затегнете инструкциите му.
Основният лост: описанието
Когато насочването се провали, почти винаги вината е в описанието. Насочващият агент не знае Вашите намерения; той чете само този текст за всеки кандидат-агент.
# Лошо — твърде неясно
description="A useful agent."
# Добре — насочващият агент кога да прехвърли
description="Agent that searches for current information on the Internet and cites its sources."
Напишете всяко описание като отговор на въпроса „в какъв случай трябва да извикам този агент?“, а не като резюме на това какво представлява той. Вторият пример назовава ситуацията – текуща информация, в интернет –, докато първият оставя насочващия агент да гадае. Също така проверете дали няма двойка описания, които се припокриват: два агента, описани с подобни термини, ще произведат нестабилно насочване от едно изпълнение към следващото.
Пълен пример
Ето кондензираната версия, като handoffs се предават директно при създаването на насочващия агент, тъй като специалистите вече съществуват в този момент.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Специализирани агенти
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 = 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. Стартиране
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Analyze the European cloud computing market in 2026: size, players, trends."
)
Ключови изводи
- Създавайте специализирани агенти с точни, ориентирани към задачата описания
- Насочващият агент използва описанията, за да избере целевия агент
client.beta.agents.update(handoffs=[...])дефинира целите за прехвърляне- Предаванията на контрола могат да бъдат вложени (агент А → агент Б → агент В)
- Описанието на всеки агент е основният лост за качеството на насочването