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

Proteger agentes com guardrails

Aula 17 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A segurança do agente não é opcional
  2. O parâmetro guardrails
  3. Instruções: a sua primeira linha de defesa
  4. O princípio do privilégio mínimo
  5. Filtrar as transferências (handoffs)
  6. Não guarde o que não precisa de ser guardado
  7. Moderar a montante
  8. Ajustar a geração
  9. Antes de ir para produção
  10. Pontos-chave

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ções moderation_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 · SDK mistralai 3.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