Adopter Touba depuis des outils existants

Touba n'impose pas de réécrire une pile agentique existante. Le chemin d'adoption recommandé consiste à garder les intégrations utiles, puis à les placer sous contrat Touba : source .tb, AIR, manifest, secrets opaques, budgets, validation humaine quand l'effet le demande, handler et traces.

Le changement principal est le suivant : un outil n'est plus seulement exposé au modèle ; il devient une capacité déclarée, révisable et observable.

Chemins d'entrée

Vous avez déjà	Entrée Touba
un serveur MCP	importer ses tools comme tool Touba gouvernés
une fonction LangChain @tool	déclarer son contrat en .tb, garder le corps dans un handler
un schéma OpenAI function calling	transformer le JSON Schema en types Touba et manifest
une API REST ou OpenAPI	générer un tool, un manifest et un handler HTTP borné
un script local utile	le ranger dans un skill pack, puis l'exposer par un tool si l'exécution est nécessaire

MCP vers Touba

MCP expose des tools via tools/list, puis les exécute via tools/call. Un tool MCP porte un nom, une description, un inputSchema JSON Schema et parfois un outputSchema. Ce sont des informations suffisantes pour produire un contrat Touba initial. Référence : MCP Tools specification.

MCP	Touba
Tool.name	nom du tool et ref canonique
Tool.description	documentation du tool et du handler
inputSchema	type Touba utilisé par takes
outputSchema ou structuredContent	type Touba utilisé par gives
résultat texte	champ Text borné ou ressource déclarée
tools/call	handler Touba qui appelle le serveur MCP
authentification du serveur	secret handle déclaré dans le manifest
opération sensible	human.approve avant l'effet
timeout ou rate limit	budget Touba et timeout handler
observation d'exécution	trace Touba

La commande touba mcp import réduit cette friction d'entrée. Elle consomme un snapshot explicite de tools MCP et produit le contrat Touba correspondant : source .tb, fragment de manifest, configuration de pont stdio, handlers de pont, template de secrets, rapport d'import et README local.

Terminal

touba mcp import mcp.github.json \
  --module integrations.mcp.github \
  --out integrations/github \
  --mode plan

Le mode plan permet de relire les noms, types, grants et handles de secrets avant écriture. Le mode write crée les fichiers ; le mode check vérifie que les artefacts générés n'ont pas dérivé. Les tools MCP qui ne produisent pas un contrat Touba clair sont listés dans le rapport de refus, avec la raison.

Après génération, mcp.bridge.config.json désigne le serveur MCP local approuvé à lancer en stdio et mappe ses variables d'environnement vers les handles de secrets accordés. Les valeurs secrètes restent dans le store Touba ou l'environnement d'exécution, jamais dans ce fichier.

Exemple MCP minimal

mcp.github.json

{
  "mcp_import_config_version": "touba-mcp-import-config-v1",
  "server": {
    "name": "github",
    "transport": "snapshot",
    "secret_handles": ["GITHUB_TOKEN"],
    "timeout_ms": 5000,
    "max_payload_bytes": 65536
  },
  "tools": [
    {
      "name": "post_comment",
      "description": "Post a GitHub comment after review",
      "secret_handles": ["GITHUB_TOKEN"],
      "inputSchema": {
        "type": "object",
        "properties": {
          "issueNumber": { "type": "integer" },
          "body": { "type": "string" }
        },
        "required": ["issueNumber", "body"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "posted": { "type": "boolean" }
        },
        "required": ["url", "posted"]
      }
    }
  ]
}

Résultat attendu en mode write :

• src/github.tb avec un tool PostComment typé ;
• touba.manifest.fragment.json avec network et secret_read ;
• mcp.bridge.config.json avec GITHUB_TOKEN mappé depuis le handle ;
• un handler *.mcp-bridge.mjs qui appelle tools/call ;
• un rapport indiquant les tools importés ou refusés.

Ce résultat reste un contrat. Le projet doit encore relire le diff, accorder le secret handle, choisir le provider d'exécution et lancer un run avec trace.

REST et OpenAPI

La majorité des intégrations communautaires sont des API HTTP avec clé. Le patron Touba est stable :

Structure

types .tb
  décrivent la requête et la réponse
tool .tb
  déclare network et les secrets attendus
manifest
  lie le tool au handler et aux handles de secrets
handler
  appelle l'API REST et normalise la réponse
trace
  enregistre l'autorisation, le refus ou le succès

Le scaffold REST/OpenAPI produit ces fichiers sans accorder d'autorité silencieuse :

Terminal

touba rest scaffold rest.search.json \
  --module integrations.web_search \
  --out integrations/web-search \
  --mode plan

--mode write crée la source .tb, le fragment de manifest, rest.handler.config.json, le handler HTTP, le template de secrets, le rapport de génération et le README local. --mode check vérifie que les artefacts générés restent alignés avec le fichier de configuration.

Le développeur relit le diff, choisit les grants, renseigne les handles de secrets et valide le run.

Exemple REST

Une API de recherche avec clé devient un tool Touba explicite :

web-search.tb

module integrations.web_search

type WebSearchRequest
    query is Text
    max_results is Int

type WebSearchResult
    summary is Text
    source_count is Int

tool SearchWeb
    takes request as WebSearchRequest
    gives WebSearchResult
    requires network, secret_read
    secrets WEB_SEARCH_API_KEY

Le manifest du projet lie ensuite tool:integrations.web_search/SearchWeb à un handler HTTP et au handle WEB_SEARCH_API_KEY. La trace attendue doit montrer l'autorisation ou le refus de binding, sans valeur de clé ni payload brut.

LangChain et function calling

Un tool LangChain ou une fonction OpenAI function calling contient déjà trois idées utiles : un nom, une description et un schéma d'arguments. Touba conserve ces idées, puis les sépare :

Modèle mental existant	Séparation Touba
fonction callable par le modèle	tool déclaré dans .tb
schéma d'arguments	type Touba et validation AIR
code de la fonction	handler hôte
clé API	secret handle hors payload agentique
choix du modèle	agent uses, callable_by et provider de décision
logs applicatifs	trace Touba structurée

Cette séparation rend la capacité plus facile à réviser. Le modèle peut encore choisir parmi des capacités utiles, mais l'autorité d'exécution reste explicite.

Exemple LangChain

Avant

@tool
def search_web(query: str, max_results: int = 5) -> str:
    ...

Dans Touba, le corps reste dans le handler hôte. Le contrat devient relisible :

Après

tool SearchWeb
    takes request as WebSearchRequest
    gives WebSearchResult
    requires network, secret_read
    secrets WEB_SEARCH_API_KEY

Le modèle ne reçoit plus une fonction opaque. Il voit une capacité déclarée, bornée par uses, manifest, grants, budgets et traces.

Exemple OpenAI function calling

Un schéma JSON de fonction :

function schema

{
  "name": "send_notification",
  "parameters": {
    "type": "object",
    "properties": {
      "channel_ref": { "type": "string" },
      "message": { "type": "string" }
    },
    "required": ["channel_ref", "message"]
  }
}

devient un type Touba, puis un tool éventuellement composé par une skill avec human.approve avant l'effet externe.

Rendre votre intégration réutilisable

Après validation du comportement métier et des refus, distribuez-la comme package Touba. Le package peut réunir tools, handlers, skills, agents et procédures contextuelles dans un seul manifeste. Le Hub liste les packages publiés ; un exemple de connexion ne constitue pas une intégration disponible.

Parcours minimal

1. Choisir une intégration existante et un seul effet externe.
2. Écrire ou générer le tool Touba et ses types.
3. Lancer touba prepare --mode plan, puis touba prepare --mode write.
4. Relire le manifest, les grants, les secrets et les contraintes de payload.
5. Implémenter le handler ou raccorder le pont MCP généré.
6. Exécuter avec --trace-out et relire les refus ou succès.
7. Promouvoir l'intégration en package seulement quand le contrat est stable.

Ce parcours garde l'intelligence des outils existants tout en ajoutant la gouvernance, la fiabilité et l'audit qui manquent aux intégrations prompt-first.