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

Guardrails за агенти на Mistral

Урок 4 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Осигуряване на автономни агенти
  2. Guardrails в разговор (Conversation)
  3. Guardrails в агент
  4. Обработка на блокирания в многократен обмен
  5. Агенти с инструменти: Какво не виждат Guardrails
  6. Препоръчителна архитектура за агенти в продукция
  7. Chat Completions, Conversation или Agent: Обобщение
  8. Ключови изводи

Урокът е пренаписан на 3 ноември 2026 г. Предишната версия разчиташе на фиктивен формат за guardrails (enabled, категории hate, violence, unpredictable), несъществуващ метод conversation.send() и твърдеше погрешно, че guardrails модерират аргументите на инструментите. Според документацията те модерират само входните данни. Кодът сега следва реалния Conversations API (start, append) и е верифициран спрямо типовете на SDK mistralai версия 3.7.0. Източници: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.

Осигуряване на автономни агенти

Един агент носи по-голям риск от обикновен чатбот: той извиква инструменти, сърфира в уеб и свързва действия във верига. Guardrails покриват само част от тази повърхност на атака – конкретно, входните данни. Точно затова трябва да знаете точно къде да ги разположите и какво оставят без покритие.

В този урок ще прикрепите guardrails към разговор, след това към агент, ще обработите техните блокирания в многократен обмен и ще видите какво трябва да добавите, за да обезопасите инструментите.

import json
import os

from mistralai.client import Mistral, errors
from mistralai.client.models import GuardrailConfigTypedDict

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Guardrails в разговор (Conversation)

Conversations API съхранява историята на сървъра. Започвате с client.beta.conversations.start(), който приема параметъра guardrails:

GUARDRAILS_RH: list[GuardrailConfigTypedDict] = [
    {
        "block_on_error": True,
        "moderation_llm_v2": {
            "custom_category_thresholds": {
                "sexual": 0.1,
                "hate_and_discrimination": 0.1,
                "violence_and_threats": 0.2,
                "pii": 0.15,
                "jailbreaking": 0.1,
            },
            "action": "block",
        },
    }
]

conversation = client.beta.conversations.start(
    model="mistral-large-latest",
    instructions="You are a professional HR assistant.",
    inputs="What leave options are available?",
    guardrails=GUARDRAILS_RH,
)
print(conversation.conversation_id)

След това продължавате с client.beta.conversations.append(). Този метод не приема параметър guardrails в SDK 3.7.0, а документацията не уточнява дали тези, предадени при стартиране, важат за последващите съобщения. Не изграждайте сигурността си върху предположения: ако всяка стъпка трябва да бъде филтрирана, използвайте агент, чиито guardrails се наследяват от всичките му разговори.

Guardrails в агент

Агентът на Mistral е регистрирана конфигурация: модел, инструкции, инструменти и guardrails. Политиката за сигурност става атрибут на агента, а не просто конвенция за кодиране.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Customer Support Agent",
    description="Secure customer support agent",
    instructions=(
        "You are a customer support agent. Strict rules: "
        "never disclose personal information; "
        "do not give medical or legal advice; "
        "redirect to a human if the topic is sensitive."
    ),
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {
                    "sexual": 0.1,
                    "hate_and_discrimination": 0.1,
                    "violence_and_threats": 0.15,
                    "dangerous": 0.1,
                    "criminal": 0.1,
                    "selfharm": 0.1,
                    "health": 0.3,
                    "financial": 0.3,
                    "law": 0.3,
                    "pii": 0.15,
                    "jailbreaking": 0.1,
                },
                "action": "block",
            },
        }
    ],
)
print(f"Agent created: {agent.id}")

Обърнете внимание на съгласуваността между инструкциите и праговете: инструкциите забраняват даването на медицински или правни съвети, а праговете health и law блокират заявки от този тип, преди моделът дори да ги прочете. Инструкциите убеждават; guardrails ограничават.

Според документацията, всички разговори, използващи този агент, наследяват неговите guardrails без нужда от повторното им задаване:

conv = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="How can I return a product?",
)

Заявката за разговор може също да замести guardrails на агента, като предаде свои собствени guardrails към start(). За да промените политиката постоянно, актуализирайте агента с client.beta.agents.update(agent_id=agent.id, guardrails=[...]).

Обработка на блокирания в многократен обмен

Блокирано съобщение поражда errors.SDKError със статус 403, а тялото на грешката детайлизира нарушените категории. В рамките на разговор блокирането не унищожава обмена: отговаряте учтиво и потребителят може да продължи.

MESSAGE_REFUS = "I cannot process this request. It violates our security policy."


def texte_reponse(reponse) -> str:
    """Text of the last assistant message in a conversation response."""
    for entree in reversed(reponse.outputs):
        if entree.type == "message.output" and isinstance(entree.content, str):
            return entree.content
    return ""


def envoyer(conversation_id: str, message: str) -> str:
    """Adds a message to a conversation and handles a guardrail block."""
    try:
        reponse = client.beta.conversations.append(conversation_id=conversation_id, inputs=message)
    except errors.SDKError as e:
        if e.status_code == 403:
            decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            print("Blocked:", [nom for nom, d in decisions.items() if d["violated"]])
            return MESSAGE_REFUS
        raise
    return texte_reponse(reponse)


print(envoyer(conv.conversation_id, "Give me the personal addresses of employees"))

Когато заявката премине успешно, отговорът на разговора също носи поле guardrails с резултати за всяка категория (reponse.guardrails). Регистрирайте ги: те Ви показват дали праговете Ви са настроени правилно.

Агенти с инструменти: Какво не виждат Guardrails

Агент, който извиква инструменти, отваря втора повърхност на атака: аргументите, които моделът предава на тези инструменти, и резултатите, които те връщат. Guardrails модерират само входящото съобщение; те не проверяват нито тези аргументи, нито тези резултати. Вашият код трябва да направи това.

agent_avec_outils = client.beta.agents.create(
    model="mistral-large-latest",
    name="Support Agent with Tools",
    instructions="Support assistant with access to commands.",
    tools=[
        {
            "type": "function",
            "function": {
                "name": "rechercher_commande",
                "description": "Searches for an order by its number",
                "parameters": {
                    "type": "object",
                    "properties": {"order_id": {"type": "string", "description": "Order number"}},
                    "required": ["order_id"],
                },
            },
        }
    ],
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {"pii": 0.15, "jailbreaking": 0.1, "criminal": 0.1},
                "action": "block",
            },
        }
    ],
)

Функциите, декларирани по този начин, се изпълняват във Вашия код: API Ви изпраща извикването и неговите аргументи, Вие изпълнявате функцията и връщате резултата. Тук трябва да валидирате аргументите, преди да действате.

import re

FORMAT_COMMANDE = re.compile(r"CMD-\d{6}")
base_commandes: dict[str, dict] = {}  # your data access


def rechercher_commande(order_id: str, client_connecte: str) -> dict:
    """Executes the tool after validating its arguments."""
    if not FORMAT_COMMANDE.fullmatch(order_id):
        return {"error": "Invalid order number."}
    commande = base_commandes.get(order_id)
    if commande is None or commande["client"] != client_connecte:
        return {"error": "Order not found."}  # never another client's order
    return {"status": commande["status"]}

Контролът на достъпа – тук „принадлежи ли поръчката на свързания клиент?“ – може да дойде само от Вашето приложение: никой класификатор не познава Вашите клиенти. За текста, който агентът връща на потребителя, добавете изходна модерация от следващия урок.

Препоръчителна архитектура за агенти в продукция

В производствена среда обвийте агента в клас, който централизира стартирането на разговора, изпращането на съобщения и броенето на блокиранията. Внезапен скок в 403 сигнализира или за атака, или за лошо калибриран праг, и Вие искате да видите това без да ровите в логовете.

class AgentSecurise:
    """Mistral Agent with guardrail block tracking."""

    def __init__(self, client: Mistral, agent_id: str):
        self.client = client
        self.agent_id = agent_id
        self.blocages = 0

    def _bloque(self, e: errors.SDKError) -> dict:
        self.blocages += 1
        decisions = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
        return {
            "status": "blocked",
            "content": "Request blocked by security policy.",
            "categories": [nom for nom, d in decisions.items() if d["violated"]],
            "blocages_total": self.blocages,
        }

    def demarrer(self, message: str) -> dict:
        """Starts a conversation with the agent."""
        try:
            reponse = self.client.beta.conversations.start(agent_id=self.agent_id, inputs=message)
        except errors.SDKError as e:
            if e.status_code == 403:
                return self._bloque(e)
            raise
        return {
            "status": "ok",
            "conversation_id": reponse.conversation_id,
            "content": texte_reponse(reponse),
            "guardrails": reponse.guardrails,
        }

    def envoyer(self, conversation_id: str, message: str) -> dict:
        """Continues an existing conversation."""
        try:
            reponse = self.client.beta.conversations.append(conversation_id=conversation_id, inputs=message)
        except errors.SDKError as e:
            if e.status_code == 403:
                return self._bloque(e)
            raise
        return {"status": "ok", "content": texte_reponse(reponse), "guardrails": reponse.guardrails}

Chat Completions, Conversation или Agent: Обобщение

АспектChat CompletionsConversationAgent
Къде се декларират guardrailsПри всяко извикванеconversations.start()agents.create() или agents.update()
НаследяванеНямаНе е документирано за append()Всички разговори на агента
Резултати в отговора (SDK 3.7.0)Не са достъпниreponse.guardrailsreponse.guardrails
ИнструментиВашите функцииВашите функцииВашите функции и вградени инструменти
УпотребаПрототипиранеЕдиничен разговорПродукция

Ключови изводи

  • Разговорът получава своите guardrails при стартиране; append() не ги приема, а тяхното запазване между стъпките не е документирано
  • Агентът предава своите guardrails на всичките си разговори; заявката може да ги замени
  • Блокирането поражда errors.SDKError (статус 403): отговорете учтиво, разговорът продължава
  • Guardrails не виждат нито аргументите на инструментите, нито техните резултати: валидирайте ги във Вашия код
  • Използвайте нивото агент в продукция и добавете изходна модерация