Garde-fous, observabilité et coûts

Les garde-fous, couche par couche

Un agent agit dans le monde réel : une commande créée par erreur, c'est un colis envoyé. Les protections se placent dans le code, à chaque étape de la boucle, jamais seulement dans le prompt.

flowchart LR
  E["Entrée client"] --> G1["1. Filtrer l'entrée : longueur, hors sujet"]
  G1 --> L["LLM"]
  L --> G2["2. Contrôler l'appel d'outil : liste blanche, validation, seuils"]
  G2 -->|"action sensible"| H["Confirmation client ou humaine"]
  G2 --> T["Outil"]
  H --> T
  T --> L
  L --> G3["3. Vérifier la sortie : prix cités = prix du catalogue"]
  G3 --> S["Réponse"]

Un garde-fou dans ADK : before_tool_callback

ADK appelle cette fonction avant chaque outil. Si elle renvoie un dictionnaire, l'outil n'est pas exécuté et ce dictionnaire sert de résultat.

QUANTITE_MAX = 50


def garde_fou_outils(tool, args, tool_context):
    if tool.name == "creer_commande" and args.get("quantite", 0) > QUANTITE_MAX:
        return {"erreur": f"Au-delà de {QUANTITE_MAX} unités, un conseiller doit valider. "
                          "Propose le transfert à un humain."}
    return None  # None = on laisse l'outil s'exécuter

root_agent = Agent(
    # ... name, model, instruction, tools ...
    before_tool_callback=garde_fou_outils,
)

Dans la boucle « fait main » du module 2, le même contrôle se place au début de run_tool, avant TOOLS_PY[name](**args).

Observabilité : savoir ce que l'agent a fait

Quand un client se plaint, il faut pouvoir répondre : quels outils, avec quels arguments, quels résultats, combien de tours, combien de tokens ?

ADK émet des traces OpenTelemetry ; au déploiement, adk deploy cloud_run --trace_to_cloud les envoie vers Cloud Trace. Dans votre boucle maison, le minimum est une ligne JSON par événement, que Cloud Logging indexe automatiquement :

import json, sys, time

def log(evenement, **champs):
    print(json.dumps({"evenement": evenement, "t": time.time(), **champs},
                     ensure_ascii=False), file=sys.stderr)

# dans run_tool :  log("outil", nom=name, args=args, resultat=str(result)[:200])

Les coûts : ordre de grandeur avant la facture

Le coût d'une requête est la somme, sur tous les tours, de (tokens d'entrée × prix d'entrée) + (tokens de sortie × prix de sortie). Or à chaque tour, tout l'historique est renvoyé.

Exemple de calcul, avec des chiffres purement illustratifs : prompt système + schémas d'outils ≈ 1 500 tokens, chaque tour ajoute ≈ 300 tokens, 4 tours par demande.

Multipliez par le prix par million de tokens de votre modèle (consultez la grille tarifaire officielle, elle change souvent) puis par le nombre de demandes par jour.

Exercice : un garde-fou et une estimation

1. Dans la boucle Python pur du module 2, ajoutez à run_tool un contrôle : si l'outil s'appelle creer_commande et que quantite > 50, ne pas exécuter et renvoyer une erreur demandant l'escalade.
2. Avec les hypothèses du tableau ci-dessus (7 800 tokens d'entrée, 600 de sortie par demande) et des prix fictifs de 0,30 € par million de tokens d'entrée et 2,50 € par million en sortie, estimez le coût de 1 000 demandes par jour pendant 30 jours.

QUANTITE_MAX = 50


def run_tool(call):
    name = call["function"]["name"]
    try:
        args = json.loads(call["function"]["arguments"] or "{}")
        if name == "creer_commande" and args.get("quantite", 0) > QUANTITE_MAX:
            result = {"erreur": f"Au-delà de {QUANTITE_MAX} unités, transférer à un humain."}
        elif name not in TOOLS_PY:
            result = {"erreur": f"Outil inconnu : {name}"}
        else:
            result = TOOLS_PY[name](**args)
    except Exception as e:
        result = {"erreur": f"{type(e).__name__}: {e}"}
    return {"role": "tool", "tool_call_id": call["id"],
            "content": json.dumps(result, ensure_ascii=False)}

Je sais faire

• Placer des garde-fous dans le code à l'entrée, sur les outils et en sortie
• Bloquer une action sensible avec before_tool_callback ou dans run_tool
• Lister ce qu'il faut tracer pour déboguer une conversation
• Estimer le coût mensuel d'un agent à partir du nombre de tours