Sistema de herramientas ToolRegistry

源码版本v2026.7.20

Responsabilidad

Las Tools son funciones atómicas que el agent puede invocar (terminal, navegador, archivos, MCP, llamadas a skills…). ToolRegistry descubre automáticamente al importar el módulo, vía escaneo AST, las herramientas en tools/*.py y las registra, ofreciendo al bucle principal una tabla name → ToolEntry para despachar las llamadas. Las herramientas son estáticas, en contraste con la «evolutividad» de las habilidades.

Archivos clave

• discover_builtin_tools:67-86 — escanea con AST tools/*.py para encontrar módulos que registran herramientas
• _is_registry_register_call / _module_registers_tools:30-43 — decide si un módulo llama a registry.register
• class ToolEntry:87-153 — metadatos de cada herramienta (handler, schema, toolset, flags de caché)
• class ToolRegistry:217-365 — el registro en sí
• def register:365-436 — registra una herramienta, construye internamente un ToolEntry
• get_entry / register_toolset_alias:274-290 — consulta y alias de toolset
• register_plugin_override_policy:316-365 — política de admisión de namespace para herramientas de plugin
• singleton registry:765 — registry = ToolRegistry() (singleton a nivel de módulo)
• tool_error / tool_result:784-810 — envoltura estándar de los valores de retorno
• directorio tools/ — unos 80 archivos de herramientas (terminal/browser/web/file/mcp/skills/delegate…)

Flujo de datos

1. En el arranque, init_agent:276 dispara la configuración de toolsets.
2. discover_builtin_tools:67 recorre el directorio tools/ y usa AST para decidir si cada módulo llama a registry.register (tools/registry.py:30).
3. Los módulos que cumplen se importan; su llamada a nivel de módulo registry.register(...) se ejecuta y escribe el ToolEntry en el singleton registry:765.
4. El bucle principal, cada turno, recolecta los ToolEntry.schema de los toolsets activos en el campo tools enviado al provider.
5. El provider devuelve un tool_call → el bucle principal hace get_entry(name) (tools/registry.py:274) para encontrar el handler y ejecutarlo → el resultado se envuelve con tool_result:798 y se devuelve al bucle principal.

Resumen

La sutileza del sistema de herramientas está en «importar = registrar»: el escaneo AST evita mantener una lista a mano; añadir una herramienta es tan simple como soltar en tools/ un archivo que llame a register. El singleton registry es la única fuente de verdad; el bucle principal solo lo lee. La diferencia con las habilidades: las herramientas son funciones estáticas; las habilidades, flujos que el bucle de aprendizaje puede reescribir.