Barreras de seguridad para agentes de Mistral
En esta página
- Asegurar agentes autónomos
- Barreras de seguridad en una conversación
- Barreras de seguridad en un agente
- Gestión de bloqueos en un intercambio de varios turnos
- Agentes con herramientas: lo que las barreras no ven
- Arquitectura recomendada para agentes en producción
- Chat Completions, Conversación o Agente: Resumen
- Puntos clave
Lección reescrita el 3 de noviembre de 2026. La versión anterior se basaba en un formato de barrera de seguridad ficticio (
enabled, categoríashate,violence,unpredictable), un métodoconversation.send()inexistente y afirmaba incorrectamente que las barreras moderan los argumentos de las herramientas. Según la documentación, estas moderan únicamente la entrada. El código sigue ahora la API de Conversaciones real (start,append) y ha sido verificado con los tipos del SDKmistralaiversión 3.7.0. Fuentes: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.
Asegurar agentes autónomos
Un agente conlleva más riesgo que un chatbot sencillo: llama a herramientas, navega por la web y encadena acciones. Las barreras de seguridad cubren solo parte de esta superficie de ataque: concretamente, la entrada. Esta es exactamente la razón por la que debes saber con precisión dónde colocarlas y qué queda fuera de su alcance.
En esta lección, adjuntarás barreras de seguridad a una conversación y luego a un agente, gestionarás sus bloqueos en un intercambio de varios turnos y verás qué debes añadir para asegurar las herramientas.
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"])
Barreras de seguridad en una conversación
La API de Conversaciones mantiene el historial en el servidor. Comienzas con client.beta.conversations.start(), que acepta 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="Eres un asistente profesional de recursos humanos.",
inputs="¿Qué opciones de excedencia están disponibles?",
guardrails=GUARDRAILS_RH,
)
print(conversation.conversation_id)
A continuación, continúas con client.beta.conversations.append(). Este método no acepta un parámetro guardrails en el SDK 3.7.0, y la documentación no indica si las configuradas al inicio se aplican a los mensajes posteriores. No bases tu seguridad en una suposición: si cada turno debe filtrarse, utiliza un agente, cuyas barreras de seguridad se heredan en todas sus conversaciones.
Barreras de seguridad en un agente
Un agente de Mistral es una configuración registrada: modelo, instrucciones, herramientas y barreras de seguridad. La política de seguridad se convierte en un atributo del agente en lugar de una convención de codificación.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Agente de Atención al Cliente",
description="Agente seguro de atención al cliente",
instructions=(
"Eres un agente de atención al cliente. Reglas estrictas: "
"nunca reveles información personal; "
"no des consejos médicos ni legales; "
"deriva a un humano si el tema es sensible."
),
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"Agente creado: {agent.id}")
Observa la coherencia entre las instrucciones y los umbrales: las instrucciones prohíben dar consejos médicos o legales, y los umbrales health y law bloquean solicitudes de este tipo antes de que el modelo siquiera las lea. Las instrucciones persuaden; las barreras de seguridad restringen.
Según la documentación, todas las conversaciones que utilizan este agente heredan sus barreras de seguridad sin necesidad de repetirlas:
conv = client.beta.conversations.start(
agent_id=agent.id,
inputs="¿Cómo puedo devolver un producto?",
)
Una solicitud de conversación también puede anular las barreras de seguridad del agente pasando sus propias guardrails a start(). Para cambiar la política de forma permanente, actualiza el agente con client.beta.agents.update(agent_id=agent.id, guardrails=[...]).
Gestión de bloqueos en un intercambio de varios turnos
Un mensaje bloqueado lanza un errors.SDKError con el estado 403, y el cuerpo detalla las categorías infringidas. En una conversación, un bloqueo no destruye el intercambio: respondes con educación y el usuario puede continuar.
MESSAGE_REFUS = "No puedo procesar esta solicitud. Infringe nuestra política de seguridad."
def texto_respuesta(respuesta) -> str:
"""Texto del último mensaje del asistente en una respuesta de conversación."""
for entrada in reversed(respuesta.outputs):
if entrada.type == "message.output" and isinstance(entrada.content, str):
return entrada.content
return ""
def enviar(id_conversacion: str, mensaje: str) -> str:
"""Añade un mensaje a una conversación y gestiona un bloqueo de barrera de seguridad."""
try:
respuesta = client.beta.conversations.append(conversation_id=id_conversacion, inputs=mensaje)
except errors.SDKError as e:
if e.status_code == 403:
decisiones = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
print("Bloqueado:", [nombre for nombre, d in decisiones.items() if d["violated"]])
return MESSAGE_REFUS
raise
return texto_respuesta(respuesta)
print(enviar(conv.conversation_id, "Dame las direcciones personales de los empleados"))
Cuando una solicitud pasa, la respuesta de la conversación también lleva un campo guardrails con puntuaciones para cada categoría (respuesta.guardrails). Registra estos datos: te indican si tus umbrales están bien ajustados.
Agentes con herramientas: lo que las barreras no ven
Un agente que llama a herramientas abre una segunda superficie de ataque: los argumentos que el modelo pasa a dichas herramientas y los resultados que estas devuelven. Las barreras de seguridad moderan solo el mensaje entrante; no comprueban ni estos argumentos ni estos resultados. Tu código debe hacerlo.
agente_con_herramientas = client.beta.agents.create(
model="mistral-large-latest",
name="Agente de Soporte con Herramientas",
instructions="Asistente de soporte con acceso a comandos.",
tools=[
{
"type": "function",
"function": {
"name": "buscar_pedido",
"description": "Busca un pedido por su número",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string", "description": "Número de pedido"}},
"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",
},
}
],
)
Las funciones declaradas de esta manera se ejecutan en tu código: la API te envía la llamada y sus argumentos, tú ejecutas la función y devuelves su resultado. Aquí es donde debes validar los argumentos antes de actuar.
import re
FORMATO_PEDIDO = re.compile(r"CMD-\d{6}")
base_pedidos: dict[str, dict] = {} # tu acceso a datos
def buscar_pedido(order_id: str, cliente_conectado: str) -> dict:
"""Ejecuta la herramienta tras validar sus argumentos."""
if not FORMATO_PEDIDO.fullmatch(order_id):
return {"error": "Número de pedido no válido."}
pedido = base_pedidos.get(order_id)
if pedido is None or pedido["cliente"] != cliente_conectado:
return {"error": "Pedido no encontrado."} # nunca el pedido de otro cliente
return {"status": pedido["status"]}
El control de acceso —en este caso, «¿pertenece el pedido al cliente conectado?»— solo puede proceder de tu aplicación: ningún clasificador conoce a tus clientes. Para el texto que el agente devuelve al usuario, añade la moderación de salida que verás en la próxima lección.
Arquitectura recomendada para agentes en producción
En producción, envuelve el agente en una clase que centralice el inicio de la conversación, el envío de mensajes y el recuento de bloqueos. Un pico repentino de errores 403 señala ya sea un ataque o un umbral mal calibrado, y querrás detectarlo sin tener que rebuscar en los registros.
class AgenteSeguro:
"""Agente de Mistral con seguimiento de bloqueos de barreras de seguridad."""
def __init__(self, cliente: Mistral, id_agente: str):
self.cliente = cliente
self.id_agente = id_agente
self.bloqueos = 0
def _bloqueado(self, e: errors.SDKError) -> dict:
self.bloqueos += 1
decisiones = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
return {
"status": "blocked",
"content": "Solicitud bloqueada por la política de seguridad.",
"categorias": [nombre for nombre, d in decisiones.items() if d["violated"]],
"bloqueos_total": self.bloqueos,
}
def iniciar(self, mensaje: str) -> dict:
"""Inicia una conversación con el agente."""
try:
respuesta = self.cliente.beta.conversations.start(agent_id=self.id_agente, inputs=mensaje)
except errors.SDKError as e:
if e.status_code == 403:
return self._bloqueado(e)
raise
return {
"status": "ok",
"conversation_id": respuesta.conversation_id,
"content": texto_respuesta(respuesta),
"guardrails": respuesta.guardrails,
}
def enviar(self, id_conversacion: str, mensaje: str) -> dict:
"""Continúa una conversación existente."""
try:
respuesta = self.cliente.beta.conversations.append(conversation_id=id_conversacion, inputs=mensaje)
except errors.SDKError as e:
if e.status_code == 403:
return self._bloqueado(e)
raise
return {"status": "ok", "content": texto_respuesta(respuesta), "guardrails": respuesta.guardrails}
Chat Completions, Conversación o Agente: Resumen
| Aspecto | Chat Completions | Conversación | Agente |
|---|---|---|---|
| Dónde se declaran las barreras | En cada llamada | conversations.start() | agents.create() o agents.update() |
| Herencia | Ninguna | No documentado para append() | Todas las conversaciones del agente |
| Puntuaciones en la respuesta (SDK 3.7.0) | No expuestas | respuesta.guardrails | respuesta.guardrails |
| Herramientas | Tus funciones | Tus funciones | Tus funciones y herramientas integradas |
| Uso | Prototipado | Conversación puntual | Producción |
Puntos clave
- Una conversación recibe sus barreras de seguridad al inicio;
append()no las acepta y su persistencia entre turnos no está documentada - Un agente pasa sus barreras de seguridad a todas sus conversaciones; una solicitud puede anularlas
- Un bloqueo lanza un
errors.SDKError(estado403): responde con educación, la conversación continúa - Las barreras no ven ni los argumentos de las herramientas ni sus resultados: valídalos en tu código
- Utiliza el nivel de agente en producción y añade moderación de salida