HAL9000
18d00c04c4
Implements AgentSkillDiscovery class to support discovering Agent Skills from multiple configured directories across three scopes (global, project, local). Handles name collisions with precedence: local > project > global. Adds comprehensive BDD test coverage for multi-scope discovery scenarios including: - Global-only, project-only, and local-only discovery - Combined discovery from all scopes - Name collision resolution with proper precedence - Non-existent and empty scope directory handling - Multiple skills in same scope discovery ISSUES CLOSED: #9369
3.0 KiB
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 definitionsexamples/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. |