Tool System — ToolRegistry

源码版本v2026.7.20

Responsibility

Tools are the atomic functions the agent can call (terminal, browser, file, MCP, skill invocation...). ToolRegistry auto-discovers tools in tools/*.py via AST scanning at module import time and registers them, providing a name → ToolEntry lookup table for the main loop's tool dispatch. Tools are static — contrast with skills, which are "evolvable".

Key Files

• discover_builtin_tools:67-86 — AST-scans tools/*.py to find modules that register tools
• _is_registry_register_call / _module_registers_tools:30-43 — judges whether a module calls registry.register
• class ToolEntry:87-153 — metadata for a single tool (handler, schema, toolset, cache flag)
• class ToolRegistry:217-365 — the registry itself
• def register:365-436 — registers a tool; internally builds a ToolEntry
• get_entry / register_toolset_alias:274-290 — lookup and toolset alias
• register_plugin_override_policy:316-365 — namespace admission policy for plugin tools
• registry singleton:765 — registry = ToolRegistry() (module-level singleton)
• tool_error / tool_result:784-810 — standard wrapper for tool return values
• tools/ directory — ~80 tool files (terminal/browser/web/file/mcp/skills/delegate...)

Data Flow

1. At startup, init_agent:276 triggers toolsets config.
2. discover_builtin_tools:67 walks the tools/ directory, AST-judging whether each module calls registry.register (tools/registry.py:30).
3. Matching modules are imported; their module-level registry.register(...) calls execute, writing ToolEntrys into registry singleton:765.
4. Each turn the main loop gathers the ToolEntry.schemas of enabled toolsets into the tools field sent to the provider.
5. The provider returns a tool_call → the main loop looks up the handler via get_entry(name) (tools/registry.py:274) and executes it → the result is wrapped via tool_result:798 and backfilled.

Summary

The tool system leans on "register on import" — AST scanning avoids maintaining a manual list; adding a tool is just dropping a file that calls register into tools/. The registry singleton is the single source of truth; the main loop only reads it. Compared with skills: tools are dead functions, skills are flows that the learning loop can rewrite.