Actor Loading and Discovery

The actor loader discovers, validates, and caches actor YAML configuration files from configurable search roots.

Discovery Rules

The ActorLoader scans one or more search root directories for actor YAML files:

Rule	Detail
File extensions	Only `.yaml` and `.yml` files are loaded
Recursive scan	Subdirectories are scanned recursively
Non-YAML ignored	Files with other extensions (`.json`, `.txt`, etc.) are silently skipped
Invalid YAML rejected	Files that fail YAML parsing or schema validation raise `ValidationError`

Search Roots

Search roots are directories passed to the loader at construction time. Common roots include:

actors/ — project-level actor definitions
examples/actors/ — example actor files shipped with CleverAgents

Namespace Handling

All actors must have a namespaced name in <namespace>/<name> format.

Input	Result
`assistants/reviewer`	Kept as-is
`my-agent` (no slash)	Automatically becomes `local/my-agent`

The local/ namespace is the default for local-only actors. See the Namespace System for the full namespace hierarchy.

Duplicate Detection

When the same actor name appears in multiple files (within a single search root or across roots), the loader emits a single consolidated error listing all conflicting file paths:

Actor discovery failed:
Duplicate actor 'assistants/writer' found in: /path/a/writer.yaml, /path/b/writer.yaml

Content Hash Caching

The loader caches loaded actors using a SHA-256 content hash to avoid redundant parsing:

Condition	Behavior
File content unchanged	Actor is served from cache (no re-parse)
File content modified	Actor is re-parsed and cache is updated
File deleted	Actor is removed from cache on next discovery

This means calling discover() multiple times is efficient — only changed files trigger re-parsing.

Tool Registry Integration

When a ToolRegistry is provided, the loader verifies tool references at load time:

Resolved tools: Tool references that exist in the registry are validated silently.
Unresolved tools: Missing tool references emit a warning but do not block loading. This allows actors to be loaded before all tools are registered.

API Reference

`ActorLoader`

from cleveragents.actor.loader import ActorLoader

loader = ActorLoader(
    search_roots=[Path("actors/"), Path("examples/actors/")],
    tool_registry=tool_registry,  # optional
)

Method	Description
`discover()`	Scan search roots and load/reload actors. Returns list of `ActorConfigSchema`.
`get(name)`	Retrieve a loaded actor by namespaced name. Returns `None` if not found.
`list_actors(namespace=None)`	List actors with optional namespace filter.
`clear()`	Drop all cached actors and content hashes.
`warnings`	List of warnings emitted during the last discovery run.

3.0 KiB Raw Blame History