Budgets d’autonomie

Les budgets d’autonomie limitent une exécution Touba. Ils servent à refuser une exécution qui dépasserait un périmètre borné : durée de run, nombre d’étapes, nombre d’appels tools, nombre d’invocations agents ou nombre d’appels au decision provider agentique.

Ils bornent le contrat runtime Touba. Les coûts fournisseur, les tokens, les quotas d’équipe et la conformité réglementaire relèvent de couches de mesure et de gouvernance séparées.

Les dépenses passant par un transport hôte peuvent être bornées séparément par le registre financier du SDK.

Syntaxe d’usage

Dans la source Touba

module examples.bounded

limits run
    max_run_ms as 30000
    max_steps as 100
    max_tool_calls as 20
    max_agent_invocations as 5
    max_provider_calls as 10

Un seul bloc limits run, après les imports et avant les déclarations, fixe les plafonds du run entier. Chaque valeur est un littéral Int strictement positif, au plus 9007199254740991. Le compilateur conserve la localisation source dans l’AIR ; aucune édition manuelle de JSON n’est nécessaire.

Une capacité peut être réutilisée tant que son autorité et le budget le permettent. Les sous-agents partagent les compteurs du run ; une reprise humaine conserve la consommation précédente. À l’assemblage, les plafonds du module d’entrée et des modules dont une déclaration exécutable est liée sont combinés par minimum. Importer uniquement un type, une constante ou une mémoire ne transfère pas les plafonds de son module.

Par CLI

Terminal

touba run program.air.json \
  --max-run-ms 30000 \
  --max-steps 100 \
  --max-tool-calls 20 \
  --max-agent-invocations 5 \
  --max-provider-calls 4 \
  --output trace

Par JSON CLI

Terminal

touba run program.air.json \
  --run-limits-json '{"max_steps":100,"max_tool_calls":20}' \
  --output trace

Par manifest

touba.manifest.json

{
  "manifest_version": "touba-manifest-v1",
  "run_limits": {
    "max_steps": 100,
    "max_tool_calls": 20,
    "max_agent_invocations": 5,
    "max_provider_calls": 4
  },
  "bindings": {}
}

Puis :

Terminal

touba run program.air.json \
  --manifest touba.manifest.json \
  --output trace

Budgets disponibles

Budget	Rôle
max_run_ms	Durée maximale du run, observée aux frontières runtime
max_steps	Nombre maximal de nœuds runtime consommés
max_tool_calls	Nombre maximal de dispatchs tools
max_agent_invocations	Nombre maximal d’invocations agents
max_provider_calls	Nombre maximal d’appels au decision provider agentique
max_runs_per_day	Quota de trigger, porté par les limites de trigger

Différence avec timeout

--run-timeout-ms est un contrôle d’annulation d’exécution. Quand il est observé, le run se termine en cancelled.

--max-run-ms est un budget d’autonomie. Quand il est dépassé, le run échoue avec un événement budget et un statut final failure.

Règle de restriction

Quand plusieurs sources déclarent une limite, la limite effective est la plus restrictive.

Le manifest peut restreindre une limite issue de l’AIR. Il ne peut pas l’élargir silencieusement.

Exemple :

module examples.restricted

limits run
    max_steps as 10

Manifest refusé

{
  "manifest_version": "touba-manifest-v1",
  "run_limits": {
    "max_steps": 20
  },
  "bindings": {}
}

Le runtime refuse cette configuration, car 20 élargit la limite AIR 10.

Pause et reprise humaine

Une pause ne remet pas les budgets à zéro. Le checkpoint conserve les compteurs, le temps actif déjà consommé et les plafonds effectifs, y compris ceux de l’hôte. À la reprise, les limites précédentes et actuelles sont combinées par minimum. Supprimer ou augmenter une option hôte ne rend donc aucun budget supplémentaire. Le temps passé à attendre une décision humaine est exclu de max_run_ms ; l’expiration de cette attente relève d’une deadline distincte.

Les anciens checkpoints de développement dépourvus de cet état complet sont refusés sans modification. Conservez-les ; aucune migration ou remise à zéro implicite n’est effectuée.

max_provider_calls compte chaque tentative auprès du decision provider, y compris les retries pilotés par le runtime. Un SDK fournisseur peut effectuer ses propres retries HTTP : ce compteur n’est pas une mesure des requêtes réseau réelles ni une garantie de facturation.

Budgets partagés en parallèle

Toutes les branches et tous les sous-agents consomment les mêmes compteurs de run. La vérification et la réservation se font avant dispatch, sans fenêtre de concurrence entre elles : deux branches ne peuvent pas consommer le même dernier permis. Une erreur de transport ne rembourse pas automatiquement la tentative.

Les bornes max_concurrency et max_items du source limitent un groupe. parallelLimits côté Engine, ou --parallel-limits-json côté CLI, bornent aussi les branches vivantes, transports externes et profondeur à l'échelle du run, groupes imbriqués compris. Voir la référence CLI. Un timeout logique ne libère pas un transport toujours actif ; ces plafonds ne constituent ni une facture ni une limite monétaire.

Lire un refus

Avec --output trace, un refus de budget contient des événements comme :

Trace extrait

{
  "kind": "dispatch_refused_budget_exceeded",
  "payload": {
    "budget_kind": "max_tool_calls",
    "limit_value": 1,
    "consumed_value": 1,
    "target_ref": "tool:examples.search/SearchDatasets",
    "runtime_error_code": "ToolCallBudgetExceeded"
  }
}

Vous pouvez inspecter la trace :

Terminal

touba inspect trace.json

L’inspection affiche le nombre de budgets vérifiés, consommés, dépassés et les types de budget concernés.

Effets déjà produits

Un budget borne le prochain pas contrôlé par le runtime : nouveau nœud, dispatch de tool, invocation d’agent ou appel provider. Il ne rollback pas un effet externe déjà terminé par un handler.

Par exemple, si un agent écrit une note dans un backend mémoire puis dépasse max_steps au moment de lire la confirmation, l’écriture peut être déjà acquise dans le backend hôte. La trace doit alors être lue comme un arrêt après effet, pas comme une garantie transactionnelle.

Pour les workflows sensibles, placez les validations humaines, checks de manifest, resource bindings, locks supply chain et budgets avant l’effet qui doit être protégé, puis rendez les handlers idempotents quand le système hôte le permet.

Périmètre

Les budgets d’autonomie sont des limites runtime Touba. Ils couvrent :

• durée coopérative de run ;
• nombre maximal d’étapes runtime ;
• nombre maximal de dispatchs tools ;
• nombre maximal d’invocations agents ;
• nombre maximal d’appels au provider de décision ;
• quotas de trigger.

Le hard kill système, les quotas distribués, les coûts fournisseur, les compteurs de tokens portables, la sandbox réseau/filesystem et la conformité réglementaire sont portés par les contrôles plateforme environnants.