Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Guardrail: convalida di input e output

Lezione 6 di 14 Aggiornata il 28 luglio 2026 Avanzato
In questa pagina
  1. Cos’è un guardrail?
  2. Un’architettura a pipeline
  3. Tre tipici guardrail
  4. Assemblaggio completo
  5. Quando la regola non può essere scritta in regex
  6. Punti chiave

Cos’è un guardrail?

Un guardrail è un livello di convalida posizionato tra l’utente e il modello in ingresso, o tra il modello e l’utente in uscita. La distinzione rispetto alla moderazione trattata nel capitolo precedente è netta e devi mantenerla: la moderazione risponde alla domanda «Questo contenuto è offensivo?», una questione universale la cui risposta non dipende dal tuo business. I guardrail rispondono a domande che solo tu puoi formulare: il messaggio rientra nell’ambito previsto? La risposta contiene informazioni vietate? L’azione richiesta è autorizzata per questo ruolo? Un assistente bancario e un assistente di libreria condividono la stessa moderazione, ma non hanno alcun guardrail in comune.

Entro il 2026, i guardrail sono diventati un componente standard delle architetture degli agenti AI, indispensabili ogni volta che un modello ha accesso a strumenti o dati sensibili.

Un’architettura a pipeline

La scelta strutturale consiste nel trattare ogni guardrail come un oggetto indipendente con una singola responsabilità, per poi concatenarli in un ordine definito. Il vantaggio emerge durante la manutenzione: aggiungere una regola di business non richiede modifiche al codice esistente e una regola che genera troppo rumore può essere rimossa in una singola riga.

Un terzo verdetto si affianca ad «allow» e «block»: «modify». Questo cambia la natura dell’esercizio. Molte situazioni reali non giustificano un rifiuto: una risposta contenente un percorso interno del server rimane utile una volta mascherato tale percorso. Il blocco farebbe perdere l’informazione; la modifica la preserva rimuovendo ciò che pone problemi.

from dataclasses import dataclass
from enum import Enum

class Decision(Enum):
    ALLOW = "allow"
    BLOCK = "block"
    MODIFY = "modify"

@dataclass
class ValidationResult:
    decision: Decision
    reason: str
    modified_content: str | None = None

class Guardrail:
    """Base class for a guardrail."""

    def validate(self, content: str, context: dict) -> ValidationResult:
        raise NotImplementedError

class GuardrailPipeline:
    """Chains multiple guardrails in sequence."""

    def __init__(self):
        self.input_guardrails: list[Guardrail] = []
        self.output_guardrails: list[Guardrail] = []

    def add_input(self, guardrail: Guardrail):
        self.input_guardrails.append(guardrail)

    def add_output(self, guardrail: Guardrail):
        self.output_guardrails.append(guardrail)

    def validate_input(self, message: str, context: dict) -> ValidationResult:
        for g in self.input_guardrails:
            result = g.validate(message, context)
            if result.decision == Decision.BLOCK:
                return result
            if result.decision == Decision.MODIFY:
                message = result.modified_content
        return ValidationResult(Decision.ALLOW, "All validations passed")

    def validate_output(self, response: str, context: dict) -> ValidationResult:
        for g in self.output_guardrails:
            result = g.validate(response, context)
            if result.decision == Decision.BLOCK:
                return result
            if result.decision == Decision.MODIFY:
                response = result.modified_content
        return ValidationResult(Decision.ALLOW, "OK", response)

Tre tipici guardrail

Il guardrail di ambito mantiene la conversazione entro il suo dominio. Serve sia alla sicurezza che alla reputazione: un assistente al servizio clienti addestrato a rispondere a domande sulle consegne non ha nulla da guadagnare commentando notizie politiche, e uno screenshot di tale risposta circola rapidamente. L’elenco degli argomenti vietati deve essere discusso con la parte commerciale, mai redatto esclusivamente dal team tecnico.

class ScopeGuardrail(Guardrail):
    """Checks that the message stays within the authorized scope."""

    def __init__(self, allowed_topics: list[str], forbidden_topics: list[str]):
        self.allowed_topics = allowed_topics
        self.forbidden_topics = forbidden_topics

    def validate(self, content: str, context: dict) -> ValidationResult:
        content_lower = content.lower()

        # Check forbidden topics
        for topic in self.forbidden_topics:
            if topic.lower() in content_lower:
                return ValidationResult(
                    Decision.BLOCK,
                    f"Out-of-scope topic detected: {topic}"
                )

        return ValidationResult(Decision.ALLOW, "Within scope")

Il guardrail di formato sembra banale, eppure offre il maggior valore quotidiano. Costa pochi microsecondi, non dipende da chiamate di rete e blocca sul nascere i messaggi sovradimensionati usati per iniezioni volumetriche e tentativi di esaurimento del budget. Posizionalo per primo nella catena: non ha senso pagare la moderazione via API per un messaggio di 200.000 caratteri che rifiuterai comunque.

class FormatGuardrail(Guardrail):
    """Validates message format and length."""

    def __init__(self, max_tokens: int = 4000, max_lines: int = 100):
        self.max_tokens = max_tokens
        self.max_lines = max_lines

    def validate(self, content: str, context: dict) -> ValidationResult:
        # Rough token estimation (1 token ~ 4 characters in English)
        estimated_tokens = len(content) // 4
        if estimated_tokens > self.max_tokens:
            return ValidationResult(
                Decision.BLOCK,
                f"Message too long: ~{estimated_tokens} tokens (max {self.max_tokens})"
            )

        line_count = content.count("\n") + 1
        if line_count > self.max_lines:
            return ValidationResult(
                Decision.BLOCK,
                f"Too many lines: {line_count} (max {self.max_lines})"
            )

        return ValidationResult(Decision.ALLOW, "Valid format")

Il terzo monitora l’output e illustra l’uso del verdetto «modify». Le quattro famiglie che cerca condividono una proprietà conveniente: hanno una forma riconoscibile indipendente dal significato. Una chiave API, un indirizzo interno, un IP privato o un percorso server sono identificati dalla loro struttura, senza bisogno di comprendere la frase che li contiene.

import re

class AntiExfiltrationGuardrail(Guardrail):
    """Prevents leakage of sensitive data in outputs."""

    def __init__(self):
        self.sensitive_patterns = {
            "api_key": r"(sk|pk|api[_-]?key)[_-][a-zA-Z0-9]{16,}",
            "internal_email": r"[a-zA-Z0-9.]+@(company|internal|corp)\.\w+",
            "private_ip": r"\b(10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b",
            "server_path": r"(/data/|/etc/|/home/|C:\\Users\\)",
        }

    def validate(self, content: str, context: dict) -> ValidationResult:
        for data_type, pattern in self.sensitive_patterns.items():
            if re.search(pattern, content):
                # Mask instead of blocking
                cleaned_content = re.sub(pattern, "[REDACTED]", content)
                return ValidationResult(
                    Decision.MODIFY,
                    f"Sensitive data redacted: {data_type}",
                    cleaned_content,
                )
        return ValidationResult(Decision.ALLOW, "No leakage detected")

Assemblaggio completo

L’assemblaggio completo mostra come i pezzi si incastrano. L’asimmetria salta agli occhi: due guardrail in ingresso, solo uno in uscita. Questo è frequente e sano: filtri pesantemente prima di chiamare il modello perché è lì che i costi sono evitabili, e mantieni il minimo necessario in uscita per evitare di danneggiare risposte corrette. Il messaggio restituito in caso di blocco in uscita segue la stessa cautela: intenzionalmente vago, non dice cosa è stato rilevato, informazione che servirebbe principalmente a chi cerca di mappare le tue difese.

from openai import OpenAI

def create_secure_assistant():
    """Creates an assistant with a complete guardrail pipeline."""
    client = OpenAI()
    pipeline = GuardrailPipeline()

    # Input guardrails
    pipeline.add_input(FormatGuardrail(max_tokens=2000))
    pipeline.add_input(ScopeGuardrail(
        allowed_topics=["products", "orders", "delivery", "returns"],
        forbidden_topics=["politics", "religion", "competitors"],
    ))

    # Output guardrails
    pipeline.add_output(AntiExfiltrationGuardrail())

    def process(message: str) -> str:
        context = {"user_role": "customer"}

        # Input validation
        input_check = pipeline.validate_input(message, context)
        if input_check.decision == Decision.BLOCK:
            return f"I cannot process this request: {input_check.reason}"

        valid_message = input_check.modified_content or message

        # Model call
        response = client.chat.completions.create(
            model="gpt-5.6-sol",
            messages=[
                {"role": "system", "content": "Acme Corp customer service assistant."},
                {"role": "user", "content": valid_message},
            ],
        )
        reply = response.choices[0].message.content

        # Output validation
        output_check = pipeline.validate_output(reply, context)
        if output_check.decision == Decision.BLOCK:
            return "I am unable to answer this question."

        return output_check.modified_content or reply

    return process

Quando la regola non può essere scritta in regex

Alcune regole di business resistono a qualsiasi formalizzazione tramite pattern. «La risposta non deve costituire consulenza finanziaria», «il messaggio non deve contenere dati sanitari»: nessuna espressione regolare cattura questo. Un secondo modello, veloce ed economico, può allora agire come giudice, con una risposta vincolata al formato JSON per rimanere utilizzabile dal codice chiamante. Il compromesso è esplicito: guadagni precisione al costo di latenza e determinismo, il che riserva questo approccio alle regole che lo giustificano davvero.

def llm_guardrail(message: str, rule: str) -> ValidationResult:
    """Uses a fast model to validate compliance."""
    client = OpenAI()
    response = client.chat.completions.create(
        model="gpt-5.6-terra",
        messages=[
            {"role": "system", "content": f"""You are a compliance validator.
Rule to check: {rule}
Respond ONLY with JSON: {{"compliant": true/false, "reason": "..."}}"""},
            {"role": "user", "content": f"Message to validate:\n{message}"},
        ],
    )
    import json
    result = json.loads(response.choices[0].message.content)
    if result["compliant"]:
        return ValidationResult(Decision.ALLOW, result["reason"])
    return ValidationResult(Decision.BLOCK, result["reason"])

Punti chiave

  • I guardrail convalidano la conformità al business, non solo i contenuti offensivi
  • L’architettura a pipeline permette di combinare più livelli di convalida
  • Ogni guardrail ha una singola responsabilità: ambito, formato, esfiltrazione, ecc.
  • I guardrail in uscita sono importanti quanto quelli in ingresso
  • Per casi complessi, un LLM veloce può fungere da validatore