Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Guardrails para Agentes Mistral

Aula 4 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Segurança de Agentes Autónomos
  2. Guardrails numa Conversa
  3. Guardrails num Agente
  4. Gestão de Bloqueios numa Troca de Vários Turnos
  5. Agentes com Ferramentas: O Que os Guardrails Não Veem
  6. Arquitetura Recomendada para Agentes em Produção
  7. Chat Completions, Conversa ou Agente: Resumo
  8. Pontos-chave

Lição reescrita em 3 de novembro de 2026. A versão anterior baseava-se num formato de guardrail fictício (enabled, categorias hate, violence, unpredictable), num método conversation.send() inexistente e afirmava incorretamente que os guardrails moderam argumentos de ferramentas. De acordo com a documentação, estes moderam apenas a entrada. O código segue agora a API de Conversas real (start, append) e foi verificado com os tipos do SDK mistralai versão 3.7.0. Fontes: Moderation & Guardrailing · Agents & Conversations · mistralai Python SDK.

Segurança de Agentes Autónomos

Um agente comporta mais riscos do que um simples chatbot: invoca ferramentas, navega na web e encadeia ações. Os guardrails cobrem apenas parte desta superfície de ataque — especificamente, a entrada. É exatamente por isso que precisa de saber exatamente onde os colocar e o que fica por cobrir.

Nesta lição, vai anexar guardrails a uma conversa e depois a um agente, gerir os seus bloqueios numa troca de vários turnos e ver o que deve adicionar para proteger as ferramentas.

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 numa Conversa

A API de Conversas mantém o histórico no servidor. Inicia com client.beta.conversations.start(), que aceita 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)

Prossegue depois com client.beta.conversations.append(). Este método não aceita o parâmetro guardrails no SDK 3.7.0, e a documentação não indica se os definidos no arranque se aplicam às mensagens subsequentes. Não baseie a sua segurança numa suposição: se cada turno deve ser filtrado, utilize um agente, cujos guardrails são herdados por todas as suas conversas.

Guardrails num Agente

Um agente Mistral é uma configuração registada: modelo, instruções, ferramentas e guardrails. A política de segurança torna-se um atributo do agente, e não uma convenção de codificação.

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}")

Note a consistência entre as instruções e os limiares: as instruções proíbem dar conselhos médicos ou jurídicos, e os limiares health e law bloqueiam pedidos deste tipo antes mesmo de o modelo os ler. As instruções persuadem; os guardrails restringem.

De acordo com a documentação, todas as conversas que utilizam este agente herdam os seus guardrails sem necessidade de os repetir:

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

Um pedido de conversa também pode substituir os guardrails do agente, passando os seus próprios guardrails para start(). Para alterar a política permanentemente, atualize o agente com client.beta.agents.update(agent_id=agent.id, guardrails=[...]).

Gestão de Bloqueios numa Troca de Vários Turnos

Uma mensagem bloqueada levanta errors.SDKError com o estado 403, e o corpo detalha as categorias violadas. Numa conversa, um bloqueio não destrói a troca: responde educadamente e o utilizador pode continuar.

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


def texto_resposta(resposta) -> str:
    """Texto da última mensagem do assistente numa resposta de conversa."""
    for entrada in reversed(resposta.outputs):
        if entrada.type == "message.output" and isinstance(entrada.content, str):
            return entrada.content
    return ""


def enviar(id_conversa: str, mensagem: str) -> str:
    """Adiciona uma mensagem a uma conversa e gere um bloqueio de guardrail."""
    try:
        resposta = client.beta.conversations.append(conversation_id=id_conversa, inputs=mensagem)
    except errors.SDKError as e:
        if e.status_code == 403:
            decisoes = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
            print("Bloqueado:", [nome for nome, d in decisoes.items() if d["violated"]])
            return MESSAGE_REFUS
        raise
    return texto_resposta(resposta)


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

Quando um pedido é aceite, a resposta da conversa também inclui um campo guardrails com pontuações para cada categoria (resposta.guardrails). Registe estes dados: indicam se os seus limiares estão bem calibrados.

Agentes com Ferramentas: O Que os Guardrails Não Veem

Um agente que invoca ferramentas abre uma segunda superfície de ataque: os argumentos que o modelo passa a essas ferramentas e os resultados que estas devolvem. Os guardrails moderam apenas a mensagem de entrada; não verificam nem esses argumentos nem esses resultados. O seu código deve fazê-lo.

agente_com_ferramentas = 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",
            },
        }
    ],
)

As funções declaradas desta forma são executadas no seu código: a API envia-lhe a chamada e os seus argumentos, você executa a função e devolve o resultado. É aqui que deve validar os argumentos antes de agir.

import re

FORMATO_ENCOMENDA = re.compile(r"CMD-\d{6}")
base_encomendas: dict[str, dict] = {}  # o seu acesso a dados


def pesquisar_encomenda(order_id: str, cliente_ligado: str) -> dict:
    """Executa a ferramenta após validar os seus argumentos."""
    if not FORMATO_ENCOMENDA.fullmatch(order_id):
        return {"error": "Invalid order number."}
    encomenda = base_encomendas.get(order_id)
    if encomenda is None or encomenda["client"] != cliente_ligado:
        return {"error": "Order not found."}  # nunca a encomenda de outro cliente
    return {"status": encomenda["status"]}

O controlo de acesso — neste caso, «a encomenda pertence ao cliente ligado?» — só pode vir da sua aplicação: nenhum classificador conhece os seus clientes. Para o texto que o agente devolve ao utilizador, adicione a moderação de saída da próxima lição.

Arquitetura Recomendada para Agentes em Produção

Em produção, envolva o agente numa classe que centralize o arranque da conversa, o envio de mensagens e a contagem de bloqueios. Um pico súbito de erros 403 sinaliza quer um ataque quer um limiar mal calibrado, e convém detetá-lo sem ter de vasculhar registos.

class AgenteSeguro:
    """Agente Mistral com rastreio de bloqueios de guardrail."""

    def __init__(self, cliente: Mistral, id_agente: str):
        self.cliente = cliente
        self.id_agente = id_agente
        self.bloqueios = 0

    def _bloqueado(self, e: errors.SDKError) -> dict:
        self.bloqueios += 1
        decisoes = json.loads(e.body)["guardrails"]["results"]["moderation_llm_v2"]["decisions"]
        return {
            "status": "blocked",
            "content": "Request blocked by security policy.",
            "categorias": [nome for nome, d in decisoes.items() if d["violated"]],
            "total_bloqueios": self.bloqueios,
        }

    def iniciar(self, mensagem: str) -> dict:
        """Inicia uma conversa com o agente."""
        try:
            resposta = self.cliente.beta.conversations.start(agent_id=self.id_agente, inputs=mensagem)
        except errors.SDKError as e:
            if e.status_code == 403:
                return self._bloqueado(e)
            raise
        return {
            "status": "ok",
            "conversation_id": resposta.conversation_id,
            "content": texto_resposta(resposta),
            "guardrails": resposta.guardrails,
        }

    def enviar(self, id_conversa: str, mensagem: str) -> dict:
        """Continua uma conversa existente."""
        try:
            resposta = self.cliente.beta.conversations.append(conversation_id=id_conversa, inputs=mensagem)
        except errors.SDKError as e:
            if e.status_code == 403:
                return self._bloqueado(e)
            raise
        return {"status": "ok", "content": texto_resposta(resposta), "guardrails": resposta.guardrails}

Chat Completions, Conversa ou Agente: Resumo

AspetoChat CompletionsConversaAgente
Onde os guardrails são declaradosEm cada chamadaconversations.start()agents.create() ou agents.update()
HerançaNenhumaNão documentado para append()Todas as conversas do agente
Pontuações na resposta (SDK 3.7.0)Não expostasresposta.guardrailsresposta.guardrails
FerramentasAs suas funçõesAs suas funçõesAs suas funções e ferramentas integradas
UtilizaçãoPrototipagemConversa pontualProdução

Pontos-chave

  • Uma conversa recebe os seus guardrails no arranque; append() não os aceita e a sua persistência entre turnos não está documentada
  • Um agente transmite os seus guardrails a todas as suas conversas; um pedido pode substituí-los
  • Um bloqueio levanta errors.SDKError (estado 403): responda educadamente, a conversa continua
  • Os guardrails não veem nem os argumentos das ferramentas nem os seus resultados: valide-os no seu código
  • Utilize o nível de agente em produção e adicione moderação de saída