feat(agents): add tool_agent_class parameter to AgentFactory and create_executor #74

Merged

hurui200320 merged 1 commits from feature/m1-tool-agent-class-injection into master 2026-07-08 09:44:17 +00:00

Conversation 2 Commits 1 Files Changed 13

+1010 -76

1 Commits

Author	SHA1	Message	Date
hurui200320	9ec578f229	feat(agents): add tool_agent_class parameter to AgentFactory and create_executor ... Extends AgentFactory.__init__ and create_executor() with a keyword-only tool_agent_class: type[ToolAgent] = ToolAgent parameter so callers can inject a custom ToolAgent subclass at runtime without monkey-patching module globals (resolves the five-module setattr loop in cleveragents-webapp). **AgentFactory** (agents/factory.py): - Accepts tool_agent_class keyword argument; validates it is a ToolAgent subclass at construction time (fail-fast, CONTRIBUTING.md §Argument Validation). - Stores as self._tool_agent_class and uses it to populate self.agent_types['tool'], so every create_agent('tool') call instantiates the supplied subclass. - Forwards tool_agent_class to LLMAgent when creating 'llm'-typed agents so the LLM tool-calling loop honours the injected subclass. - Default ToolAgent is preserved, so all existing callers are unaffected. **LLMAgent** (agents/llm.py): - Accepts a keyword-only tool_agent_class: type[ToolAgent] = ToolAgent argument, validated as a ToolAgent subclass at construction time. - The multi-turn tool-call loop (_execute_tool_loop) constructs its ephemeral tool executors via self._tool_agent_class(...) across all three dispatch sites (regular loop, budget-exhaustion synthesis round, and stuck-model synthesis round), so the LLM tool-calling path no longer falls back to the module-level ToolAgent. This closes the gap that previously prevented removing the webapp monkey-patch for the LLM tool-calling path. **Executor / create_executor** (runtime.py): - Executor.__init__ accepts and validates tool_agent_class; stores as self.tool_agent_class. - create_executor() accepts tool_agent_class and forwards it to Executor. **Dispatch paths** (runtime_dispatch.py): - _execute_tool: uses executor.tool_agent_class(...) instead of the module-level ToolAgent(...) so the direct-construction path (bypassing AgentFactory) also honours the injected subclass. - _execute_graph and _execute_graph_stream: pass tool_agent_class=executor.tool_agent_class to AgentFactory so graph nodes using tool-typed agents pick up the subclass. - _execute_llm and _execute_llm_stream: pass tool_agent_class=executor.tool_agent_class to AgentFactory so the single-LLM actor's internally-created LLMAgent (and its tool-calling loop) honours the injected subclass. Without this, a single LLM actor that makes tool calls silently fell back to the base ToolAgent. - _execute_multi_actor: passes tool_agent_class=executor.tool_agent_class to the sub-Executor so every actor inside a multi-actor bundle (tool, graph, or LLM) honours the injected subclass. Without this, all dispatch paths reachable through a multi-actor bundle fell back to the base ToolAgent. - Removed the now-unused module-level ToolAgent import; the _execute_tool docstring cross-reference is fully qualified so it still resolves. All six dispatch paths that construct or dispatch tool agents now forward the injected subclass. **ReactiveCleverAgentsApp** (core/application.py): - Removed the redundant register_agent_type('tool', ToolAgent) call from load_configuration and the dead type_map re-registration block in _create_agents; AgentFactory.__init__ already owns the 'tool' registration. This drops the last hardcoded module-level ToolAgent references flagged in the issue #73 audit. **Tests** (features/tool_agent_class_injection.feature + steps): - 17 BDD scenarios covering: default class when parameter omitted; custom subclass stored on factory and executor; invalid class rejected with ConfigurationError (factory, executor, and LLMAgent); factory create_agent returns custom instance; _execute_tool dispatch instantiates custom subclass; the LLM tool loop instantiates the injected subclass; isinstance LSP compatibility through the factory; the _execute_llm dispatch path forwarding tool_agent_class to AgentFactory (single-LLM actor making a tool call); and the _execute_multi_actor dispatch path forwarding tool_agent_class to the sub-Executor. The two new dispatch-path scenarios were verified to fail without the source fixes (instantiation_count=0), confirming they guard the injection contract for the single-LLM and multi-actor paths. **Updated tests** (features/steps/runtime_coverage_steps.py, features/steps/runtime_extended_coverage_steps.py): - Removed the now-dead patch('cleveractors.runtime_dispatch.ToolAgent') mocks (and their mock instances) that no longer intercept _execute_tool after it switched to executor.tool_agent_class. The tool-actor scenario continues to pass via the real ToolAgent; the normal-coverage branch uses patch.object(ToolAgent, 'process_message', ...) to stub tool execution. **Updated test** (features/steps/credential_executor_paths_steps.py): - The _execute_multi_actor credentials-forwarding scenario intercepts Executor.__init__ with a capturing_init to assert the credentials dict reaches the sub-Executor. Now that _execute_multi_actor forwards tool_agent_class to the sub-Executor, capturing_init accepts and forwards that keyword so the assertion continues to pass. **Removed obsolete test** (features/application_coverage_gaps.feature): - Dropped the '_create_agents registers built-in agent types' scenario and its step definitions; the behaviour it asserted (redundant re-registration) was removed from _create_agents. ISSUES CLOSED: #73	2026-07-08 09:23:34 +00:00