forked from HAL9000/cleveragents-core
82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
# 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](../specification.md#namespaces) 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`
|
|
|
|
```python
|
|
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. |
|