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

Asegura los agentes con barreras de protección

Lección 17 de 18 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. La seguridad de los agentes no es opcional
  2. El parámetro guardrails
  3. Instrucciones: tu primera línea de defensa
  4. El principio de mínimo privilegio
  5. Filtra las transferencias
  6. No almacenes lo que no necesita ser almacenado
  7. Modera aguas arriba
  8. Ajusta la generación
  9. Antes de pasar a producción
  10. Puntos clave

Actualizado el 3 de noviembre de 2026. Ambos ejemplos anteriores pasaban guardrails={"enabled": True}, un formato que no existe: el parámetro oficial es una lista de configuraciones moderation_llm_v2, con un umbral por categoría. El texto también aclara lo que indica la documentación sobre su alcance: solo moderan el mensaje entrante. Fuentes: Moderation & Guardrailing · Agents & Conversations · SDK mistralai 3.7.0.

La seguridad de los agentes no es opcional

Un agente autónomo que utiliza herramientas, accede a internet y ejecuta código supone un riesgo si sus acciones no están restringidas. La diferencia respecto a una llamada de completado simple es fundamental, no solo una cuestión de grado: un modelo que produce texto puede corregirse tras una revisión, pero un agente que actúa ya ha actuado. Las barreras de protección (guardrails) son el conjunto de mecanismos que definen los límites de lo que un agente puede y no puede hacer. Ninguno de ellos es suficiente por sí solo; es su superposición en capas lo que proporciona la protección.

El parámetro guardrails

El primer nivel se declara al crear el agente.

from mistralai.client import Mistral
import os

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

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Secure Agent",
    description="Agent with guardrails enabled.",
    instructions="""You are a professional assistant.
- Never share personal information
- Never generate inappropriate content
- Refuse out-of-scope requests
- If in doubt, ask for clarification""",
    tools=[{"type": "web_search"}],
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {
                    "sexual": 0.1,
                    "hate_and_discrimination": 0.1,
                    "violence_and_threats": 0.2,
                    "criminal": 0.1,
                    "selfharm": 0.1,
                    "pii": 0.2,
                    "jailbreaking": 0.2,
                },
                "action": "block",
            },
        }
    ],
)

Cada categoría listada recibe un umbral de 0 a 1: más allá de este punto, el mensaje del usuario se rechaza con un error 403 antes de llegar al modelo, y block_on_error también rechaza la solicitud si la propia evaluación falla. Según la documentación, todas las conversaciones del agente heredan estas barreras de protección. Solo moderan la entrada: ni los resultados de la búsqueda web ni la respuesta del agente son comprobados por ellas.

El mismo parámetro se acepta a nivel de conversación, donde anula la configuración del agente. Esto permite endurecer temporalmente el comportamiento de un agente compartido sin necesidad de crear una segunda versión de dicho agente para un único caso de uso.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Analyze this confidential document.",
    guardrails=[  # replaces the agent's guardrails for this conversation
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {"pii": 0.05, "jailbreaking": 0.1},
                "action": "block",
            },
        }
    ],
)

Instrucciones: tu primera línea de defensa

El prompt del sistema sigue siendo la palanca más eficaz porque actúa antes de cualquier decisión del modelo. Un prompt de seguridad bien construido separa claramente el rol, el alcance, las prohibiciones y el formato esperado.

instructions = """## Role
You are a legal assistant specializing in French labor law.

## Scope
- ONLY French labor law
- Refuse any out-of-scope questions (tax, real estate, criminal law, etc.)

## Strict Prohibitions
- NEVER give definitive legal advice
- NEVER draft legal documents without a disclaimer
- NEVER share information about other clients
- ALWAYS mention that a lawyer must validate

## Format
- Cite relevant legal articles
- Clearly state the limits of your response
- Always propose consulting a professional"""

Observa lo que hace la sección “Scope”: no solo dice qué maneja el agente; nombra explícitamente los dominios adyacentes que debe rechazar. Sin esta enumeración, una pregunta fiscal relacionada con un despido podría colarse porque se parece lo suficiente al derecho laboral para que el modelo interactúe. La sección “Strict Prohibitions” sigue la misma lógica: formula rechazos, no recomendaciones. Un agente al que se le dice que sea “cauto” calibra su propia cautela; un agente al que se le prohíbe redactar sin un descargo de responsabilidad aplica una regla.

El principio de mínimo privilegio

Cada herramienta declarada es una capacidad que el agente puede movilizar en el momento equivocado. Compara estas dos configuraciones.

# Too many tools — large attack surface
dangerous_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="do-it-all-agent",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"},
        {"type": "image_generation"},
        {"type": "document_library", "library_ids": [lib.id]}
    ]
)

# Principle of least privilege — only what is necessary
secure_agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="documentation-agent",
    tools=[{"type": "document_library", "library_ids": [lib.id]}]
)

El segundo agente no puede salir a internet para buscar información que falte en tus documentos, ni ejecutar código sobre contenido que no hayas revisado. Esto no es una limitación que sufras; es la garantía de que sus respuestas provienen de tu base de conocimientos y de ningún otro lugar. Pregúntate herramienta por herramienta: si no encuentras un escenario en el que el agente la necesite, elimínala.

Filtra las transferencias

En un sistema multiagente, el modo cliente te da poder de veto sobre cada transferencia (handoff). Una lista blanca es suficiente para evitar que un agente llegue a otro a través de una ruta que no anticipaste.

response = client.beta.conversations.start(
    agent_id=router.id,
    inputs=user_query,
    handoff_execution="client"
)

ALLOWED_AGENTS = {research.id, analyst.id}  # Whitelist

for entry in response.outputs:
    if entry.type == "agent.handoff":
        if entry.next_agent_id not in ALLOWED_AGENTS:
            print(f"BLOCKED: unauthorized handoff to {entry.next_agent_id}")
            continue
        # Continue with the authorized agent

La lista blanca vive en tu código, no en la configuración del agente: sigue siendo válida incluso si alguien añade un destino de transferencia al enrutador sin notificártelo.

No almacenes lo que no necesita ser almacenado

Para datos sensibles, la mejor protección es no almacenar nada.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Confidential data: Q1 2026 financial report...",
    store=False  # Nothing persists
)

Este ajuste se decide por conversación, lo que te permite conservar el historial de intercambios ordinarios mientras procesas contenido confidencial en modo efímero.

Modera aguas arriba

Una variante elegante consiste en colocar un agente moderador a la cabeza de la cadena: examina la solicitud y solo la transfiere al especialista si es aceptable.

moderator = client.beta.agents.create(
    model="mistral-large-latest",
    name="moderator",
    description="Checks that requests are appropriate.",
    instructions="""Analyze the user request:
- If appropriate: transfer to the specialist
- If inappropriate: politely reply that the request is not supported
- If ambiguous: ask for clarification"""
)

specialist = client.beta.agents.create(
    model="mistral-large-latest",
    name="specialist",
    description="Handles validated requests.",
    tools=[{"type": "web_search"}]
)

moderator = client.beta.agents.update(
    agent_id=moderator.id,
    handoffs=[specialist.id]
)

El valor de este patrón reside en la separación de roles: el moderador no tiene herramientas y solo hace una cosa, por lo que una solicitud maliciosa que rechaza nunca llega al agente que sabe cómo actuar.

Ajusta la generación

Los parámetros de completado también contribuyen a la seguridad por una razón simple: una respuesta alucinada es un riesgo, y la creatividad es su caldo de cultivo.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Factual Agent",
    description="Factual and conservative agent.",
    completion_args={
        "temperature": 0.1,   # Very low creativity
        "top_p": 0.85,        # Restricted nucleus
        "max_tokens": 1024    # Short responses
    }
)

Una temperatura de 0,1 junto con un top_p de 0,85 deja muy poco margen al modelo: para una pregunta cuya respuesta aparece en tus documentos, la recupera en lugar de bordar una variante. El límite de 1024 tokens juega un papel similar, porque una respuesta que crece demasiado acaba desviándose del alcance documentado y produce relleno. Obviamente, estos ajustes no convienen a un agente creativo, pero son la configuración predeterminada para cualquier agente que deba exponer hechos: asistente legal, soporte técnico, experto en producto.

Antes de pasar a producción

Estos mecanismos solo son válidos cuando se superponen en capas, y la comprobación final se reduce a unas pocas verificaciones. Las instrucciones deben definir explícitamente el alcance y las prohibiciones, y el agente debe tener solo las herramientas estrictamente necesarias para su tarea. Verifica que las barreras de protección estén habilitadas y que los flujos de trabajo críticos se ejecuten en modo cliente para que ninguna transferencia se ejecute sin tu aprobación. Asegúrate de que store=False acompañe a cualquier conversación que implique datos sensibles y de que la temperatura se mantenga baja siempre que se espere que el agente se ciña a los hechos. Por último, coloca un agente moderador delante de la cadena para que las solicitudes inaceptables nunca lleguen a los agentes que saben cómo actuar.

Puntos clave

  • Las barreras de protección se configuran a nivel de agente y/o de conversación
  • Las instrucciones son tu primera línea de defensa: sé explícito con las prohibiciones
  • Aplica el principio de mínimo privilegio: proporciona solo las herramientas necesarias
  • El modo cliente te permite validar y bloquear transferencias no autorizadas
  • En producción: moderación aguas arriba, registro de actividad, lista blanca de agentes, store=False para datos sensibles