feat(agents): add tool_agent_class parameter to AgentFactory and create_executor #74
No reviewers
Labels
No labels
auto/blocked-by-deps
auto/ci-timeout
auto/claimed-implementer
auto/claimed-merge
auto/claimed-reviewer
auto/driver-down
auto/invariant-violation
auto/last-attempt-tier-0
auto/last-attempt-tier-1
auto/last-attempt-tier-2
auto/last-attempt-tier-min
Automation Tracking
auto/needs-conflict-resolution
auto/needs-implementer
auto/postmortem
auto/ready-to-merge
auto/restart-throttled
auto/revert
auto/sentinel
auto/stale-inactivity
auto/unstable
Blocked
Bounty
$100
Bounty
$1000
Bounty
$10000
Bounty
$20
Bounty
$2000
Bounty
$250
Bounty
$50
Bounty
$500
Bounty
$5000
Bounty
$750
MoSCoW
Could have
MoSCoW
Must have
MoSCoW
Should have
Needs Feedback
Points
1
Points
13
Points
2
Points
21
Points
3
Points
34
Points
5
Points
55
Points
8
Points
88
Priority
Backlog
Priority
CI Blocker
Priority
Critical
Priority
High
Priority
Low
Priority
Medium
Signed-off: Owner
Signed-off: Scrum Master
Signed-off: Tech Lead
Spike
State
Completed
State
Duplicate
State
In Progress
State
In Review
State
Paused
State
Unverified
State
Verified
State
Wont Do
Type
Automation
Type
Bug
Type
Discussion
Type
Documentation
Type
Epic
Type
Feature
Type
Legendary
Type
Refactor
Type
Support
Type
Task
Type
Testing
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Blocks
#73 Add
tool_agent_class parameter to AgentFactory and create_executor to support runtime-injected ToolAgent subclasses
cleveragents/cleveractors-core
Reference
cleveragents/cleveractors-core!74
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "feature/m1-tool-agent-class-injection"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Eliminates the monkey-patching workaround used by
cleveragents-webappto substitute a platform-controlledToolAgentsubclass at runtime. Adds a keyword-onlytool_agent_class: type[ToolAgent] = ToolAgentparameter toAgentFactory.__init__,Executor.__init__,create_executor(), andLLMAgent.__init__. Every internal site that constructs an ephemeralToolAgent— including the LLM agent's multi-turn tool-call loop and all six dispatch paths — now uses the injected subclass.Motivation
cleveragents-webappcurrently monkey-patches fivecleveractorsmodule namespaces at import time to replace theToolAgentclass withPlatformAwareToolAgent. This approach is fragile against library evolution (any new module that importsToolAgentat import time would be missed), import-order sensitive, and breaks static analysis. This PR provides the upstream API extension that removes the need for the monkey-patch entirely — including the LLM tool-calling path and the multi-actor path, which earlier drafts missed.What Changed
src/cleveractors/agents/factory.py(AgentFactory.__init__,_create_agent_instance)tool_agent_class: type[ToolAgent] = ToolAgentargument.ToolAgentsubclass at construction time (fail-fast perCONTRIBUTING.md §Argument Validation).self._tool_agent_classand uses it to populateself.agent_types["tool"], socreate_agent("tool")instantiates the supplied subclass.tool_agent_class=self._tool_agent_classtoLLMAgentwhen creating"llm"-typed agents, so the LLM tool-calling loop honours the injected subclass.src/cleveractors/agents/llm.py(LLMAgent.__init__,_execute_tool_loop)LLMAgent.__init__accepts a keyword-onlytool_agent_class: type[ToolAgent] = ToolAgentargument, validated as aToolAgentsubclass at construction time.self._tool_agent_class(...)across all three dispatch sites (the regular loop, the budget-exhaustion synthesis round, and the post-loop stuck-model synthesis round). Previously these sites importedToolAgent as _TAlocally and constructed the base class directly, which silently bypassed the injected subclass.src/cleveractors/runtime.py(Executor,create_executor)Executor.__init__accepts and validatestool_agent_class, stored asself.tool_agent_class.create_executor()acceptstool_agent_class(keyword-only) and forwards it toExecutor.src/cleveractors/runtime_dispatch.py(all six dispatch paths)_execute_tool: usesexecutor.tool_agent_class(...)instead of the module-levelToolAgent(...)._execute_graphand_execute_graph_stream: passtool_agent_class=executor.tool_agent_classtoAgentFactoryso graph nodes with tool-typed agents pick up the subclass._execute_llmand_execute_llm_stream: passtool_agent_class=executor.tool_agent_classtoAgentFactoryso the single-LLM actor's internally-createdLLMAgent(and its tool-calling loop) honours the injected subclass. (Review-fix round 2) — without this, a single LLM actor that makes tool calls silently fell back to the baseToolAgent._execute_multi_actor: passestool_agent_class=executor.tool_agent_classto the sub-Executorso every actor inside a multi-actor bundle (tool, graph, or LLM) honours the injected subclass. (Review-fix round 2) — without this, all dispatch paths reachable through a multi-actor bundle fell back to the baseToolAgent.ToolAgentimport; the_execute_tooldocstring cross-reference is fully qualified so it still resolves.src/cleveractors/core/application.py(load_configuration,_create_agents)register_agent_type("tool", ToolAgent)call fromload_configurationand the deadtype_mapre-registration block in_create_agents;AgentFactory.__init__already owns the"tool"registration. The"llm"registration is retained as a defensive no-op.features/tool_agent_class_injection.feature+features/steps/tool_agent_class_injection_steps.pyConfigurationError(factory, executor, andLLMAgent);create_agent()returns custom instance;_execute_tooldispatch instantiates custom subclass; the LLM tool loop instantiates the injected subclass;isinstanceLSP compatibility through the factory; the_execute_llmdispatch path forwardingtool_agent_classtoAgentFactory(single-LLM actor making a tool call); and the_execute_multi_actordispatch path forwardingtool_agent_classto the sub-Executor.instantiation_count=0), confirming they guard the injection contract for the single-LLM and multi-actor paths.Test cleanups (consequence of the dispatch-path changes)
features/steps/runtime_coverage_steps.pyandfeatures/steps/runtime_extended_coverage_steps.py: removed the now-deadpatch("cleveractors.runtime_dispatch.ToolAgent")mocks that no longer intercept_execute_toolafter it switched toexecutor.tool_agent_class.features/steps/credential_executor_paths_steps.py: the_execute_multi_actorcredentials-forwarding scenario interceptsExecutor.__init__with acapturing_initto assert the credentials dict reaches the sub-Executor. Now that_execute_multi_actorforwardstool_agent_classto the sub-Executor,capturing_initaccepts and forwards that keyword so the assertion continues to pass.features/application_coverage_gaps.feature: dropped the obsolete_create_agents registers built-in agent typesscenario since the redundant re-registration it asserted was removed.CHANGELOG.md_execute_tool,_execute_graph,_execute_graph_stream,_execute_llm,_execute_llm_stream,_execute_multi_actor) instead of the earlier "All three dispatch paths" wording.Review Fix Rounds
Round 1 (pre-review):
LLMAgenttool loop now uses the injectedtool_agent_class(was constructing baseToolAgent).application.pyredundantToolAgentregistrations; removed unused imports from the new step file.isinstancescenario into a factory-created LSP check; removed the staleToolAgentimport inruntime_dispatch.py; renamed the_fake_processparameter that shadowed Behave'scontext.Round 2 (this revision):
_execute_llmand_execute_llm_streamnow forwardtool_agent_class=executor.tool_agent_classtoAgentFactory(previously omitted, so single-LLM actors with tools fell back to the baseToolAgent)._execute_multi_actornow forwardstool_agent_class=executor.tool_agent_classto the sub-Executor(previously omitted, so every actor inside a multi-actor bundle fell back to the baseToolAgent).CHANGELOG.mdto list all six dispatch paths accurately._execute_multi_actorcredentials-forwarding test'scapturing_initto accept/forward the newtool_agent_classkeyword.Backward Compatibility
Callers that do not pass
tool_agent_classreceive identical behaviour to the previous release — the default isToolAgentitself. No existing callers are affected.cleveragents-webappMigrationAfter this PR merges, update the webapp call site to:
The five-module
setattrloop and_install_platform_tool_hookmachinery can then be deleted — including for the LLM tool-calling path and the multi-actor path, which are now covered.Quality Gates
nox -e lint: pass ✅nox -e typecheck(pyright strict): 0 errors ✅nox -e unit_tests: 2756 scenarios, 0 failures ✅nox -e coverage_report: 97.0% (threshold 96.5%) ✅nox -e integration_tests: pass ✅Closes #73
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. - Default ToolAgent is preserved, so all existing callers are unaffected. **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: replaces ToolAgent(...) with executor.tool_agent_class(...) 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. **Tests** (features/tool_agent_class_injection.feature + steps): - 13 BDD scenarios covering: default class when parameter omitted; custom subclass stored on factory and executor; invalid class rejected with ConfigurationError; factory create_agent returns custom instance; _execute_tool dispatch instantiates custom subclass; isinstance LSP compatibility. **Updated test** (features/steps/runtime_extended_coverage_steps.py): - _execute_tool now uses executor.tool_agent_class instead of the module-level ToolAgent name; updated the mock strategy from patch('cleveractors.runtime_dispatch.ToolAgent') to patch.object(ToolAgent, 'process_message', ...) so the existing coverage scenario continues to pass. ISSUES CLOSED: #73tool_agent_classparameter toAgentFactoryandcreate_executorto support runtime-injected ToolAgent subclasses #73LGTM ✅ — self-review complete. Implementation is correct, tests pass, CI green, coverage 97.0%.
tool_agent_classparameter toAgentFactoryandcreate_executorto support runtime-injected ToolAgent subclasses20f68e9ae43ead0cc7a83ead0cc7a88ad12ac0758ad12ac0750646b3e958Self-QA Approval
This PR has passed internal self-QA review after 3 review/fix cycles.
Summary
tool_agent_classinjection is correctly implemented acrossAgentFactory,Executor,create_executor, andLLMAgent._execute_tool,_execute_graph,_execute_graph_stream,_execute_llm,_execute_llm_stream,_execute_multi_actor.ToolAgent).Quality Gates
Approved for merge. 🚀
0646b3e9589ec578f229