cleveragents-core/docs/reference/actor_compiler.md

Actor Compiler

The actor compiler translates hierarchical YAML-defined GRAPH actors into LangGraph StateGraph node/edge structures that can be executed by the CleverAgents runtime.

Compilation Pipeline

1. Input validation — The compiler accepts an ActorConfigSchema with type=GRAPH and a populated route field. Non-GRAPH types are rejected with ActorCompilationError.

2. Reference validation — All node IDs referenced in edges, entry, and exit points are checked against the declared node set.

3. Intra-graph cycle detection — The route's detect_cycles() method verifies the node graph is acyclic.

4. Cross-actor subgraph cycle detection — When an optional actor_resolver is provided, the compiler follows SUBGRAPH node references recursively and detects cycles across actor boundaries (e.g. actor A → actor B → actor A).

5. Node mapping — Each NodeDefinition is mapped to a LangGraph NodeConfig with the appropriate NodeType (AGENT, TOOL, CONDITIONAL, SUBGRAPH).

6. Edge mapping — Each EdgeDefinition is mapped to a LangGraph Edge. Conditional expressions are preserved in edge.condition.

7. LSP binding extraction — Per-node lsp_bindings config entries are extracted into LspBinding objects and stored in compilation metadata.

8. Metadata assembly — The compiler returns a CompiledActor containing the node map, edge list, entry point, and a CompilationMetadata object for diagnostics and CLI inspection.

Node Binding

Actor Node Type	LangGraph NodeType	Notes
agent	AGENT	LLM invocation node
tool	TOOL	Tool execution node
conditional	CONDITIONAL	Routing node
subgraph	SUBGRAPH	Nested actor reference

LSP bindings are declared per-node in the config.lsp_bindings list:

nodes:
  - id: coder
    type: agent
    name: Code Writer
    description: Writes Python code
    config:
      agent: coder_agent
      lsp_bindings:
        - lsp_server_name: local/pyright
          languages: [python]
          auto_detect: true

Error Modes

Error	Class	When
Non-GRAPH type	ActorCompilationError	config.type != GRAPH
Missing route	ActorCompilationError	config.route is None
Missing node	MissingNodeError	Edge references unknown node
Invalid entry/exit	InvalidEntryExitError	Entry/exit node not in graph
Intra-graph cycle	SubgraphCycleError	Nodes form a cycle
Cross-actor cycle	SubgraphCycleError	Subgraph refs form a cycle

API Reference

compile_actor(config, *, actor_resolver=None) -> CompiledActor

Compile an ActorConfigSchema into a LangGraph-ready bundle.

Parameters:

• config — The actor configuration (must be ActorType.GRAPH).
• actor_resolver — Optional callable (name: str) -> ActorConfigSchema | None for resolving subgraph references.

Returns: CompiledActor with nodes, edges, and metadata.

CompiledActor

Field	Type	Description
name	str	Actor name
nodes	dict[str, NodeConfig]	LangGraph node configs
edges	list[Edge]	LangGraph edges
entry_point	str	Entry node ID
metadata	CompilationMetadata	Diagnostic metadata

CompilationMetadata

Field	Type	Description
node_ids	list[str]	All node IDs (sorted)
tool_nodes	list[str]	Tool-type node IDs
lsp_bindings	list[LspBinding]	Per-node LSP bindings
subgraph_refs	dict[str, str]	Subgraph node → actor name
entry_node	str	Entry point node ID
exit_nodes	list[str]	Exit point node IDs