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

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

---

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

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

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

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

```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.
- **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](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