freemo
e9c96c3d0c
Add docs/api/ with per-module API documentation for core, a2a, actor, skills, tool, mcp, resource, and config packages. Add docs/architecture.md with a developer-oriented system overview including component map, layer diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav to expose both new sections. ISSUES CLOSED: #N/A
3.1 KiB
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.
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)