fix(actor): Implement GRAPH actor subgraph and tool node execution (fixes #5467, #5462) #8984

Open
opened 2026-04-14 04:35:12 +00:00 by HAL9000 · 1 comment
Owner

Background and Context

The GRAPH actor system has two critical stub implementations that make hierarchical actor composition and tool-based workflow nodes completely non-functional:

  1. _execute_subgraph() is a stub (UAT #5467): Returns a fake {"subgraph_invoked": "..."} response instead of resolving, compiling, and executing the referenced nested actor. This breaks the entire "Actor Composition (Hierarchical References)" feature.

  2. _execute_tool() is a stub (UAT #5462): Returns a hardcoded {"tool_executed": True} response instead of looking up and invoking the configured tool from the Tool Registry. This breaks all GRAPH actor workflows that depend on tool nodes.

Both are core v3.5.0 deliverables under Epic #5502.

Parent Epic: #5502 (EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance)

Acceptance Criteria

  • _execute_subgraph() resolves the referenced actor by name from the Actor Registry
  • _execute_subgraph() compiles the referenced actor using compile_actor() and executes it as a nested LangGraph
  • _execute_subgraph() returns the nested graph's actual output state
  • _execute_tool() reads self.config.tools and looks up each tool in the Tool Registry
  • _execute_tool() invokes the tool with parameters from self.config.metadata and returns actual tool output
  • Cycle detection in _detect_subgraph_cycles() continues to work correctly
  • All nox stages pass with coverage >= 97%

Subtasks

  • Implement _execute_subgraph() in src/cleveragents/langgraph/nodes.py:
    • Read self.config.subgraph for the referenced actor name
    • Look up actor in Actor Registry
    • Compile actor using compile_actor()
    • Create LangGraph instance and execute with current state
    • Return nested graph output state
  • Implement _execute_tool() in src/cleveragents/langgraph/nodes.py:
    • Read self.config.tools for tool names
    • Look up each tool in Tool Registry
    • Invoke tool with parameters from self.config.metadata
    • Return actual tool output
  • Write unit tests for _execute_subgraph() with mock Actor Registry
  • Write unit tests for _execute_tool() with mock Tool Registry
  • Write integration tests for multi-level actor composition
  • Run nox (all default sessions), fix any errors

Definition of Done

  • All acceptance criteria met
  • Tests written and passing (coverage >= 97%)
  • Code reviewed and approved
  • Documentation updated if needed
  • No regressions introduced

Metadata

  • Commit message: fix(actor): implement GRAPH actor subgraph and tool node execution
  • Branch name: fix/v350/actor-graph-node-execution

Automated by CleverAgents Bot
Supervisor: Epic Planning Pool | Agent: epic-planning-pool-supervisor

## Background and Context The GRAPH actor system has two critical stub implementations that make hierarchical actor composition and tool-based workflow nodes completely non-functional: 1. **`_execute_subgraph()` is a stub** (UAT #5467): Returns a fake `{"subgraph_invoked": "..."}` response instead of resolving, compiling, and executing the referenced nested actor. This breaks the entire "Actor Composition (Hierarchical References)" feature. 2. **`_execute_tool()` is a stub** (UAT #5462): Returns a hardcoded `{"tool_executed": True}` response instead of looking up and invoking the configured tool from the Tool Registry. This breaks all GRAPH actor workflows that depend on tool nodes. Both are core v3.5.0 deliverables under Epic #5502. Parent Epic: #5502 (EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance) ## Acceptance Criteria - [ ] `_execute_subgraph()` resolves the referenced actor by name from the Actor Registry - [ ] `_execute_subgraph()` compiles the referenced actor using `compile_actor()` and executes it as a nested LangGraph - [ ] `_execute_subgraph()` returns the nested graph's actual output state - [ ] `_execute_tool()` reads `self.config.tools` and looks up each tool in the Tool Registry - [ ] `_execute_tool()` invokes the tool with parameters from `self.config.metadata` and returns actual tool output - [ ] Cycle detection in `_detect_subgraph_cycles()` continues to work correctly - [ ] All nox stages pass with coverage >= 97% ## Subtasks - [ ] Implement `_execute_subgraph()` in `src/cleveragents/langgraph/nodes.py`: - Read `self.config.subgraph` for the referenced actor name - Look up actor in Actor Registry - Compile actor using `compile_actor()` - Create `LangGraph` instance and execute with current state - Return nested graph output state - [ ] Implement `_execute_tool()` in `src/cleveragents/langgraph/nodes.py`: - Read `self.config.tools` for tool names - Look up each tool in Tool Registry - Invoke tool with parameters from `self.config.metadata` - Return actual tool output - [ ] Write unit tests for `_execute_subgraph()` with mock Actor Registry - [ ] Write unit tests for `_execute_tool()` with mock Tool Registry - [ ] Write integration tests for multi-level actor composition - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] All acceptance criteria met - [ ] Tests written and passing (coverage >= 97%) - [ ] Code reviewed and approved - [ ] Documentation updated if needed - [ ] No regressions introduced ## Metadata - **Commit message:** `fix(actor): implement GRAPH actor subgraph and tool node execution` - **Branch name:** `fix/v350/actor-graph-node-execution` --- **Automated by CleverAgents Bot** Supervisor: Epic Planning Pool | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.5.0 milestone 2026-04-14 04:44:57 +00:00
Author
Owner

Verified — GRAPH actor subgraph/tool node execution is required for actor functionality. MoSCoW: Must-have. Priority: Medium.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — GRAPH actor subgraph/tool node execution is required for actor functionality. MoSCoW: Must-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#8984
No description provided.