Batches CSV et XLSX

Un batch exécute le même agent sur chaque ligne d'un fichier CSV ou XLSX : 500 fournisseurs à vérifier, 2 000 fiches produits à enrichir à partir de leur EAN. Chaque ligne devient un run, suivi dans le mur Live, et les résultats s'exportent dans le même format.

Préparer le fichier

Une ligne par entité, une colonne par champ, jusqu'à 100 000 lignes. Le mapping associe chaque colonne à un champ du formulaire d'entrée de l'agent ; l'app le propose automatiquement et signale les champs requis non couverts. La colonne d'identité (entity_key_field, par exemple siren ou ean) dédoublonne les lignes et relie chaque résultat à son entité. Un modèle de question (question_template) peut remplacer le mapping pour les agents sans formulaire.

Estimer et fixer le budget

• L'estimation (POST /v1/batches/estimate) donne le coût attendu et le coût maximal pour l'ensemble des lignes. Si votre solde ne suffit pas, l'app propose un effort inférieur.
• max_credits plafonne la dépense totale : aucune ligne n'est lancée sans budget couvert. Plafond atteint, le batch passe en pause et l'événement batch.paused est émis ; relevez le plafond puis reprenez.
• max_concurrent fixe le nombre de runs simultanés : 5 par défaut, 20 au maximum.

Créer le batch

forge batches create \
  --agent 8f1c2a4e-… \
  --file societes.csv \
  --mapping '{"Raison sociale":"company_name","SIREN":"siren"}' \
  --entity-key siren \
  --effort low \
  --max-credits 5000 \
  --max-concurrent 10

curl -X POST https://api.forge.example/v1/batches \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Idempotency-Key: kyb-fournisseurs-octobre" \
  -F agent_id=8f1c2a4e-… \
  -F file=@societes.csv \
  -F 'mapping={"SIREN":"siren"}' \
  -F entity_key_field=siren \
  -F max_credits=5000 \
  -F max_concurrent=10

Suivre dans le mur Live

La salle de contrôle affiche une carte par ligne : étape, dernière action, aperçu du navigateur, statut et coût. Filtrez les runs en cours, en erreur, en revue ou terminés ; un clic ouvre la vue Live du run. Le bandeau indique le débit, le coût cumulé face au plafond et l'heure de fin estimée, et signale les anomalies (agent bloqué, coût inhabituel). Par API : WebSocket /v1/batches/:id/live ou SSE /v1/batches/:id/live/sse.

Pause, relance, export

# Mettre en pause, puis reprendre avec un plafond relevé
forge batches control <batch_id> pause
forge batches control <batch_id> resume --max-credits 8000

# Relancer uniquement les lignes en échec
forge batches control <batch_id> retry_failed

# Exporter les résultats
forge batches results <batch_id> --format xlsx -o resultats.xlsx
forge batches results <batch_id> --format csv > resultats.csv

retry_failed ne relance que les lignes en échec, sans repayer les autres. L'export JSON, CSV ou XLSX reprend pour chaque ligne les données d'entrée, la sortie structurée et le statut. À la fin du batch, l'événement batch.completed est envoyé à vos webhooks.