Guardrails за агенти на Mistral
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия разчиташе на фиктивен формат за guardrails (
enabled, категорииhate,violence,unpredictable), несъществуващ методconversation.send()и твърдеше погрешно, че guardrails модерират аргументите на инструментите. Според документацията те модерират само входните данни. Кодът сега следва реалния Conversations API (start,append) и е верифициран спрямо типовете на SDKmistralaiверсия 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 Completions | Conversation | Agent |
|---|---|---|---|
| Къде се декларират guardrails | При всяко извикване | conversations.start() | agents.create() или agents.update() |
| Наследяване | Няма | Не е документирано за append() | Всички разговори на агента |
| Резултати в отговора (SDK 3.7.0) | Не са достъпни | reponse.guardrails | reponse.guardrails |
| Инструменти | Вашите функции | Вашите функции | Вашите функции и вградени инструменти |
| Употреба | Прототипиране | Единичен разговор | Продукция |
Ключови изводи
- Разговорът получава своите guardrails при стартиране;
append()не ги приема, а тяхното запазване между стъпките не е документирано - Агентът предава своите guardrails на всичките си разговори; заявката може да ги замени
- Блокирането поражда
errors.SDKError(статус403): отговорете учтиво, разговорът продължава - Guardrails не виждат нито аргументите на инструментите, нито техните резултати: валидирайте ги във Вашия код
- Използвайте нивото агент в продукция и добавете изходна модерация