Ir al contenido principal
Español— Elegir un idioma
Menú

Barreras de seguridad para agentes de Mistral

Lección 4 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Asegurar agentes autónomos
  2. Barreras de seguridad en una conversación
  3. Barreras de seguridad en un agente
  4. Gestión de bloqueos en un intercambio de varios turnos
  5. Agentes con herramientas: lo que las barreras no ven
  6. Arquitectura recomendada para agentes en producción
  7. Chat Completions, Conversación o Agente: Resumen
  8. 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ías hate, violence, unpredictable), un método conversation.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 SDK mistralai versió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

AspectoChat CompletionsConversaciónAgente
Dónde se declaran las barrerasEn cada llamadaconversations.start()agents.create() o agents.update()
HerenciaNingunaNo documentado para append()Todas las conversaciones del agente
Puntuaciones en la respuesta (SDK 3.7.0)No expuestasrespuesta.guardrailsrespuesta.guardrails
HerramientasTus funcionesTus funcionesTus funciones y herramientas integradas
UsoPrototipadoConversación puntualProducció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 (estado 403): 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