cleveractors-core/docs/reference/actor_hierarchy.md

Actor Hierarchy and Advanced YAML Extensions

This document covers the advanced actor YAML schema extensions: per-node LSP bindings, tool-source references, subgraph actor references, and actor-level skill/LSP fields.

Module: cleveractors.actor.schema

Overview

Actor YAML configurations can define multi-node graph workflows. These extensions add fine-grained control over:

Feature	Scope	Purpose
lsp_binding	Per-node	Bind specific LSP servers to individual graph nodes
tool_sources	Per-node	Declare where a node's tools come from (skills, MCP, builtins)
actor_ref	Per-node (subgraph)	Reference another actor by namespaced name
skills	Actor-level	List of skill references available to the actor
lsp	Actor-level	Default LSP server bindings for the actor
lsp_capabilities	Actor-level	Filter which LSP capabilities are exposed
lsp_context_enrichment	Actor-level	Control automatic context injection

Per-Node LSP Binding

Different nodes in a graph can have different LSP configurations:

nodes:
  - id: strategist
    type: agent
    name: Strategy Planner
    description: Plans with read-only LSP
    lsp_binding:
      server: local/pyright
      languages:
        - python
      capabilities:
        - diagnostics
        - hover

  - id: implementer
    type: agent
    name: Implementer
    description: Full LSP auto-binding
    lsp_binding:
      auto: true

NodeLspBinding Fields

Field	Type	Default	Description
server	string	null	Namespaced LSP server name (e.g. local/pyright)
languages	list[string]	[]	Languages for language-based resolution
auto	bool	false	Auto-resolve from project resources
capabilities	list[string]	null	Capability filter for this node

The LspBinding objects extracted from per-node configurations are available on CompiledActor.metadata.lsp_bindings after compilation. The host application is responsible for starting the LSP servers at runtime.

Tool-Source References

Nodes can declare their tool sources explicitly:

nodes:
  - id: executor
    type: agent
    name: Executor
    description: Has multiple tool sources
    tool_sources:
      - type: skill
        name: local/file-ops
      - type: mcp
        name: local/filesystem
      - type: builtin
        group: git_operations

ToolSourceRef Fields

Field	Type	Required	Description
type	string	Yes	skill, mcp, builtin, or custom
name	string	No	Namespaced name (for skill and mcp)
group	string	No	Group identifier (for builtin)

Subgraph Actor References

Subgraph nodes reference other actors by namespaced name using the actor_ref field (not config.actor_path):

nodes:
  - id: review
    type: subgraph
    name: Code Review
    description: Delegates to code-reviewer
    actor_ref: local/code-reviewer

The actor_ref field must be in namespace/name format. The compiler records this reference in CompiledActor.metadata.subgraph_refs for cross-actor cycle detection; the host resolves the actual actor at execution time.

Actor-Level Fields

skills

List of skill references available to the actor and its nodes:

skills:
  - local/file-ops
  - local/git-ops

lsp

Explicit binding (list of server names):

lsp:
  - local/pyright
  - local/clangd

Auto binding:

lsp:
  auto: true

lsp_capabilities

Filter which LSP capabilities are exposed to this actor:

lsp_capabilities:
  - diagnostics
  - hover
  - definitions

Or expose all:

lsp_capabilities: all

lsp_context_enrichment

Control automatic context injection from LSP:

lsp_context_enrichment:
  diagnostics: true
  type_annotations: false
  max_diagnostics_per_file: 50

Validation Error Messages

Validation errors include field-path context:

Error	Example Message
Bad entry node	Entry node 'missing' not found in route.entry_node. Valid node IDs: [a, b]
Bad exit node	Exit node 'missing' not found in route.exit_nodes. Valid node IDs: [a, b]
Bad edge ref	Edge from_node 'ghost' not found at route.edges[0]. Valid node IDs: [a, b]
Duplicate IDs	route.nodes: Duplicate node IDs found: ['dup']. Each node ID must be unique.
Cycle	route: graph contains a cycle involving nodes: [a → b]. Hint: remove or redirect edges.

Complete Example

name: workflows/dev-pipeline
type: graph
description: Multi-agent development pipeline with LSP and tool-source control
version: "1.0"
provider: openai
model: gpt-4

# Actor-level declarations
skills:
  - local/file-ops
  - local/git-ops
lsp:
  - local/pyright
lsp_capabilities:
  - diagnostics
  - hover

route:
  nodes:
    - id: planner
      type: agent
      name: Planner
      description: Plans the implementation strategy
      config:
        model: gpt-4
        prompt: "Analyze requirements and create a plan."
      lsp_binding:
        server: local/pyright
        languages:
          - python
        capabilities:
          - diagnostics
      tool_sources:
        - type: skill
          name: local/file-ops

    - id: implementer
      type: agent
      name: Implementer
      description: Implements the plan
      config:
        model: gpt-4
        prompt: "Implement the changes per the plan."
      lsp_binding:
        auto: true
      tool_sources:
        - type: skill
          name: local/file-ops
        - type: skill
          name: local/git-ops
        - type: mcp
          name: local/filesystem

    - id: reviewer
      type: subgraph
      name: Code Reviewer
      description: Delegates to the code-review actor
      actor_ref: local/code-reviewer

  edges:
    - from_node: planner
      to_node: implementer
    - from_node: implementer
      to_node: reviewer

  entry_node: planner
  exit_nodes:
    - reviewer

See Also

• Actor YAML Schema — full field reference
• Actor Configuration Guide — practical authoring guide
• Actor Compiler — how LSP bindings are extracted during compilation