temp/docs/showcase/cli-tools/actor-management-workflow.md

Managing AI Actors with the CleverAgents CLI

Overview

CleverAgents uses an actor-first model where every AI interaction is mediated by a named actor — a configuration bundle that pairs a provider (OpenAI, Anthropic, Google, etc.) with a specific model and optional settings. This guide walks through the complete actor management lifecycle: listing built-in actors, inspecting their capabilities, adding a custom actor, switching the default, and cleaning up — all from the command line.

Prerequisites

• CleverAgents installed (pip install cleveragents or from source with uv sync)
• Python 3.13 or higher

What You'll Learn

• How to list all available actors in rich table and JSON/YAML formats
• How to inspect a specific actor's capabilities and configuration
• How to add a custom actor from a YAML config file
• How to switch the active default actor
• How to update actor options without replacing the full config
• How to safely remove a custom actor (with impact reporting)
• The naming convention: built-ins use <provider>/<model>, custom actors use local/<id>

---

Step-by-Step Walkthrough

Step 1: Explore the Actor Subcommand

Start by seeing what actor management commands are available:

$ python -m cleveragents actor --help

Actual Output:

 Usage: python -m cleveragents actor [OPTIONS] COMMAND [ARGS]...

 Actor management (built-ins <provider>/<model>; customs local/<id>; unsafe
 requires --unsafe)

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ run          Run the reactive network once with actor-first configs.         │
│ add          Add a new actor configuration.                                  │
│ update       Update an existing actor.                                       │
│ remove       Remove a custom actor.                                          │
│ list         List all actors.                                                │
│ show         Show details for an actor.                                      │
│ set-default  Set the default actor.                                          │
│ context      Actor context management commands                               │
╰──────────────────────────────────────────────────────────────────────────────╯

What's Happening: The actor group exposes eight subcommands covering the full actor lifecycle. The naming convention is enforced at the CLI level: built-in actors are addressed as <provider>/<model> (e.g. openai/gpt-4o), while custom actors you register yourself use the local/<id> namespace.

---

Step 2: List All Actors (Rich Table)

$ python -m cleveragents actor list

Actual Output:

                                Actors (5 total)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                            ┃ Provider    ┃ Model                                    ┃ Default ┃ Built-in ┃ Unsafe ┃ Updated                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ anthropic/claude-sonnet-4-20250514              │ Anthropic   │ claude-sonnet-4-20250514                 │         │    ✓     │   no   │ 2026-04-06 06:58:24.126927 │
│ gemini/gemini-2.0-flash                         │ Gemini      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-06 06:58:24.164135 │
│ google/gemini-2.0-flash                         │ Google      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-06 06:58:24.145584 │
│ openai/gpt-4o                                   │ Openai      │ gpt-4o                                   │    ✓    │    ✓     │   no   │ 2026-04-06 06:58:24.209040 │
│ openrouter/anthropic-claude-sonnet-4-20250514   │ Openrouter  │ anthropic/claude-sonnet-4-20250514       │         │    ✓     │   no   │ 2026-04-06 06:58:24.186643 │
└─────────────────────────────────────────────────┴─────────────┴──────────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘
╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Total: 5                                                                     │
│ Built-in: 5                                                                  │
│ Custom: 0                                                                    │
│ Unsafe: 0                                                                    │
│ Providers Used: 5                                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK 5 actors listed

What's Happening: The list command queries the actor registry and renders a Rich table with seven columns. The ✓ in the Default column marks the actor that will be used when no actor is explicitly specified. The Summary panel gives a quick breakdown of total, built-in, custom, unsafe, and provider counts.

---

Step 3: List Actors in JSON Format (for Scripting)

$ python -m cleveragents actor list --format json

Actual Output (abbreviated):

{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": [
    {
      "name": "anthropic/claude-sonnet-4-20250514",
      "provider": "Anthropic",
      "model": "claude-sonnet-4-20250514",
      "unsafe": false,
      "is_default": false,
      "is_built_in": true,
      "config_hash": "f50baf2f771ee21ebe4977239fef62dbd8b9514b218eb8173e62e463e10c86c1",
      "schema_version": "1.0",
      "updated_at": "2026-04-06T06:58:24.126927",
      "graph_descriptor": {
        "provider": "Anthropic",
        "model": "claude-sonnet-4-20250514",
        "source": "provider-registry",
        "capabilities": {
          "supports_streaming": true,
          "supports_tool_calls": true,
          "supports_vision": true,
          "max_context_length": 200000,
          "supports_json_mode": false
        }
      }
    },
    {
      "name": "openai/gpt-4o",
      "provider": "Openai",
      "model": "gpt-4o",
      "unsafe": false,
      "is_default": true,
      "is_built_in": true,
      "config_hash": "757c93dd5d9699f7e7c770ddef09ded5ef02d3b011cf654b719cc70ae781c02a",
      "schema_version": "1.0",
      "updated_at": "2026-04-06T06:58:24.209040",
      "graph_descriptor": {
        "provider": "Openai",
        "model": "gpt-4o",
        "source": "provider-registry",
        "capabilities": {
          "supports_streaming": true,
          "supports_tool_calls": true,
          "supports_vision": true,
          "max_context_length": 128000,
          "supports_json_mode": true
        }
      }
    }
  ],
  "timing": { "duration_ms": 0 },
  "messages": [{ "level": "ok", "text": "ok" }]
}

What's Happening: The --format json flag wraps the actor list in the standard CleverAgents output envelope. The data array contains one object per actor with full capability metadata from the provider registry — including max_context_length, supports_streaming, supports_tool_calls, supports_vision, and supports_json_mode. This is ideal for scripting: pipe to jq to filter actors by capability.

Tip: --format yaml and --format plain are also supported for different scripting needs.

---

Step 4: Inspect a Specific Actor

$ python -m cleveragents actor show openai/gpt-4o

Actual Output:

╭─── Actor details ───╮
│ Name: openai/gpt-4o │
│ Provider: Openai    │
│ Model: gpt-4o       │
│ Default: yes        │
│ Unsafe: no          │
│ Type:               │
╰─────────────────────╯

$ python -m cleveragents actor show anthropic/claude-sonnet-4-20250514

Actual Output:

╭───────────── Actor details ──────────────╮
│ Name: anthropic/claude-sonnet-4-20250514 │
│ Provider: Anthropic                      │
│ Model: claude-sonnet-4-20250514          │
│ Default: no                              │
│ Unsafe: no                               │
│ Type:                                    │
╰──────────────────────────────────────────╯

For full machine-readable detail including capabilities:

$ python -m cleveragents actor show openai/gpt-4o --format json

Actual Output:

{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "name": "openai/gpt-4o",
    "provider": "Openai",
    "model": "gpt-4o",
    "unsafe": false,
    "is_default": true,
    "is_built_in": true,
    "config_hash": "757c93dd5d9699f7e7c770ddef09ded5ef02d3b011cf654b719cc70ae781c02a",
    "schema_version": "1.0",
    "updated_at": "2026-04-07T09:04:14.227024",
    "graph_descriptor": {
      "provider": "Openai",
      "model": "gpt-4o",
      "source": "provider-registry",
      "capabilities": {
        "supports_streaming": true,
        "supports_tool_calls": true,
        "supports_vision": true,
        "max_context_length": 128000,
        "supports_json_mode": true
      }
    },
    "config_blob": {
      "provider": "Openai",
      "model": "gpt-4o",
      "capabilities": {
        "supports_streaming": true,
        "supports_tool_calls": true,
        "supports_vision": true,
        "max_context_length": 128000,
        "supports_json_mode": true
      },
      "unsafe": false,
      "source": "provider-registry"
    }
  },
  "timing": { "duration_ms": 0 },
  "messages": [{ "level": "ok", "text": "ok" }]
}

What's Happening: actor show retrieves a single actor from the registry by its namespaced name. The JSON output exposes the full config_blob and graph_descriptor, which is useful for understanding exactly what capabilities the actor advertises to the system.

---

Step 5: Add a Custom Actor

Custom actors live in the local/ namespace and are backed by a YAML configuration file. Create a minimal config:

$ cat > my-haiku-actor.yaml << 'EOF'
provider: Anthropic
model: claude-3-5-haiku-20241022
unsafe: false
EOF

Then register it:

$ python -m cleveragents actor add local/my-haiku-actor --config my-haiku-actor.yaml

Actual Output:

╭────────── Actor added ───────────╮
│ Name: local/my-haiku-actor       │
│ Provider: Anthropic              │
│ Model: claude-3-5-haiku-20241022 │
│ Default: no                      │
│ Unsafe: no                       │
│ Type:                            │
╰──────────────────────────────────╯
╭──────────────────────────────── Config ────────────────────────────────╮
│ Path: /path/to/my-haiku-actor.yaml                                     │
│ Hash: 4ec6313ba1c7aca3e1d01065c9b799e425c8942f2be9f8705bad0d9a727fa0fc │
│ Options: 0                                                             │
│ Nodes: 0                                                               │
│ Edges: 0                                                               │
╰────────────────────────────────────────────────────────────────────────╯
✓ OK Actor added

What's Happening: The add command:

1. Reads and validates the YAML config against the actor schema
2. Computes a SHA-256 config_hash for change detection
3. Persists the actor to the registry database
4. Renders an Actor added panel plus a Config panel showing the file path, hash, and graph topology counts (nodes/edges — relevant for multi-agent graph actors)

The --format json flag is also supported for scripting:

$ python -m cleveragents actor add local/my-haiku-actor --config my-haiku-actor.yaml --format json

Note: Re-running add on an existing actor name will fail with an error panel. Use --update to replace an existing actor definition.

---

Step 6: Verify the Actor Appears in the List

$ python -m cleveragents actor list

Actual Output:

                                Actors (6 total)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                            ┃ Provider    ┃ Model                                    ┃ Default ┃ Built-in ┃ Unsafe ┃ Updated                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ anthropic/claude-sonnet-4-20250514              │ Anthropic   │ claude-sonnet-4-20250514                 │         │    ✓     │   no   │ 2026-04-07 09:04:40        │
│ gemini/gemini-2.0-flash                         │ Gemini      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-07 09:04:40        │
│ google/gemini-2.0-flash                         │ Google      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-07 09:04:40        │
│ local/my-haiku-actor                            │ Anthropic   │ claude-3-5-haiku-20241022                │         │          │   no   │ 2026-04-07 09:04:40        │
│ openai/gpt-4o                                   │ Openai      │ gpt-4o                                   │    ✓    │    ✓     │   no   │ 2026-04-07 09:04:40        │
│ openrouter/anthropic-claude-sonnet-4-20250514   │ Openrouter  │ anthropic/claude-sonnet-4-20250514       │         │    ✓     │   no   │ 2026-04-07 09:04:40        │
└─────────────────────────────────────────────────┴─────────────┴──────────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘
╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Total: 6                                                                     │
│ Built-in: 5                                                                  │
│ Custom: 1                                                                    │
│ Unsafe: 0                                                                    │
│ Providers Used: 5                                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK 6 actors listed

What's Happening: The custom actor local/my-haiku-actor now appears in the list. Notice it has no ✓ in the Built-in column — custom actors are user-managed and can be removed, unlike built-ins.

---

Step 7: Switch the Default Actor

$ python -m cleveragents actor set-default local/my-haiku-actor

Actual Output:

╭───── Default actor updated ──────╮
│ Name: local/my-haiku-actor       │
│ Provider: Anthropic              │
│ Model: claude-3-5-haiku-20241022 │
│ Default: yes                     │
│ Unsafe: no                       │
│ Type:                            │
╰──────────────────────────────────╯

What's Happening: set-default updates the registry so that all commands that accept an actor (like plan, tell, build) will use local/my-haiku-actor unless overridden. Only one actor can be the default at a time — setting a new default automatically clears the previous one.

You can also set a built-in as the default:

$ python -m cleveragents actor set-default anthropic/claude-sonnet-4-20250514

Actual Output:

╭───────────── Default actor updated ──────────────╮
│ Name: anthropic/claude-sonnet-4-20250514         │
│ Provider: Anthropic                              │
│ Model: claude-sonnet-4-20250514                  │
│ Default: yes                                     │
│ Unsafe: no                                       │
│ Type:                                            │
╰──────────────────────────────────────────────────╯

---

Step 8: Update Actor Options Without Replacing the Config

You can patch individual actor options without rewriting the whole config file using actor update --option:

$ python -m cleveragents actor update local/my-haiku-actor --option temperature=0.7

Actual Output:

╭───────── Actor updated ──────────╮
│ Name: local/my-haiku-actor       │
│ Provider: Anthropic              │
│ Model: claude-3-5-haiku-20241022 │
│ Default: no                      │
│ Unsafe: no                       │
│ Type:                            │
╰──────────────────────────────────╯

What's Happening: The --option key=value flag merges the provided key-value pair into the actor's options blob without touching the rest of the config. Repeat the flag to set multiple options at once:

$ python -m cleveragents actor update local/my-haiku-actor \
    --option temperature=0.5 \
    --option max_tokens=2048

---

Step 9: Remove a Custom Actor

Before removing, switch the default back to a built-in (you cannot remove the default actor):

$ python -m cleveragents actor set-default openai/gpt-4o
$ python -m cleveragents actor remove local/my-haiku-actor

Actual Output:

╭─────────────────────────────── Actor Removed ────────────────────────────────╮
│ Name: local/my-haiku-actor                                                   │
│ Provider: Anthropic                                                          │
│ Model: claude-3-5-haiku-20241022                                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────── Impact ───────────────────────────────────╮
│ Sessions: 0 affected                                                         │
│ Active Plans: 0 affected                                                     │
│ Actions Referencing: 0                                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────── Cleanup ───────────────────────────────────╮
│ Config: kept on disk                                                         │
│ Contexts: 0 orphaned                                                         │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK Actor removed

What's Happening: The remove command:

1. Queries the database to compute the Impact — how many sessions, active lifecycle plans, and configured actions reference this actor
2. Removes the actor from the registry
3. Reports what was cleaned up (orphaned contexts, etc.)

The original YAML config file on disk is not deleted — only the registry entry is removed. This lets you re-add the actor later with the same config.

Safety rule: Built-in actors (openai/gpt-4o, anthropic/..., etc.) cannot be removed. The default actor cannot be removed either — switch the default first.

---

Built-in Actors Reference

The five built-in actors registered at startup:

Name	Provider	Model	Context Window	JSON Mode
openai/gpt-4o	OpenAI	gpt-4o	128,000 tokens	✓
anthropic/claude-sonnet-4-20250514	Anthropic	claude-sonnet-4-20250514	200,000 tokens	—
google/gemini-2.0-flash	Google	gemini-2.0-flash	1,000,000 tokens	✓
gemini/gemini-2.0-flash	Gemini	gemini-2.0-flash	1,000,000 tokens	✓
openrouter/anthropic-claude-sonnet-4-20250514	OpenRouter	anthropic/claude-sonnet-4-20250514	128,000 tokens	✓

All built-in actors support streaming, tool calls, and vision.

---

Scripting Examples

Find the Default Actor

python -m cleveragents actor list --format json | python3 -c "
import sys, json
actors = json.load(sys.stdin)['data']
default = next((a for a in actors if a['is_default']), None)
if default:
    print(f\"Default: {default['name']} ({default['provider']} / {default['model']})\")
"

List Actors with Vision Support

python -m cleveragents actor list --format json | python3 -c "
import sys, json
actors = json.load(sys.stdin)['data']
for a in actors:
    caps = (a.get('graph_descriptor') or {}).get('capabilities') or {}
    if caps.get('supports_vision'):
        print(a['name'])
"

Check if an Actor Exists

python -m cleveragents actor show openai/gpt-4o --format json 2>/dev/null \
  && echo 'Actor exists' || echo 'Actor not found'

---

Complete Interaction Log

Click to see the full verified command session

$ python -m cleveragents actor --help
 Usage: python -m cleveragents actor [OPTIONS] COMMAND [ARGS]...
 Actor management (built-ins <provider>/<model>; customs local/<id>; unsafe requires --unsafe)
 Commands: run, add, update, remove, list, show, set-default, context

$ python -m cleveragents actor list
                                Actors (5 total)
[table with 5 built-in actors, openai/gpt-4o marked as default]
✓ OK 5 actors listed

$ python -m cleveragents actor list --format json
{"command":"","status":"ok","exit_code":0,"data":[...5 actors with full capability metadata...]}

$ python -m cleveragents actor show openai/gpt-4o
╭─── Actor details ───╮
│ Name: openai/gpt-4o │
│ Provider: Openai    │
│ Model: gpt-4o       │
│ Default: yes        │
│ Unsafe: no          │
│ Type:               │
╰─────────────────────╯

$ python -m cleveragents actor show openai/gpt-4o --format json
{"command":"","status":"ok","exit_code":0,"data":{"name":"openai/gpt-4o","provider":"Openai","model":"gpt-4o","unsafe":false,"is_default":true,"is_built_in":true,...}}

$ cat > my-haiku-actor.yaml << 'EOF'
provider: Anthropic
model: claude-3-5-haiku-20241022
unsafe: false
EOF

$ python -m cleveragents actor add local/my-haiku-actor --config my-haiku-actor.yaml
╭────────── Actor added ───────────╮
│ Name: local/my-haiku-actor       │
│ Provider: Anthropic              │
│ Model: claude-3-5-haiku-20241022 │
│ Default: no                      │
│ Unsafe: no                       │
│ Type:                            │
╰──────────────────────────────────╯
╭─ Config ─╮
│ Hash: 4ec6313b... │
│ Options: 0        │
╰───────────────────╯
✓ OK Actor added

$ python -m cleveragents actor list
                                Actors (6 total)
[table now shows local/my-haiku-actor with Custom: 1 in summary]
✓ OK 6 actors listed

$ python -m cleveragents actor set-default local/my-haiku-actor
╭───── Default actor updated ──────╮
│ Name: local/my-haiku-actor       │
│ Default: yes                     │
╰──────────────────────────────────╯

$ python -m cleveragents actor update local/my-haiku-actor --option temperature=0.7
╭───────── Actor updated ──────────╮
│ Name: local/my-haiku-actor       │
│ Default: yes                     │
╰──────────────────────────────────╯

$ python -m cleveragents actor set-default openai/gpt-4o
╭─ Default actor updated ─╮
│ Name: openai/gpt-4o     │
│ Default: yes            │
╰─────────────────────────╯

$ python -m cleveragents actor remove local/my-haiku-actor
╭─ Actor Removed ─╮
│ Name: local/my-haiku-actor │
╰─────────────────────────────╯
╭─ Impact ─╮
│ Sessions: 0 affected │
│ Active Plans: 0 affected │
│ Actions Referencing: 0 │
╰──────────────────────────╯
✓ OK Actor removed

---

Key Takeaways

• Actor naming convention: built-ins use <provider>/<model> (e.g. openai/gpt-4o); custom actors use local/<id> (e.g. local/my-actor).
• actor list shows a rich table with a Summary panel — use --format json to get full capability metadata (context window size, streaming, tool calls, vision, JSON mode) for all actors.
• actor show <name> inspects a single actor; --format json exposes the full config_blob and graph_descriptor.
• actor add requires a --config YAML file and a local/<id> name. Use --update to replace an existing actor without error.
• actor set-default works on both built-in and custom actors. Only one actor is the default at a time.
• actor update --option key=value patches individual options without rewriting the config file.
• actor remove shows an Impact panel before deletion — sessions, active plans, and actions referencing the actor are counted. The YAML file on disk is preserved.
• Safety rules: built-in actors cannot be removed; the current default actor cannot be removed (switch the default first).

Try It Yourself

• Add a custom actor with options: actor add local/my-actor --config actor.yaml --option temperature=0.3 --option max_tokens=4096
• Set a custom actor as default at add time: actor add local/my-actor --config actor.yaml --set-default
• Script: find all actors with >100k context: pipe actor list --format json to jq '[.data[] | select(.graph_descriptor.capabilities.max_context_length > 100000) | .name]'
• YAML output: actor list --format yaml — same data as JSON but in YAML syntax, useful for config-heavy tooling

Related Examples

• CleverAgents CLI Basics — version, info, and diagnostics commands
• Mastering Output Format Flags — deep dive into --format json/yaml/plain/table
• Showcase Index

---

This example was automatically generated and verified by the CleverAgents UAT system. Feature area: Actor management workflows | Test cycle: 1 | Generated: 2026-04-07

---

Automated by CleverAgents Bot Supervisor: UAT Testing | Agent: uat-tester