# 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:

```bash
$ 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)

```bash
$ 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)

```bash
$ python -m cleveragents actor list --format json
```

**Actual Output (abbreviated):**
```json
{
  "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

```bash
$ 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:               │
╰─────────────────────╯
```

```bash
$ 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:

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

**Actual Output:**
```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,
    "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:

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

Then register it:

```bash
$ 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:

```bash
$ 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

```bash
$ 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

```bash
$ 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:

```bash
$ 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`:

```bash
$ 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:

```bash
$ 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):

```bash
$ 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

```bash
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

```bash
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

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

---

## Complete Interaction Log

<details>
<summary>Click to see the full verified command session</summary>

```
$ 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
```
</details>

---

## 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](cleveragents-cli-basics.md) — version, info, and diagnostics commands
- [Mastering Output Format Flags](output-format-flags.md) — deep dive into `--format json/yaml/plain/table`
- [Showcase Index](../index.md)

---
*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
