cleveragents-core/docs/api/actor.md

cleveragents.actor — Actor System

The actor package provides the actor registry, YAML configuration schema, loader, and compiler. Actors are the primary execution units in CleverAgents — they encapsulate an LLM, a set of tools, and a LangGraph execution graph.

See ADR-010 and ADR-031 for design rationale.

!!! note "Lazy imports" The actor package uses lazy imports to avoid pulling in heavy transitive dependencies (LangChain, LangSmith, SQLAlchemy) when only lightweight submodules such as role_validation or schema are needed.

---

ActorConfiguration

from cleveragents.actor import ActorConfiguration

Pydantic model representing a fully-parsed actor YAML file. Key fields:

Field	Type	Description
name	str	Actor identifier (namespaced, e.g. openai/gpt-4o)
entry_node	str	Graph entry node name
nodes	dict[str, NodeConfig]	Node definitions
edges	list[EdgeConfig]	Graph edges
lsp_binding	LSPBinding | None	Per-node LSP server binding
tool_sources	list[str]	Tool source references

---

ActorLoader

from cleveragents.actor import ActorLoader

loader = ActorLoader()
actors = loader.discover(Path("./actors/"))

Discovers and loads actor YAML files from a directory tree. Validates graph reachability (all nodes reachable from entry_node) and reports YAML line/column positions on error.

Methods

Method	Description
discover(path)	Scan directory for actor YAML files
load(path)	Load a single actor YAML file
validate(config)	Validate an ActorConfiguration

---

ActorRegistry

from cleveragents.actor import ActorRegistry

registry = ActorRegistry()
registry.register(actor_config)
actor = registry.get("openai/gpt-4o")

In-memory registry for actor configurations. Thread-safe.

ActorRegistry.add() — YAML-first persistence path

The agents actor add CLI command routes through ActorRegistry.add() to ensure the original YAML text, schema_version, and compiled_metadata are preserved in the database.

registry.add(yaml_text="name: openai/gpt-4o\n...", update=False)

Parameter	Type	Description
yaml_text	str	Raw YAML text of the actor configuration
update	bool	When True, overwrite an existing actor with the same name

Note: The legacy registry.upsert_actor() path is still available for programmatic use but is no longer called by the CLI. Use registry.add() for all new code that needs to persist actor configurations.

---

compile_actor / CompiledActor

from cleveragents.actor import compile_actor, CompiledActor

compiled: CompiledActor = compile_actor(actor_config, tool_registry)

Compiles an ActorConfiguration into a runnable CompiledActor by resolving tool bindings, building the LangGraph state machine, and attaching LSP/MCP adapters.

CompilationMetadata

Carries diagnostics from the compilation step: resolved tools, skipped nodes, and any warnings.

---

Compilation Errors

Exception	Description
ActorCompilationError	General compilation failure
MissingNodeError	Referenced node not defined
InvalidEntryExitError	Entry/exit node configuration invalid
SubgraphCycleError	Cycle detected in subgraph references

---

Example: Loading and Compiling an Actor

from pathlib import Path
from cleveragents.actor import ActorLoader, compile_actor
from cleveragents.tool import ToolRegistry

loader = ActorLoader()
config = loader.load(Path("examples/actors/graph_workflow.yaml"))

tool_registry = ToolRegistry()
compiled = compile_actor(config, tool_registry)