cleveragents/cleveragents-core

Fork 3

UAT: SUBGRAPH node config uses `actor_ref` key but spec defines `actor_path` for subgraph node configuration #4756

New issue

Open

opened 2026-04-08 18:53:40 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 18:53:40 +00:00

Owner

Bug Report

Feature Area: Actor YAML schema — graph node configuration / LangGraph composition
Severity: Medium
Found by: UAT tester instance uat-worker-actor-yaml
Spec reference: docs/specification.md §Route Configuration (line 20531–20578), §Node type-specific config (line 20552–20559)

What Was Tested

Code-level analysis of src/cleveragents/actor/schema.py and src/cleveragents/actor/compiler.py — the SUBGRAPH node configuration field name.

Expected Behavior (from spec)

The spec (line 20552–20559) defines the node type-specific config for SUBGRAPH nodes as:

Node Type	Config Fields	Description
`subgraph`	`actor_path`	Embeds another actor as a nested workflow

The spec uses actor_path as the config key for subgraph nodes.

Actual Behavior

The implementation uses actor_ref instead of actor_path in multiple places:

src/cleveragents/actor/schema.py (line 418):

# NodeDefinition docstring shows:
SUBGRAPH: {"actor_path": "path/to/actor.yaml"}  # ← docstring says actor_path

But the actual field and all code uses actor_ref:

actor_ref: str | None = Field(
    default=None,
    description="Namespaced actor reference for subgraph nodes",
)

src/cleveragents/actor/compiler.py (lines 140, 197, 293):

subgraph=(config.get("actor_ref") if node.type == NodeType.SUBGRAPH else None),
ref_name = node.config.get("actor_ref", "")
ref = node_def.config.get("actor_ref", "")

The docstring in NodeDefinition (line 418) even shows actor_path as the correct key, but the implementation uses actor_ref everywhere. This creates a documentation/implementation mismatch.

Additionally, the spec's actor_path implies a file path reference (e.g., "path/to/actor.yaml"), while the implementation's actor_ref uses a namespaced actor name (e.g., "local/my-actor"). The spec's description says "Embeds another actor as a nested workflow" which is consistent with a namespaced name, but the field name actor_path suggests a file path.

Code Locations

Schema: src/cleveragents/actor/schema.py lines 418, 451–472
Compiler: src/cleveragents/actor/compiler.py lines 140, 197, 293
Spec: docs/specification.md line 20559

Impact

Users writing YAML actor configs with actor_path in subgraph node configs (following the spec) will have their subgraph references silently ignored
The compiler will not resolve subgraph references when users use the spec-documented actor_path key
The docstring in NodeDefinition contradicts the actual field name, causing confusion

Example

A user following the spec would write:

route:
  nodes:
    - id: nested_workflow
      type: subgraph
      name: Nested Workflow
      description: Runs a nested actor
      config:
        actor_path: local/my-nested-actor  # ← spec says actor_path

But the implementation only recognizes:

      config:
        actor_ref: local/my-nested-actor  # ← implementation uses actor_ref

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Actor YAML schema — graph node configuration / LangGraph composition **Severity:** Medium **Found by:** UAT tester instance `uat-worker-actor-yaml` **Spec reference:** docs/specification.md §Route Configuration (line 20531–20578), §Node type-specific config (line 20552–20559) --- ### What Was Tested Code-level analysis of `src/cleveragents/actor/schema.py` and `src/cleveragents/actor/compiler.py` — the SUBGRAPH node configuration field name. ### Expected Behavior (from spec) The spec (line 20552–20559) defines the node type-specific config for SUBGRAPH nodes as: | Node Type | Config Fields | Description | |-----------|---------------|-------------| | `subgraph` | `actor_path` | Embeds another actor as a nested workflow | The spec uses `actor_path` as the config key for subgraph nodes. ### Actual Behavior The implementation uses `actor_ref` instead of `actor_path` in multiple places: **`src/cleveragents/actor/schema.py` (line 418):** ```python # NodeDefinition docstring shows: SUBGRAPH: {"actor_path": "path/to/actor.yaml"} # ← docstring says actor_path ``` But the actual field and all code uses `actor_ref`: ```python actor_ref: str | None = Field( default=None, description="Namespaced actor reference for subgraph nodes", ) ``` **`src/cleveragents/actor/compiler.py` (lines 140, 197, 293):** ```python subgraph=(config.get("actor_ref") if node.type == NodeType.SUBGRAPH else None), ref_name = node.config.get("actor_ref", "") ref = node_def.config.get("actor_ref", "") ``` The docstring in `NodeDefinition` (line 418) even shows `actor_path` as the correct key, but the implementation uses `actor_ref` everywhere. This creates a documentation/implementation mismatch. Additionally, the spec's `actor_path` implies a file path reference (e.g., `"path/to/actor.yaml"`), while the implementation's `actor_ref` uses a namespaced actor name (e.g., `"local/my-actor"`). The spec's description says "Embeds another actor as a nested workflow" which is consistent with a namespaced name, but the field name `actor_path` suggests a file path. ### Code Locations - **Schema:** `src/cleveragents/actor/schema.py` lines 418, 451–472 - **Compiler:** `src/cleveragents/actor/compiler.py` lines 140, 197, 293 - **Spec:** docs/specification.md line 20559 ### Impact - Users writing YAML actor configs with `actor_path` in subgraph node configs (following the spec) will have their subgraph references silently ignored - The compiler will not resolve subgraph references when users use the spec-documented `actor_path` key - The docstring in `NodeDefinition` contradicts the actual field name, causing confusion ### Example A user following the spec would write: ```yaml route: nodes: - id: nested_workflow type: subgraph name: Nested Workflow description: Runs a nested actor config: actor_path: local/my-nested-actor # ← spec says actor_path ``` But the implementation only recognizes: ```yaml config: actor_ref: local/my-nested-actor # ← implementation uses actor_ref ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 18:59:36 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4743

HAL9000 added the

labels

2026-04-08 23:00:39 +00:00

HAL9000 commented

2026-04-09 03:04:59 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:05:09 +00:00

HAL9000 added this to the v3.5.0 milestone