Proteger agentes com guardrails
Nesta página
Atualizado em 3 de novembro de 2026. Ambos os exemplos anteriores passavam
guardrails={"enabled": True}, um formato que não existe: o parâmetro oficial é uma lista de configuraçõesmoderation_llm_v2, com um limiar por categoria. O texto também esclarece o que a documentação afirma sobre o seu âmbito: apenas moderam a mensagem de entrada. Fontes: Moderation & Guardrailing · Agents & Conversations · SDKmistralai3.7.0.
A segurança do agente não é opcional
Um agente autónomo que utiliza ferramentas, acede à internet e executa código representa um risco se as suas ações não forem restringidas. A diferença face a uma chamada de completamento simples é fundamental, não sendo apenas uma questão de grau: um modelo que produz texto pode ser corrigido após revisão, mas um agente que age já agiu. Os guardrails são o conjunto de mecanismos que definem os limites do que um agente pode e não pode fazer. Nenhum deles é suficiente por si só; é a sua sobreposição em camadas que garante a proteção.
O parâmetro guardrails
O primeiro nível é declarado aquando da criação do 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 categoria listada recebe um limiar de 0 a 1: para além deste ponto, a mensagem do utilizador é rejeitada com um erro 403 antes de chegar ao modelo, e block_on_error também rejeita o pedido se a própria avaliação falhar. De acordo com a documentação, todas as conversas para o agente herdam estes guardrails. Estes apenas moderam a entrada: nem os resultados da pesquisa na web nem a resposta do agente são verificados por eles.
O mesmo parâmetro é aceite ao nível da conversa, onde substitui a configuração do agente. Isto permite-lhe apertar temporariamente o comportamento de um agente partilhado sem criar uma segunda versão desse agente para um ú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",
},
}
],
)
Instruções: a sua primeira linha de defesa
O prompt do sistema continua a ser a alavanca mais eficaz porque atua antes de qualquer decisão do modelo. Um prompt de segurança bem construído separa claramente a função, o âmbito, as proibições e o 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"""
Observe o que a secção “Scope” faz: não diz apenas com o que o agente lida; nomeia explicitamente os domínios adjacentes que deve recusar. Sem esta enumeração, uma questão fiscal relacionada com um despedimento pode passar despercebida porque se assemelha o suficiente ao direito do trabalho para que o modelo engage. A secção “Strict Prohibitions” segue a mesma lógica: formula recusas, não recomendações. Um agente instruído a ser “cauteloso” calibra a sua própria cautela; um agente proibido de redigir sem um aviso prévio aplica uma regra.
O princípio do privilégio mínimo
Cada ferramenta declarada é uma capacidade que o agente pode mobilizar no momento errado. Compare estas duas configurações.
# 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]}]
)
O segundo agente não pode ir à internet buscar informações em falta nos seus documentos, nem executar código sobre conteúdo que não tenha revisto. Isto não é uma limitação que sofre; é a garantia de que as suas respostas provêm da sua base de conhecimento e de mais lado nenhum. Questione-se ferramenta por ferramenta — se não conseguir encontrar um cenário em que o agente precise dela, remova-a.
Filtrar as transferências (handoffs)
Num sistema multi-agente, o modo cliente dá-lhe poder de veto sobre cada transferência. Uma lista branca é suficiente para impedir que um agente alcance outro através de um caminho que não antecipou.
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
A lista branca reside no seu código, não na configuração do agente: permanece válida mesmo que alguém adicione um alvo de transferência ao router sem o notificar.
Não guarde o que não precisa de ser guardado
Para dados sensíveis, a melhor proteção é não guardar nada.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Confidential data: Q1 2026 financial report...",
store=False # Nothing persists
)
Esta definição é decidida por conversa, o que lhe permite reter o histórico de trocas ordinárias enquanto processa conteúdo confidencial em modo efémero.
Moderar a montante
Uma variante elegante consiste em colocar um agente de moderação no início da cadeia: este examina o pedido e só o transfere para o especialista se for aceitável.
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]
)
O valor deste padrão reside na separação de funções: o moderador não tem ferramentas e faz apenas uma coisa, pelo que um pedido malicioso que rejeite nunca chega ao agente que sabe agir.
Ajustar a geração
Os parâmetros de completamento também contribuem para a segurança por uma razão simples: uma resposta alucinada é um risco, e a criatividade é o seu terreno fértil.
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
}
)
Uma temperatura de 0,1 emparelhada com um top_p de 0,85 deixa muito pouca latitude ao modelo: para uma pergunta cuja resposta aparece nos seus documentos, ele recupera-a em vez de bordar uma variante. O limite de 1024 tokens desempenha um papel semelhante, porque uma resposta que cresce demasiado acaba por se desviar do âmbito documentado e produz enchimento. Estas definições obviamente não servem um agente criativo, mas são a configuração padrão para qualquer agente esperado para enunciar factos — assistente jurídico, suporte técnico, especialista de produto.
Antes de ir para produção
Estes mecanismos só são válidos quando sobrepostos em camadas, e a verificação final resume-se a algumas verificações. As instruções devem definir explicitamente o âmbito e as proibições, e o agente deve ter apenas as ferramentas estritamente necessárias para a sua tarefa. Verifique se os guardrails estão ativados e se os fluxos de trabalho críticos são executados em modo cliente, para que nenhuma transferência seja executada sem a sua aprovação. Garanta que store=False acompanha qualquer conversa envolvendo dados sensíveis e que a temperatura permanece baixa sempre que se espera que o agente se mantenha factual. Por fim, coloque um agente de moderação à frente da cadeia para que pedidos inaceitáveis nunca cheguem aos agentes que sabem agir.
Pontos-chave
- Os guardrails são configurados ao nível do agente e/ou da conversa
- As instruções são a sua primeira linha de defesa — seja explícito sobre as proibições
- Aplique o princípio do privilégio mínimo: dê apenas as ferramentas necessárias
- O modo cliente permite-lhe validar e bloquear transferências não autorizadas
- Em produção: moderação a montante, registo (logging), lista branca de agentes, store=False para dados sensíveis