feat(actor): integrate compiled actors into subplan workflow execution #8994

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

Background and Context

Epic #392 covers the Actor YAML & Compiler pipeline. While #157 defines the YAML schema and #158 implements the compiler, neither issue addresses the integration of compiled actors into the subplan workflow execution engine. Actors must be resolvable by name during plan execution so that actions can reference custom actors (strategy, execution, estimation roles) and have them executed via the compiled LangGraph StateGraph. Without this integration, compiled actors exist in isolation and cannot participate in real plan workflows.

Expected Behavior

When this issue is complete:

  • Actions in a plan can reference custom actors by name (e.g., actor: my-custom-strategy-actor)
  • The plan executor resolves actor references to compiled LangGraph StateGraphs at execution time
  • If an actor reference cannot be resolved, execution fails with a clear error message identifying the missing actor
  • Subplan workflows correctly route through compiled actor graphs, respecting entry/exit points and LSP bindings
  • The integration is covered by Behave unit tests and Robot Framework integration smoke tests

Acceptance Criteria

  • Actions in a plan YAML can specify a custom actor by name via an actor: field
  • The plan executor resolves actor: references to compiled LangGraph StateGraphs from the actor registry
  • Unresolvable actor references produce a clear error message at execution time (not at compile time)
  • Subplan workflows correctly route through compiled actor graphs, respecting entry/exit points
  • LSP bindings defined in the actor YAML are applied per-node during subplan execution
  • Behave scenarios cover: successful actor resolution, missing actor error, multi-node actor graph execution
  • Robot Framework smoke test validates end-to-end: define actor YAML → agents actor add → run plan referencing actor
  • docs/reference/actor_compiler.md is updated with subplan integration documentation
  • Test coverage >= 97% via nox -s coverage_report

Subtasks

  • Add actor: field to action schema and plan YAML parser
  • Implement actor resolution in the plan executor (lookup compiled StateGraph from actor registry)
  • Add error handling for unresolvable actor references with clear error messages
  • Wire LSP bindings from compiled actor metadata into subplan node execution
  • Write Behave scenarios for actor resolution success, missing actor error, and multi-node graph execution
  • Write Robot Framework smoke test for end-to-end actor workflow (define → add → plan → execute)
  • Update docs/reference/actor_compiler.md with subplan integration section
  • Run nox (all default sessions) and fix any errors
  • Verify coverage >= 97% via nox -s coverage_report

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: feat(actor): integrate compiled actors into subplan workflow execution
  • Branch name: feat/actor-subplan-workflow-integration

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

## Background and Context Epic #392 covers the Actor YAML & Compiler pipeline. While #157 defines the YAML schema and #158 implements the compiler, neither issue addresses the integration of compiled actors into the subplan workflow execution engine. Actors must be resolvable by name during plan execution so that actions can reference custom actors (strategy, execution, estimation roles) and have them executed via the compiled LangGraph StateGraph. Without this integration, compiled actors exist in isolation and cannot participate in real plan workflows. ## Expected Behavior When this issue is complete: - Actions in a plan can reference custom actors by name (e.g., `actor: my-custom-strategy-actor`) - The plan executor resolves actor references to compiled LangGraph StateGraphs at execution time - If an actor reference cannot be resolved, execution fails with a clear error message identifying the missing actor - Subplan workflows correctly route through compiled actor graphs, respecting entry/exit points and LSP bindings - The integration is covered by Behave unit tests and Robot Framework integration smoke tests ## Acceptance Criteria - [ ] Actions in a plan YAML can specify a custom actor by name via an `actor:` field - [ ] The plan executor resolves `actor:` references to compiled LangGraph StateGraphs from the actor registry - [ ] Unresolvable actor references produce a clear error message at execution time (not at compile time) - [ ] Subplan workflows correctly route through compiled actor graphs, respecting entry/exit points - [ ] LSP bindings defined in the actor YAML are applied per-node during subplan execution - [ ] Behave scenarios cover: successful actor resolution, missing actor error, multi-node actor graph execution - [ ] Robot Framework smoke test validates end-to-end: define actor YAML → `agents actor add` → run plan referencing actor - [ ] `docs/reference/actor_compiler.md` is updated with subplan integration documentation - [ ] Test coverage >= 97% via `nox -s coverage_report` ## Subtasks - [ ] Add `actor:` field to action schema and plan YAML parser - [ ] Implement actor resolution in the plan executor (lookup compiled StateGraph from actor registry) - [ ] Add error handling for unresolvable actor references with clear error messages - [ ] Wire LSP bindings from compiled actor metadata into subplan node execution - [ ] Write Behave scenarios for actor resolution success, missing actor error, and multi-node graph execution - [ ] Write Robot Framework smoke test for end-to-end actor workflow (define → add → plan → execute) - [ ] Update `docs/reference/actor_compiler.md` with subplan integration section - [ ] Run `nox` (all default sessions) and fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## 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:** `feat(actor): integrate compiled actors into subplan workflow execution` - **Branch name:** `feat/actor-subplan-workflow-integration` --- **Automated by CleverAgents Bot** Supervisor: Epic Planning Pool | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.2.0 milestone 2026-04-14 04:45:30 +00:00
Author
Owner

Verified — Actor integration into subplan workflow is a v3.2.0 deliverable. MoSCoW: Must-have. Priority: Medium.


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

✅ **Verified** — Actor integration into subplan workflow is a v3.2.0 deliverable. 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.

Blocks
#392 Epic: Actor YAML & Compiler
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#8994
No description provided.