Guardrails para Agentes Mistral
Nesta página
Lição reescrita em 3 de novembro de 2026. A versão anterior baseava-se num formato de guardrail fictício (
enabled, categoriashate,violence,unpredictable), num métodoconversation.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 SDKmistralaiversã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
| Aspeto | Chat Completions | Conversa | Agente |
|---|---|---|---|
| Onde os guardrails são declarados | Em cada chamada | conversations.start() | agents.create() ou agents.update() |
| Herança | Nenhuma | Não documentado para append() | Todas as conversas do agente |
| Pontuações na resposta (SDK 3.7.0) | Não expostas | resposta.guardrails | resposta.guardrails |
| Ferramentas | As suas funções | As suas funções | As suas funções e ferramentas integradas |
| Utilização | Prototipagem | Conversa pontual | Produçã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(estado403): 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