Най-добри практики и следващи стъпки
На тази страница
Какво научихте
Преминахте през целия API на Mistral Agents. Нека направим кратко обобщение, преди да навлезем в практиките за продукционна среда, тъй като всяка част от този курс се гради върху предишната.
Първите три урока положиха основите: AI агентът е автономна система с цикъл „възприятие–действие“; API се базира на три обекта – Agent, Conversation и Entry; а това, което отличава агента от чатбот, е постоянството, инструментите и предаването на контрола (handoffs). Уроци 4 до 7 направиха тези обекти използваеми: създаване и конфигуриране на агенти чрез client.beta.agents.create(), поддържане на постоянни разговори с conversations.start() и conversations.append(), както и използване на директен режим без агент, когато прототипирате и постоянството не носи стойност.
Уроци 8 до 11 добавиха възможности. web_search Ви осигурява достъп до актуална информация с автоматични цитати; code_interpreter изпълнява Python в пясъчник (sandbox), предоставяйки на агента точни резултати там, където самият модел би дал приблизителни такива; image_generation създава визуализации от текстови подкани; document_library интегрира RAG за Вашите собствени документи. След това уроци 12 до 16 показаха как множество агенти работят заедно: предаването на контрола прехвърля управлението от един агент към друг, референтната архитектура съчетава централен насочващ агент (router) със специалисти, сървърният режим автоматизира процесите, докато клиентският режим Ви държи в цикъла на вземане на решения, а неограниченото верижно изпълнение се разпада на линейни, звездовидни и хибридни модели. Накрая, урок 17 обобщи всичко с предпазни механизми (guardrails), принципа на най-малките привилегии и модерация на входящите данни.
Проектиране на устойчиви агенти
Едно изречение обобщава целия курс: един агент, една отговорност, едно описание, което казва кога да бъде извикан. Контрастът по-долу прави разликата осезаема.
# ДОБРЕ — специализиран агент с точно описание
agent = client.beta.agents.create(
model="mistral-large-latest",
name="invoice-processor",
description="Processes invoices: extracts amounts, dates, vendors.",
instructions="Extract invoice information into structured JSON.",
tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)
# ЗЛЕ — общ, неясен агент
agent = client.beta.agents.create(
model="mistral-large-latest",
name="helper",
description="A helpful agent.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)
Вторият агент ще се провали по два начина едновременно. Никой насочващ агент (router) няма да знае кога да му прехвърли заявка, защото „полезен агент“ не описва никаква конкретна ситуация. И когато все пак бъде извикан, трите му инструмента му позволяват да търси в уеба нещо, което е трябвало да изчисли, или да илюстрира нещо, което е било помолен да анализира.
Обработка на грешки
Мрежовите обаждания рано или късно се провалят. Повторен опит с експоненциално забавяне (exponential backoff) абсорбира временни инциденти, без да превръща моментно забавяне в видим срив.
import time
def safe_conversation(agent_id, query, max_retries=3):
"""Conversation with error handling and retry."""
for attempt in range(max_retries):
try:
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Exponential backoff
return None
Експоненциалното забавяне – една секунда, после две, после четири – отличава цивилизования повторен опит от „бомбардирането“ на услуга, която вече се затруднява. Обърнете внимание също, че последният опит повторно генерира изключението, вместо да връща None: Вашият извикващ код трябва да знае, че операцията е неуспешна.
Наблюдение на процесите
В продукционна среда многоагентен работен поток, който не може да се наблюдава, става невъзможен за отстраняване на грешки. Клиентският режим Ви предоставя точно необходимите куки (hooks).
import logging
import time
logger = logging.getLogger("agents")
def monitored_conversation(agent_id, query):
"""Conversation with monitoring."""
start = time.time()
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query,
handoff_execution="client"
)
handoff_count = 0
tool_count = 0
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_count += 1
logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
elif entry.type == "tool.execution":
tool_count += 1
logger.info(f"Tool #{tool_count}: {entry.tool_name}")
duration = time.time() - start
logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")
return response
Тези два брояча струват повече, отколкото простотата им подсказва: отклонение в средния брой предавания на контрола сигнализира за колебание в насочващия агент; скок в обажданията към инструменти сочи към скъпи заявки.
Контролът на разходите след това се свежда до конкретни решения. Следете токена на разговор, тъй като това е реалната единица за таксуване. Използвайте mistral-medium-latest навсякъде, където mistral-large-latest не добавя нищо – първото ниво на поддръжка е учебен пример за това. Ограничете max_tokens в completion_args, за да избегнете безкрайни отговори на прости въпроси, и деактивирайте съхранението с store=False, когато постоянството не е необходимо.
Тестване на насочването
Тествайте многоагентна система като всяка телефонна централа: подайте ѝ случаи, чиято очаквана дестинация знаете, и проверете къде стигат.
def test_agent_routing():
"""Verifies that the router distributes correctly."""
test_cases = [
("What is the price of Bitcoin?", "web-search-agent"),
("Calculate 25 * 48", "calculator-agent"),
("Summarize this document", "doc-agent"),
]
for query, expected_agent_name in test_cases:
response = client.beta.conversations.start(
agent_id=router.id,
inputs=query,
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target = client.beta.agents.get(agent_id=entry.next_agent_id)
assert target.name == expected_agent_name, \
f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"
Изградете този тестов набор с времето: всяка грешно насочена заявка, която хванете в продукционна среда, става още един ред в test_cases, и ще знаете, че пренаписването на описание оправя целевия случай, без да нарушава друг.
Референтна архитектура
За продукционен проект ето една препоръчителна архитектура:
Application
│
▼
Moderator Agent (filters requests)
│
▼
Router Agent (distributes to specialists)
├── Search Agent (web_search)
├── Analysis Agent (code_interpreter)
├── Documents Agent (document_library)
└── Creation Agent (image_generation)
│
▼
Logging + Monitoring + Alerting
Тя обединява всичко от този курс: модераторът филтрира преди всяко изпълнение, насочващият агент разпределя, без никога да отговаря сам, всеки специалист носи един инструмент и една отговорност, а наблюдението обгръща цялата система.
Къде да продължите оттук
Четири направления разширяват възможностите Ви сега. Function calling Ви позволява да изградите свои собствени персонализирани инструменти извън вградените: извикване на бизнес API, заявка към база данни, задействане на вътрешна услуга. MCP Servers интегрират Model Context Protocol, който стандартизира начина, по който инструментите се излагат. Structured outputs принуждават отговорите да следват JSON схема, което променя всичко, когато изходът на агента захранва друга система, а не човешки читател. Накрая, streaming връща отговорите в реално време, вместо на един блок – решаващо за дълги вериги, където тихото чакане става неудобно.
Три ресурса придружават тази следваща стъпка: официалната документация на docs.mistral.ai/agents, готварските книги (cookbooks) на Mistral, които предоставят пълни примери за внедряване, и API справочникът, който документира всеки крайна точка в детайли.
Ключови изводи
- Специализирайте Вашите агенти – един агент = една отговорност
- Наблюдавайте – записвайте в дневник всяко предаване на контрол и изпълнение на инструмент
- Тествайте – валидирайте насочването и отговорите на всеки агент
- Сигурност – предпазни механизми, най-малки привилегии, входяща модерация
- Оптимизирайте разходите – модел с подходящ размер, max_tokens, store=False когато е възможно
- Mistral Agents са в бета версия – следете за промени в API
Проверете знанията си
Агенти, вградени инструменти, предаване на контрола: има ли слепи петна в API на Agents?
1. Кога е необходим агент – и кога е достатъчен чатбот?
Отговор: Агентът е оправдан, когато имате нужда от инструменти, постоянство и решения в няколко стъпки; за просто въпрос-отговор е достатъчен стандартен разговор – архитектурата следва нуждата.
2. Какво управляват постоянните разговори в API на Agents?
Отговор: Историята от страна на Mistral: продължавате разговор по неговия ID, без да изпращате отново целия контекст – състоянието става услуга.
3. Избройте наличните вградени инструменти и тяхното използване.
Отговор: web_search (информация в реално време), code_interpreter (изпълнение на Python), image_generation (създаване на изображения), document_library (въпроси и отговори върху Вашите файлове) – готови за употреба възможности, без нужда от внедряване.
4. Как работи многоагентна система с предаване на контрола?
Отговор: Насочващ агент (router) квалифицира заявката и я предава на компетентния специализиран агент; всеки агент остава прост, оркестрацията осигурява покритие – а предаванията се верижат в дълбочина.
5. Как осигурявате агентите в продукционна среда?
Отговор: С предпазни механизми за входове/изходи, строго ограничени инструменти, проследимост на действията и човешка валидация при решения с висок риск – автономността се извоюва чрез контрол.
Специализирани агенти, вградени инструменти, насочване, предпазни механизми: цялата архитектура се събира в четири думи – и този курс Ви накара да изградите всяка една от тях.