forked from HAL9000/cleveragents-core
freemo
f7993d7309
Align actor add/remove/list/show commands to YAML-first configs, namespaced names, and --format json|yaml|plain output support. Changes: - Add --format option to list, show, add, and update commands - Add --update flag to add command for updating existing actors - Add _actor_spec_dict helper for structured output serialization - Update _print_actor to support format_output rendering - Add Behave feature tests for CLI format scenarios (11 scenarios) - Add Robot Framework integration test for show output fields - Add ASV benchmark for actor CLI parsing overhead - Add CLI reference documentation for actor commands ISSUES CLOSED: #288
181 lines
4.1 KiB
Markdown
181 lines
4.1 KiB
Markdown
# Actor CLI Reference
|
|
|
|
The `agents actor` command group manages actor configurations for the
|
|
CleverAgents v3 actor system.
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|--------------------------|----------------------------------------------|
|
|
| `agents actor add` | Add actor from YAML/JSON config file |
|
|
| `agents actor update` | Update an existing actor |
|
|
| `agents actor remove` | Remove a custom actor by namespaced name |
|
|
| `agents actor list` | List all registered actors |
|
|
| `agents actor show` | Show actor details |
|
|
| `agents actor set-default` | Set the default actor |
|
|
| `agents actor run` | Run the reactive network with actor configs |
|
|
|
|
## Namespaced Names
|
|
|
|
Actor names follow the `[[server:]namespace/]name` format. When no
|
|
namespace is provided, the name defaults to `local/`. Built-in actors
|
|
use `<provider>/<model>` (e.g. `openai/gpt-4`).
|
|
|
|
## `agents actor add`
|
|
|
|
Add a new actor from a YAML or JSON configuration file.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
agents actor add <NAME> --config <FILE> [--update] [--unsafe] [--set-default] [--option key=value] [--format FORMAT]
|
|
```
|
|
|
|
### YAML Configuration File
|
|
|
|
```yaml
|
|
provider: openai
|
|
model: gpt-4
|
|
temperature: 0.7
|
|
max_tokens: 1024
|
|
options:
|
|
stream: true
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Add an actor from YAML config
|
|
agents actor add local/my-actor --config ./actors/my-actor.yaml
|
|
|
|
# Add or update an existing actor
|
|
agents actor add local/my-actor --config ./actors/my-actor.yaml --update
|
|
|
|
# Add with option overrides
|
|
agents actor add local/my-actor --config actor.yaml --option temperature=0.9
|
|
|
|
# Add with JSON output
|
|
agents actor add local/my-actor --config actor.yaml --format json
|
|
```
|
|
|
|
## `agents actor update`
|
|
|
|
Update an existing actor configuration.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
agents actor update <NAME> [--config <FILE>] [--unsafe|--safe] [--set-default] [--option key=value] [--format FORMAT]
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Update actor with new config
|
|
agents actor update local/my-actor --config ./actors/updated.yaml
|
|
|
|
# Mark actor as safe
|
|
agents actor update local/my-actor --safe
|
|
|
|
# Update with JSON output
|
|
agents actor update local/my-actor --format json
|
|
```
|
|
|
|
## `agents actor remove`
|
|
|
|
Remove a custom actor by its namespaced name.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
agents actor remove <NAME>
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
agents actor remove local/my-actor
|
|
```
|
|
|
|
## `agents actor list`
|
|
|
|
List all registered actors.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
agents actor list [--format FORMAT]
|
|
```
|
|
|
|
### Output Formats
|
|
|
|
| Format | Description |
|
|
|---------|--------------------------------------|
|
|
| `rich` | Rich table with colours (default) |
|
|
| `json` | JSON array of actor objects |
|
|
| `yaml` | YAML list of actor objects |
|
|
| `plain` | Plain text key-value pairs |
|
|
| `table` | ASCII table without Rich styling |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Default rich table
|
|
agents actor list
|
|
|
|
# JSON output for scripting
|
|
agents actor list --format json
|
|
|
|
# YAML output
|
|
agents actor list --format yaml
|
|
```
|
|
|
|
## `agents actor show`
|
|
|
|
Show details for a specific actor.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
agents actor show <NAME> [--format FORMAT]
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Rich panel (default)
|
|
agents actor show local/my-actor
|
|
|
|
# JSON output
|
|
agents actor show local/my-actor --format json
|
|
|
|
# YAML output
|
|
agents actor show openai/gpt-4 --format yaml
|
|
```
|
|
|
|
## `agents actor set-default`
|
|
|
|
Set the default actor used when no actor is specified.
|
|
|
|
### Synopsis
|
|
|
|
```bash
|
|
agents actor set-default <NAME>
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
agents actor set-default openai/gpt-4
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
| Error | Cause |
|
|
|----------------------------|------------------------------------------|
|
|
| `Config file not found` | Specified config file doesn't exist |
|
|
| `Config must be a JSON/YAML object` | Config file is not a valid object |
|
|
| `Config file is required` | No `--config` flag provided for `add` |
|
|
| `Actor config is marked unsafe` | Unsafe config without `--unsafe` flag |
|
|
| `Actor not found` | Named actor doesn't exist |
|