Système d'outils ToolRegistry

源码版本v2026.7.20

Responsabilité

Un Tool est une fonction atomique que l'agent peut appeler (terminal, navigateur, fichier, MCP, appel de compétence…). À l'import du module, ToolRegistry découvre automatiquement, via un scan AST, les outils déclarés dans tools/*.py et les enregistre ; il expose une table de correspondance name → ToolEntry que la boucle principale utilise pour distribuer les appels d'outils. Les outils sont statiques — par opposition aux compétences qui sont « évolutives ».

Fichiers clés

• discover_builtin_tools:67-86 — scan AST de tools/*.py pour trouver les modules qui enregistrent des outils
• _is_registry_register_call / _module_registers_tools:30-43 — décide si un module appelle registry.register
• class ToolEntry:87-153 — métadonnées d'un outil (handler, schema, toolset, flag de cache)
• class ToolRegistry:217-365 — le registre lui-même
• def register:365-436 — enregistre un outil, construit en interne un ToolEntry
• get_entry / register_toolset_alias:274-290 — requête et alias de toolset
• register_plugin_override_policy:316-365 — stratégie d'admission des espaces de noms pour les outils issus de plugins
• singleton registry:765 — registry = ToolRegistry() (singleton au niveau module)
• tool_error / tool_result:784-810 — enveloppe standard des valeurs de retour d'outil
• répertoire tools/ — environ 80 fichiers d'outils (terminal/browser/web/file/mcp/skills/delegate…)

Flux de données

1. Au démarrage, init_agent:276 déclenche la configuration des toolsets.
2. discover_builtin_tools:67 parcourt le répertoire tools/ et utilise un scan AST pour déterminer si chaque module appelle registry.register (tools/registry.py:30).
3. Les modules retenus sont importés ; leurs appels registry.register(...) au niveau module s'exécutent et écrivent un ToolEntry dans singleton registry:765.
4. À chaque tour, la boucle principale collecte les ToolEntry.schema des toolsets activés dans le champ tools envoyé au provider.
5. Le provider renvoie un tool_call → la boucle principale utilise get_entry(name) (tools/registry.py:274) pour trouver le handler, l'exécute → le résultat est enveloppé via tool_result:798 et réinjecté.

Résumé

La subtilité du système d'outils tient à « importer c'est s'enregistrer » — grâce au scan AST, on évite de maintenir une liste à la main ; ajouter un outil consiste simplement à déposer dans tools/ un fichier qui appelle register. Le singleton registry est la seule source de vérité globale, et la boucle principale se contente de le lire. Différence avec les compétences : les outils sont des fonctions figées, les compétences sont des flux que la boucle d'apprentissage peut réécrire.