Tutoriel - Borner un run avec les budgets d’autonomie

Objectif : lancer un programme Touba avec des limites de run et observer un refus avant que l’exécution ne dépasse le périmètre déclaré.

Les budgets d’autonomie (BQ-1) couvrent la durée de run, le nombre d’étapes, les appels tools, les invocations agents et les quotas de triggers. Ils ne mesurent pas les tokens, les coûts fournisseur ou les quotas distribués.

1. Créer un programme simple

Terminal

mkdir -p budget-demo
cd budget-demo

budget-demo.tb

module examples.budget_demo

limits run
    max_run_ms as 30000
    max_steps as 20
    max_tool_calls as 5
    max_agent_invocations as 3
    max_provider_calls as 4

skill BuildMessage
    description "Display a message and return the completed value."
    gives Text
    do
        show
            with message as "budget demo"
        give "done"

strategy RunBudgetDemo
    gives Text
    uses BuildMessage
    do
        BuildMessage
            into result
        give result

2. Compiler

Terminal

touba compile budget-demo.tb --out budget-demo.air.json

3. Lancer avec un budget suffisant

Terminal

touba run budget-demo.air.json \
  --entry strategy:examples.budget_demo/RunBudgetDemo \
  --output all \
  --trace-out budget-demo.trace.json

Sortie attendue :

Sortie

budget demo

La trace doit contenir des événements de consommation de budget.

4. Lancer avec un budget trop strict

Terminal

if touba run budget-demo.air.json \
  --entry strategy:examples.budget_demo/RunBudgetDemo \
  --max-steps 1 \
  --output json > refused.json; then
  exit 1
else
  test "$?" -eq 1
fi
node --input-type=module -e 'import assert from "node:assert/strict"; import {readFileSync} from "node:fs"; const r=JSON.parse(readFileSync("refused.json","utf8")); assert.equal(r.reason,"StepBudgetExceeded"); assert.deepEqual(r.messages,[]); assert.equal(r.result,null); console.log("STEP_BUDGET_REFUSED_OK");'

Résultat attendu :

Résumé

budget error [...]

Le refus doit arriver comme un événement runtime observable. L’objectif n’est pas d’absorber l’échec, mais de montrer que l’autonomie est bornée par contrat.

5. Inspecter une trace de budget

Terminal

touba inspect budget-demo.trace.json

Vous devez voir les limites et la consommation runtime. Touba ne déduit pas de coût financier depuis ces informations.

Variante avec manifest

Un hôte peut aussi déclarer des limites dans le manifest.

touba.manifest.json

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

Le runtime refuse si le manifest tente d’élargir un budget plus strict déjà déclaré dans l’AIR.

Contrat Validé

Les budgets d’autonomie donnent une borne observable à l’exécution. Le runtime peut refuser une boucle, un appel ou une configuration qui dépasse le périmètre déclaré.

La commande suivante exerce réellement le manifest ci-dessus :

Terminal

touba run budget-demo.air.json --entry strategy:examples.budget_demo/RunBudgetDemo \
  --manifest touba.manifest.json --output json > manifest-result.json
node --input-type=module -e 'import assert from "node:assert/strict"; import {readFileSync} from "node:fs"; const r=JSON.parse(readFileSync("manifest-result.json","utf8")); assert.equal(r.status,"success"); assert.equal(r.result,"done"); assert.ok(r.trace.events.some(e=>e.kind==="budget_limit_checked" && e.payload.budget_kind==="max_steps")); console.log("MANIFEST_BUDGET_OK");'

Le programme déclare ses limites avec limits run. La CLI et le manifest peuvent les restreindre. Une limite n’accorde aucun outil ni scope supplémentaire. max_provider_calls compte orientation, sélection, retries du runtime et finalisation ; ce n’est ni un nombre de tokens ni un coût financier.