Архитектура на API за агенти на Mistral
На тази страница
Обновено на 3 ноември 2026 г. Предишният пълен пример за агент предаваше
guardrails={"enabled": True}, формат, който не съществува: официалният параметър е списък от конфигурацииmoderation_llm_v2. Входътtool.executionизлага името на инструмента вentry.name, а не вentry.tool_name, което преди това предизвиквашеAttributeError. Източници: Агенти и разговори · Модерация и защитни огради ·mistralaiSDK 3.7.0.
Трите фундаментални обекта
API за агенти на Mistral разчита на три взаимодействащи си обекта: Agent (Агент), Conversation (Разговор) и Entry (Запис). Повечето грешки в проектирането, срещани в началото на даден проект – създаване на нов агент за всяка заявка, повторно използване на изтекъл conversation_id или парсиране на отговор, което се срива при неочакван запис – произтичат от объркване между тези три нива. Разбирането на техните роли и взаимоотношения е предпоставка за написването дори на един ред код.
Обектът Agent
Агентът е набор от конфигурации, който дефинира поведението на модела. Той не съдържа данни за разговора: това е шаблон за многократна употреба, който създавате веднъж и към който могат да се препращат хиляди разговори.
Създаването изисква поне модел, име и описание.
agent = client.beta.agents.create(
model="mistral-large-latest", # LLM модел за използване
name="My Agent", # Идентификатор, четим от човек
description="Agent for financial analysis" # Описание, ориентирано към задачата
)
Параметърът model определя модела, който ще задвижва агента, избран от наличните модели за завършване на чатове като mistral-medium-latest или mistral-large-latest. name е идентификатор, четим от човек, който използвате, за да откривате и препращате към агента: в проект с двадесет такива, това е което Ви спасява от ровене в логовете, за да разберете кой отговаря на клиентите. description от своя страна е ориентирано към задачата и служи за повече от просто вътрешна документация – то помага на модела да разбере очакваната му роля, което обяснява формулировката „агент за финансов анализ“, вместо неясното „агент номер 3“.
Останалото се конфигурира по желание и точно тук се оформя истинската личност на агента.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Complete Agent",
description="Agent with all parameters",
instructions="You are a finance expert. Always respond with sources.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95},
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
"action": "block",
},
}
],
)
instructions— Системният промпт на агента (дефинира неговата личност, правила и стил)tools— Списък с налични инструменти:web_search,web_search_premium,code_interpreter,image_generation,document_libraryили персонализирани функцииcompletion_args— Параметри на семплера (температура, top_p, max_tokens и др.)guardrails— Списък с конфигурации за модерация (moderation_llm_v2), прилагани към входящото съобщение на всеки от разговорите на агента; тук пробивът на защитите (jailbreaking) се блокира над 0.2, а категориятаfinancialе деактивирана (праг1), тъй като агентът е създаден да обсъжда финанси. Подробности има в курса AI Модерация и сигурност с Mistral.
В горния пример финансовият агент наследява изискване за източници от своите инструкции, способност да проверява цифри чрез своите инструменти и ниска температура, която ограничава креативността там, където се очаква строгост.
Обектът Conversation
Разговорът (Conversation) е историята на взаимодействията между потребител и агент – или между потребител и самия модел. Той съдържа съобщения, резултати от изпълнение на инструменти и събития за предаване (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Извличане на ID на разговора за продължаване по-късно
conversation_id = response.conversation_id
Поведението на този обект крие няколко изненади. Разговорът е устойчив: историята се съхранява от страна на Mistral, освен ако не предадете store=False. Той е независим от агента, което означава, че един разговор може съвсем нормално да съществува без агент, в режим на директен модел. Накрая, той е неизменяем: всяко добавяне връща нов conversation_id, като старият остава достъпен. Последната точка е най-изненадваща: ако съхраните началното ID във вашата база данни и го използвате повторно при третия завой, ще се върнете към контекста на първия обмен.
Обектът Entry
Записът (Entry) е индивидуално действие в рамките на един разговор: атомната единица на историята. Когато получите отговор, полето outputs съдържа списък от записи, чийто тип зависи от това какво е направил агентът. Записът message.output носи текстов отговор от агента, т.е. текста, който Вашият интерфейс ще покаже. Записът tool.execution носи резултата от изпълнението на инструмент, като код или уеб търсене: стартираният скрипт и неговият изход, или страниците, върнати от двигателя. Записът agent.handoff сигнализира за събитие на предаване към друг агент и следователно се появява само в сценарии с множество агенти.
Един единствен отговор често смесва тези типове. Попитайте агент с инструменти да извърши изчисление и ще получите изпълнението, последвано от коментара, който го придружава: следователно Вашият код трябва да итерира през този списък, вместо да чете едно единствено поле.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Calculate the square root of 144"
)
for entry in response.outputs:
print(f"Type: {entry.type}")
if entry.type == "message.output":
print(f"Message: {entry.content}")
elif entry.type == "tool.execution":
print(f"Tool: {entry.name}")
Връзки между обектите
Следващата диаграма обобщава свързването на трите нива: конфигурация за многократна употреба, нишка на историята и единични действия.
Agent (configuration)
├── model, instructions, tools, guardrails
└── Can be referenced by N conversations
Conversation (history)
├── Linked to 0 or 1 Agent (optional)
├── Contains N ordered entries
└── Each append creates a new conversation_id
Entry (unit action)
├── message.output (text response)
├── tool.execution (tool result)
└── agent.handoff (agent transfer)
Опции за разговор
Стартирането на разговор приема настройки, които влияят както на Вашето съответствие с правилата, така и на Вашата архитектура, и е по-добре Вие да ги решите, отколкото да ги търпите. Първо, съхранението: store=False предотвратява всякакво запазване от страна на Mistral, което ще използвате за обработка на данни, които Вашата вътрешна политика забранява да напускат сървър на трета страна.
# Деактивиране на облачно съхранение
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
Втората настройка определя кой изпълнява предаванията (handoffs). В режим server, стойността по подразбиране, Mistral осъществява веригата от предавания между агенти без Ваша намеса; в режим client Вие получавате събития за предаване и запазвате контрола, за да ги регистрирате, филтрирате или отказвате.
# Режим Server (по подразбиране) — Mistral обработва предаванията автоматично
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Режим Client — Вие получавате събития за предаване и решавате какво да правите
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Ключови изводи
- Agent = конфигурация за многократна употреба (модел, инструкции, инструменти, защитни огради)
- Conversation = устойчива история, съхранявана на сървъра, независима от агента
- Entry = единично действие (съобщение, изпълнение на инструмент, предаване)
- Разговорите могат да съществуват без агент (режим на директен модел)
- Всяко добавяне към разговор създава нов
conversation_id - Режимът
store=Falseпредотвратява съхранението от страна на Mistral