Премини към основното съдържание
Български— Изберете език
Меню

Архитектура на API за агенти на Mistral

Урок 3 от 18 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Трите фундаментални обекта
  2. Обектът Agent
  3. Обектът Conversation
  4. Обектът Entry
  5. Връзки между обектите
  6. Опции за разговор
  7. Ключови изводи

Обновено на 3 ноември 2026 г. Предишният пълен пример за агент предаваше guardrails={"enabled": True}, формат, който не съществува: официалният параметър е списък от конфигурации moderation_llm_v2. Входът tool.execution излага името на инструмента в entry.name, а не в entry.tool_name, което преди това предизвикваше AttributeError. Източници: Агенти и разговори · Модерация и защитни огради · mistralai SDK 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