Exécution de code

Pour une question analytique (le plus élevé, le total, la moyenne, un top-N, un comptage exhaustif) ou multi-étapes (recouper plusieurs sources), faire transiter toutes les données par le modèle coûte cher en tokens et le pousse à calculer « de tête » — peu fiable.

L’outil exécution de code résout ça : le modèle écrit un petit programme JavaScript, exécuté dans un bac à sable isolé qui interroge vos connecteurs API et calcule le résultat. Seul le résultat final revient au modèle ; les données ne polluent pas le contexte. Le calcul est fait par du code (déterministe), pas estimé.

Activer

Deux conditions :

la clé porte le scope code (Portail → Clés API) ;
la requête passe tools_enabled: ["code"] — généralement avec un ou plusieurs connecteurs.

curl https://api.astrolabe.chat/v1/chat/completions \
  -H "Authorization: Bearer $ASTROLABE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium",
    "messages": [{ "role": "user", "content": "Quelle est la facture la plus élevée de 2026 ?" }],
    "tools_enabled": ["code", "connection:ma-compta"]
  }'

Le modèle décide seul d’écrire un script ; il reboucle (corrige) si l’exécution renvoie une erreur, dans la limite de tools_max_steps. Mode agentique (non-streamé), comme le RAG agentique et les outils web — ils coexistent dans la même boucle.

L’API disponible dans le bac à sable

Le script appelle vos connecteurs (jamais le réseau brut) :

// appel brut d'une opération → JSON de l'API
const page = await astrolabe.connector("ma-compta").call("list-invoices", { limit: 100, cursor });

// agrégat déterministe (pagination complète automatique) → { count, sum, avg, min, max }
// `list` = le NOM de l'opération de liste à agréger ; `field` = le champ numérique.
const agg = await astrolabe.connector("ma-compta").aggregate({
  list: "list-invoices",
  field: "amount",
  filter: '[{"field":"date","operator":"gteq","value":"2026-01-01"}]'
});

// interroger une base de connaissance (moteur analytique : total / aggregates exacts)
const kb = await astrolabe.kb("ma-base").search({
  filters: [{ key: "statut", op: "eq", value: "actif" }],
  aggregate: "montant",   // → aggregates[0] = { count, sum, avg, min, max }
  group_by: "document"    // → total = nombre d'enregistrements EXACT
});

Pour un superlatif ou un agrégat sur un champ que l’API ne sait pas trier (ex. un montant), préférez aggregate (il pagine tout et calcule côté serveur) ; sinon paginez vous-même dans le script.

Deux réflexes d’efficacité (coût en tokens) : enchaînez les appels dépendants dans un seul script (ex. facture → client → participant) plutôt qu’un script par appel ; et ne renvoyez que le résultat utile via console.log(JSON.stringify(resultat)) — pas le JSON brut complet d’un enregistrement, qui gonfle le contexte inutilement.

Chaque source doit être autorisée : un connecteur via tools_enabled:["connection:<slug>"], une base de connaissance via knowledge_base:["<slug>"] + le scope kb:read sur la clé. Le code ne peut interroger que les sources que vous avez ainsi activées — ce qui permet de recouper une base et un connecteur dans un seul script (ex. santé d’une participation ⇄ CA facturé).

Sécurité

Isolation : le script s’exécute dans un bac à sable sans réseau ni système de fichiers. Il ne peut que appeler vos connecteurs via astrolabe.* ; aucune autre sortie possible.
Vos secrets ne sont jamais exposés au script : l’authentification des connecteurs est appliquée côté serveur. Le script reçoit des données, jamais vos clés.
Permissions : un script ne peut utiliser que les connecteurs auxquels la clé a accès (scope connections + autorisations par connexion). Les opérations en écriture restent soumises à leur autorisation habituelle.
Bornes : temps d’exécution et nombre de pages plafonnés.

Souveraineté & facturation

L’exécution tourne sur notre infrastructure (UE) ; les données restent dans le pipeline européen. Router vers un modèle cloud reste soumis à l’opt-in habituel.
Gratuit : seuls les tokens du modèle sont facturés (le calcul et les appels connecteurs ne le sont pas). Et comme les données ne passent plus par le contexte, ces questions analytiques coûtent bien moins de tokens qu’une boucle classique.

Quand l’utiliser (et quand non)

Question	Outil
« liste les factures de mars »	connecteur direct (`connection:…`)
« la facture la plus élevée », « le CA total 2026 », « la moyenne par client »	exécution de code
recouper plusieurs connecteurs et/ou bases de connaissance dans un même calcul	exécution de code
recherche de connaissances non structurées	base de connaissance (RAG)