Tool

Un tool déclare une action qui sort du calcul pur. Il décrit le contrat d’un effet externe : entrée, sortie, capabilities requises, secrets éventuels et accès mémoire éventuels.

Le code réel ne vit pas dans le fichier .tb. Il vit dans un handler hôte relié par manifest.

Forme

source.tb

tool Name
    takes input as InputType
    gives OutputType
    requires capability

Clauses visibles :

• requires <capability> ;
• secrets HANDLE ;
• uses memory <Name> read ;
• uses memory <Name> write.

Cas simple

tool_simple.tb

module examples.tool_simple

type DatasetSearchRequest
    query is Text

type DatasetSearchResult
    title is Text

tool SearchDatasets
    takes request as DatasetSearchRequest
    gives DatasetSearchResult
    requires network

Ce tool déclare l’accès réseau requis. Le manifest le relie à un handler JavaScript ou Python. Les deux SDK partagent ce même contrat source.

Cas avancé

tool_advanced.tb

module examples.tool_advanced

type SearchRequest
    query is Text

type Summary
    text is Text

memory ProjectKnowledge

tool SummarizeWithContext
    uses memory ProjectKnowledge read
    takes request as SearchRequest
    gives Summary
    requires network, secret_read, memory_read
    secrets LLM_API_KEY

Ce cas déclare trois frontières :

• le handler aura besoin du réseau ;
• le runtime devra résoudre le handle LLM_API_KEY sans exposer sa valeur dans .tb, AIR, manifest ou trace ;
• l’accès logique à ProjectKnowledge devra être accordé et scope avant dispatch.

Ce que le tool absorbe

Sans tool, un effet externe peut rester hors contrat dans une fonction hôte ordinaire : appel HTTP, lecture de base, accès à une clé, écriture fichier.

Avec tool, l’effet devient un contrat visible. Le runtime peut refuser avant handler si le manifest ne satisfait pas les requirements produits par l’AIR.

Contrat runtime

• requires network n’est pas une sandbox réseau.
• secrets LLM_API_KEY ne contient jamais la valeur du secret.
• Un tool ne contient pas de code hôte inline.
• Un tool sans binding manifest ne peut pas exécuter de handler.