Loops et monitors

Relancer un agent à intervalle régulier, comparer chaque passage au précédent et être notifié seulement quand quelque chose change.

Un loop relance un agent sur une liste d'entités à intervalle régulier ; un monitor surveille un sujet. Dans les deux cas, chaque passage est comparé au précédent et les changements deviennent des findings, notifiés sur les canaux de votre choix.

Loop ou monitor

Type	Entrée	Exemple
`loop`	Une liste de lignes (10 000 au plus), rejouée comme un batch.	Revérifier chaque mois 300 fournisseurs : dirigeants, annonces BODACC, sanctions.
`monitor`	Un sujet en texte libre (`config.subject`).	Relever chaque matin le prix d'un produit chez cinq marchands concurrents.

Fréquence et fuseau

frequency accepte daily, weekly, monthly ou une expression cron à 5 champs, par exemple 0 7 * * 1-5 pour 7 h du lundi au vendredi.
config.time fixe l'heure locale (HH:MM, 08:00 par défaut), config.weekday le jour pour weekly (0 pour dimanche, 1 pour lundi par défaut) et config.day_of_month le jour pour monthly (1 à 28).
timezone prend un fuseau IANA, Europe/Paris par défaut. Les changements d'heure sont pris en compte.
Après 3 échecs consécutifs, la planification se désactive. Réactivez-la avec PATCH /v1/schedules/:id et is_active à true.

curl -X POST https://api.forge.example/v1/schedules \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "monitor",
    "agent_id": "3b9d0f7c-…",
    "name": "Prix concurrents robot pâtissier",
    "frequency": "daily",
    "timezone": "Europe/Paris",
    "config": {
      "subject": "Prix du robot pâtissier XR-500 chez les cinq principaux marchands",
      "time": "07:30",
      "ignore_fields": ["nombre_avis"]
    },
    "notify": { "channels": ["email", "webhook"], "only_on_change": true }
  }'

{
  "kind": "loop",
  "agent_id": "8f1c2a4e-…",
  "frequency": "monthly",
  "timezone": "Europe/Paris",
  "config": {
    "day_of_month": 1,
    "time": "06:00",
    "rows": [{ "siren": "123456789" }, { "siren": "987654321" }],
    "entity_key_field": "siren",
    "effort": "low"
  },
  "notify": { "channels": ["in_app", "slack"], "only_on_change": true }
}

Findings et détection de changements

Chaque passage reçoit le résultat précédent comme référence. FORGE compare les sorties structurées champ par champ et enregistre un finding avec le détail des changements (diff) et une sévérité info, warning ou critical. La sévérité vient du champ severity de la sortie si votre schéma le prévoit, sinon d'une heuristique : suppressions, variations numériques de 20 % ou plus. L'agent peut aussi signaler lui-même un changement avec changes_detected. config.ignore_fields exclut de la comparaison les champs volatils, comme un nombre d'avis.

# Findings d'une planification
curl https://api.forge.example/v1/schedules/<schedule_id>/findings \
  -H "Authorization: Bearer $FORGE_API_KEY"

# Déclencher un passage tout de suite
curl -X POST https://api.forge.example/v1/schedules/<schedule_id>/trigger \
  -H "Authorization: Bearer $FORGE_API_KEY"

Notifications

notify.channels combine in_app, email, webhook et slack. Avec only_on_change à true, vous n'êtes notifié que lorsqu'un changement est détecté. Côté webhooks, les findings déclenchent l'événement schedule.finding.

Chaque passage consomme des crédits comme un run ou un batch. Avant d'activer un loop de 300 lignes, estimez le coût d'un batch équivalent et choisissez l'effort low si la tâche le permet.