cleveragents-core/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>
• How to handle actor removal when sessions, plans, or actions reference it
• When and how to use the --unsafe flag for forced removal

---

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.

---

Understanding Actor Removal Impact and the --unsafe Flag

When you attempt to remove an actor, CleverAgents first computes the impact of that removal — how many sessions, active plans, and configured actions reference the actor. This safeguard prevents accidental data loss.

Impact Reporting

The Impact panel shows three counts:

• Sessions affected: How many active or paused sessions are using this actor
• Active Plans affected: How many lifecycle plans (currently running or scheduled) depend on this actor
• Actions Referencing: How many configured actions (e.g., in tools or workflows) reference this actor

If all three counts are zero, the removal is safe and proceeds immediately.

Non-Zero Impact Scenarios

If any impact count is non-zero, the removal is blocked by default. This prevents breaking active workflows. For example:

$ python -m cleveragents actor remove local/my-production-actor

Actual Output (blocked):

╭─────────────────────────────── Actor Removal Blocked ────────────────────────╮
│ Name: local/my-production-actor                                              │
│ Provider: Anthropic                                                          │
│ Model: claude-3-5-sonnet-20241022                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────── Impact ───────────────────────────────────╮
│ Sessions: 3 affected                                                         │
│ Active Plans: 2 affected                                                     │
│ Actions Referencing: 5                                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
⚠ BLOCKED: Cannot remove actor with non-zero impact. Use --unsafe to override.

What's Happening: The removal is rejected because:

• 3 sessions are actively using this actor
• 2 lifecycle plans depend on it
• 5 configured actions reference it

To proceed, you must explicitly acknowledge the risk using the --unsafe flag.

The --unsafe Flag

The --unsafe flag explicitly overrides the impact safeguard and forces removal even when impact counts are non-zero. Use it only when you understand the consequences:

$ python -m cleveragents actor remove local/my-production-actor --unsafe

Actual Output (forced removal):

╭─────────────────────────────── Actor Removed ────────────────────────────────╮
│ Name: local/my-production-actor                                              │
│ Provider: Anthropic                                                          │
│ Model: claude-3-5-sonnet-20241022                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────── Impact ───────────────────────────────────╮
│ Sessions: 3 affected                                                         │
│ Active Plans: 2 affected                                                     │
│ Actions Referencing: 5                                                       │
╰──────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────── Cleanup ───────────────────────────────────╮
│ Config: kept on disk                                                         │
│ Contexts: 0 orphaned                                                         │
│ ⚠ WARNING: 3 sessions will lose actor reference                              │
│ ⚠ WARNING: 2 active plans will fail on next execution                        │
│ ⚠ WARNING: 5 actions will reference a non-existent actor                     │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK Actor removed (with warnings)

When to Use --unsafe

Use the --unsafe flag only in these scenarios:

1. Decommissioning a deprecated actor: You've migrated all sessions and plans to a new actor, but some stale action configurations still reference the old one. You're confident they won't be executed.

2. Emergency cleanup: An actor is corrupted or misconfigured, and you need to remove it immediately to prevent further damage. You'll manually fix affected sessions and plans afterward.

3. Development/testing: You're in a development environment and don't care about breaking test sessions or plans.

4. Automated cleanup: A script is removing actors as part of a larger migration or cleanup process, and you've already handled the affected sessions and plans programmatically.

Best Practices for Safe Removal

To remove an actor without using --unsafe:

1. Identify affected sessions: Use session list --format json and filter for sessions using the actor you want to remove.

2. Migrate or terminate sessions: For each affected session, either:

   • Migrate it to a different actor using session update <id> --actor <new-actor>
   • Terminate it using session terminate <id>

3. Update or cancel plans: For each affected active plan, either:

   • Update it to use a different actor
   • Cancel it using plan cancel <id>

4. Update action configurations: For each action referencing the actor, update its configuration to use a different actor or remove the action.

5. Remove the actor: Once all impact counts are zero, removal proceeds safely:

$ python -m cleveragents actor remove local/my-production-actor

Actual Output (safe removal):

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

Safety Rules Summary

• Built-in actors cannot be removed — they are system-managed and essential
• The default actor cannot be removed — switch the default first
• Non-zero impact blocks removal by default — use --unsafe to override
• YAML config files are preserved — only the registry entry is deleted
• Removal is irreversible — once deleted, the actor must be re-added from the YAML file if needed

---

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.
• Impact safeguards: Non-zero impact blocks removal by default. Use --unsafe to force removal when you understand the consequences.
• 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