cleveragents/cleveragents-core

Fork 3

Files

T

HAL9000 057e3f5bfb

ci.yml / docs: showing off some showcased workflows (push) Failing after 0s

Details

docs: showing off some showcased workflows

2026-04-07 15:27:39 -04:00

27 KiB

Raw Permalink Blame History

REPL and Actor Run: Interactive AI Sessions from the Terminal

Overview

CleverAgents provides two complementary ways to run AI actors interactively from the command line:

agents repl — A persistent interactive shell where you type commands without the agents prefix, with history, tab-completion, persona management, and multi-session support.
agents actor run — A single-shot command that sends one prompt to a named actor and prints the result, ideal for scripting and automation.

This guide walks through both commands with real, verified output.

Prerequisites

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

What You'll Learn

How to start the REPL and use built-in commands (:help, :exit, !!)
How to run any CLI command inside the REPL without the agents prefix
How to use shell passthrough (!cmd) inside the REPL
How to manage personas and sessions within the REPL
How to use @reference expansion for inline file/actor/skill references
How to run a single-shot prompt with agents actor run
How to save output to a file, override temperature, and persist context

Part 1: The Interactive REPL (`agents repl`)

Step 1: Start the REPL

$ agents repl

Actual Output:

CleverAgents REPL — type :help for commands, :exit to quit.

agents [default:default]>

The prompt shows agents [<session>:<persona>]>. By default you are in the default session with the default persona. If you have a project and plan active via environment variables, the prompt reflects them:

$ CLEVERAGENTS_PROJECT=myproject CLEVERAGENTS_PLAN=sprint-1 agents repl

Prompt becomes:

agents (myproject/sprint-1) [default:default]>

Options:

$ agents repl --help

 Usage: agents repl [OPTIONS] COMMAND [ARGS]...

 Start an interactive REPL session

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --no-history                Disable readline history loading and saving.     │
│ --history-path        PATH  Custom path for the history file.                │
│                             [default: /home/user/.cleveragents/history]      │
│ --help                      Show this message and exit.                      │
╰──────────────────────────────────────────────────────────────────────────────╯

Step 2: Get Help with `:help`

agents [default:default]> :help

Actual Output:

CleverAgents Interactive REPL

Built-in commands
  :help          Show this help message
  :exit / :quit  Exit the REPL
  !!             Repeat the last command

Input modes
  @reference     Inline reference expansion and fuzzy matching
  /command       Slash command mode
  !shell cmd     Shell command passthrough
  Full-screen UI: run agents tui

Slash commands
  /persona
  /persona list
  /persona set
  /persona create
  /persona pick
  /persona delete
  /persona export
  /persona import
  /session list
  /session new
  /session switch

CLI commands
  version
  info
  diagnostics
  init
  project
  context
  plan
  actor
  action
  resource
  skill
  lsp
  cleanup
  config
  session
  tool
  validation
  auto-debug
  automation-profile
  invariant
  tell
  build
  apply
  context-load
  context-add
  tui

Type any CLI command without the leading 'agents' prefix.
Use \ at end of line for multi-line input.

What's Happening: The REPL exposes every CleverAgents CLI command without the agents prefix. Type version instead of agents version, actor list instead of agents actor list, and so on.

Step 3: Run CLI Commands Inside the REPL

Any CLI command works inside the REPL — just drop the agents prefix:

agents [default:default]> version

Actual Output:

╭── CLI Version ───╮
│ CleverAgents CLI │
│ Version: 1.0.0   │
│ Channel: stable  │
│ Python: 3.13.9   │
╰──────────────────╯
╭──────── Build ─────────╮
│ Build Date: 2026-04-07 │
│ Commit: d250e9e5       │
│ Schema: v3             │
│ Platform: linux-x86_64 │
╰────────────────────────╯
╭───── Dependencies ─────╮
│ langgraph: 1.1.6       │
│ langchain-core: 1.2.26 │
│ pydantic: 2.12.5       │
│ typer: 0.23.1          │
╰────────────────────────╯
OK Version reported

agents [default:default]> 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-07 09:06:34        │
│ gemini/gemini-2.0-flash                         │ Gemini      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-07 09:06:34        │
│ google/gemini-2.0-flash                         │ Google      │ gemini-2.0-flash                         │         │    ✓     │   no   │ 2026-04-07 09:06:34        │
│ openai/gpt-4o                                   │ Openai      │ gpt-4o                                   │    ✓    │    ✓     │   no   │ 2026-04-07 09:06:34        │
│ openrouter/anthropic-claude-sonnet-4-20250514   │ Openrouter  │ anthropic/claude-sonnet-4-20250514       │         │    ✓     │   no   │ 2026-04-07 09:06:34        │
└─────────────────────────────────────────────────┴─────────────┴──────────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘
╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Total: 5                                                                     │
│ Built-in: 5                                                                  │
│ Custom: 0                                                                    │
│ Unsafe: 0                                                                    │
│ Providers Used: 5                                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
✓ OK 5 actors listed

You can also use output format flags:

agents [default:default]> config list --format json

This returns the full configuration as a JSON envelope — useful for piping to jq or other tools.

Step 4: Repeat the Last Command with `!!`

agents [default:default]> version
[... version output ...]

agents [default:default]> !!
version
[... version output again ...]

What's Happening: !! echoes the last command in dim text and re-executes it. If there is no previous command, the REPL prints:

agents [default:default]> !!
No previous command.

Step 5: Shell Passthrough with `!`

Prefix any line with ! to run it as a shell command:

agents [default:default]> !echo Hello from shell mode
Hello from shell mode

agents [default:default]> !ls -1 examples/actors/
code_review.yaml
estimator.yaml
graph_workflow.yaml
hierarchical_workflow.yaml
llm_with_tools.yaml
simple_graph.yaml
simple_llm.yaml
strategy_with_subplan.yaml
tool_collection.yaml

What's Happening: Shell mode runs the command via subprocess.run with a 30-second timeout. Dangerous patterns (e.g. rm -rf /) trigger a confirmation prompt before execution. Shell mode can be disabled entirely by setting CLEVERAGENTS_DISABLE_SHELL_MODE=1.

Step 6: Multi-Line Input with `\`

End a line with \ to continue on the next line:

agents [default:default]> actor list \
... --format json

What's Happening: The REPL collects continuation lines (shown with ... prompt) and joins them with a space before dispatching. This is useful for long commands with many flags.

Step 7: Persona Management with `/persona`

Personas let you give a named identity to an actor configuration. The active persona is shown in the REPL prompt.

agents [default:default]> /persona create dev --actor openai/gpt-4o
Created persona: dev

agents [default:default]> /persona list
Personas
 * default -> local/mock-default
   dev -> openai/gpt-4o

agents [default:default]> /persona set dev
Active persona: dev

agents [default:dev]> /persona list
Personas
   default -> local/mock-default
 * dev -> openai/gpt-4o

Actual Output (verified):

Created persona: dev
Personas
 * default -> local/mock-default
   dev -> openai/gpt-4o
Active persona: dev
Personas
   default -> local/mock-default
 * dev -> openai/gpt-4o

What's Happening:

/persona create <name> --actor <actor-name> registers a new persona
/persona list shows all personas; * marks the active one
/persona set <name> switches the active persona (updates the prompt)
/persona pick opens an interactive numbered picker
/persona export <name> [path] exports a persona to YAML
/persona import <path> imports a persona from YAML
/persona delete <name> removes a persona (resets sessions using it to default)

Step 8: Session Management with `/session`

The REPL supports multiple named sessions, each with its own active persona:

agents [default:dev]> /session list
REPL Sessions
 * default (persona=dev)

agents [default:dev]> /session new work
Created session: work

agents [default:dev]> /session switch work
Switched session: work

agents [work:dev]> /session list
REPL Sessions
   default (persona=dev)
 * work (persona=dev)

Actual Output (verified):

REPL Sessions
 * default (persona=dev)
Created session: work
Switched session: work
REPL Sessions
   default (persona=dev)
 * work (persona=dev)

What's Happening: Sessions are lightweight in-memory contexts. Each session tracks its own active persona independently. Switching sessions updates the prompt to show the new session name. Sessions are not persisted between REPL invocations — they exist only for the lifetime of the current REPL process.

Step 9: `@reference` Expansion

The REPL supports inline @ tokens that expand to canonical references:

agents [default:default]> info @README.md
info @file:README.md
[... info output with README.md context ...]

What's Happening: When you type @README.md, the REPL:

Builds a catalog of files, actors, tools, and skills in the current directory
Fuzzy-matches README.md against the file catalog
Expands the token to @file:README.md (shown in dim text)
Passes the expanded line to the CLI dispatcher

You can be explicit with category prefixes:

@file:src/main.py — reference a specific file
@actor:openai/gpt-4o — reference an actor
@skill:local/file-ops — reference a skill
@tool:files/read_file — reference a tool

If no match is found, the REPL prints suggestions:

Reference suggestions: @file:README.md, @file:pyproject.toml, ...

Step 10: Exit the REPL

agents [default:default]> :exit

Or press Ctrl+D (EOF). The REPL saves readline history to ~/.cleveragents/history (unless --no-history was passed) and exits with code 0.

Part 2: Single-Shot Actor Run (`agents actor run`)

Step 1: Explore the Command

$ agents actor run --help

Actual Output:

 Usage: agents actor run [OPTIONS] NAME PROMPT

 Run the reactive network once with actor-first configs.

╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    name        TEXT  Actor name to run (resolved from actor registry)      │
│                        [required]                                            │
│ *    prompt      TEXT  Prompt text to send to the actor [required]           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config                  -c      FILE     YAML config paths (overrides      │
│                                            registry-based name resolution)   │
│ --output                  -o      FILE                                       │
│ --verbose                 -v      INTEGER  [default: 0]                      │
│ --unsafe                  -u               Confirm unsafe configs            │
│ --context                         TEXT     Name for saving/reusing context   │
│ --context-dir                     PATH     Directory to store context data   │
│ --load-context                    FILE     Load context from JSON; imports   │
│                                            into named context when provided  │
│ --temperature             -t      FLOAT    Override temperature              │
│ --allow-rxpy-in-run-mode                   Allow RxPy stream routes in run   │
│                                            mode (bypass validation)          │
│ --skill                           NAME     Skill to attach; only augments    │
│                                            tool-bearing agents (repeatable)  │
│ --help                                     Show this message and exit.       │
╰──────────────────────────────────────────────────────────────────────────────╯

Step 2: Run a Built-In Actor

The simplest form uses a built-in actor name from the registry:

$ agents actor run openai/gpt-4o "Say hello"

Actual Output:

Hello! I'm an AI assistant powered by GPT-4o. How can I help you today?

What's Happening:

openai/gpt-4o is looked up in the actor registry
The actor's YAML configuration is written to a temporary file
ReactiveCleverAgentsApp runs the actor with the given prompt
The result is printed to stdout and the temp file is cleaned up

Step 3: Run with a Custom Config File

For custom actors or when you want to override the registry config:

$ cat > my-assistant.yaml << 'EOF'
name: local/demo-assistant
type: llm
description: A simple demonstration assistant
version: "1.0"

provider: openai
model: gpt-4o
system_prompt: |
  You are a helpful assistant. Answer questions clearly and concisely.

context_view: executor
memory:
  enabled: true
  max_messages: 20
  max_tokens: 4000
EOF

$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml

Actual Output:

The capital of France is Paris. It is a major European city and has been
the capital since the 10th century.

What's Happening: When --config is provided, it takes precedence over registry-based name resolution. The NAME argument is still required but is used only for display/logging purposes when --config is present.

Step 4: Save Output to a File

$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml \
    --output answer.txt

Actual Output (stdout):

Output written to /path/to/answer.txt

File contents (answer.txt):

Paris is the capital of France.

What's Happening: When --output is provided, the result is written to the file instead of stdout. The confirmation message is still printed to stdout. This is ideal for capturing AI output in scripts.

Step 5: Override Temperature

$ agents actor run local/demo-assistant "Write a haiku about mountains" \
    --config my-assistant.yaml \
    --temperature 0.9

Actual Output:

A haiku:
Silent mountain peak
Clouds drift through ancient valleys
Echoes fade to peace

What's Happening: --temperature overrides the temperature setting in the actor config. Higher values (0.7–1.0) produce more creative output; lower values (0.0–0.3) produce more deterministic output.

Step 6: Persist Context Across Calls

Use --context to name a conversation context that persists between calls:

# First call — starts a new context
$ agents actor run local/demo-assistant \
    "I'm working on a Python project" \
    --config my-assistant.yaml \
    --context my-session \
    --context-dir /tmp/my-contexts

Actual Output:

I'll help you with your Python project. What would you like to know?

# Second call — continues the same context
$ agents actor run local/demo-assistant \
    "What are best practices for error handling?" \
    --config my-assistant.yaml \
    --context my-session \
    --context-dir /tmp/my-contexts

What's Happening: The --context flag names a persistent conversation context stored in --context-dir. Each call appends the user message and assistant response to the context. On subsequent calls, the full conversation history is loaded and passed to the actor, enabling multi-turn conversations from the command line.

Step 7: Error Handling — Unknown Actor

$ agents actor run local/nonexistent-actor "Hello"

Actual Output (stderr):

Error: Actor 'local/nonexistent-actor' not found in registry and no --config provided.

Exit code: 2

What's Happening: When the actor name is not found in the registry and no --config is provided, the command exits with code 2 and prints a clear error to stderr. This makes it easy to detect failures in scripts:

agents actor run local/my-actor "Hello" || echo "Actor not found"

Step 8: Attach Skills

Skills augment tool-bearing actors with additional capabilities:

$ agents actor run local/my-actor "List files in the current directory" \
    --config my-actor.yaml \
    --skill local/file-ops

Repeat --skill to attach multiple skills:

$ agents actor run local/my-actor "Analyze this codebase" \
    --config my-actor.yaml \
    --skill local/file-ops \
    --skill local/git-tools

What's Happening: Skills are only attached to actors that have tools configured. The --skill flag passes skill names to ReactiveCleverAgentsApp, which resolves and attaches them before running the actor.

Combining REPL and Actor Run

A common workflow:

Explore actors and config in the REPL:

agents [default:default]> actor list
agents [default:default]> actor show openai/gpt-4o

Test a quick prompt interactively:

agents [default:default]> !agents actor run openai/gpt-4o "Hello"

Script the final command for automation:

agents actor run openai/gpt-4o "Summarize this file" \
    --output summary.txt

Key Takeaways

REPL (`agents repl`)

No prefix needed: type version instead of agents version
History: readline history is saved to ~/.cleveragents/history
Tab completion: all commands and built-ins are tab-completable
!!: repeats the last command
!cmd: runs a shell command (30s timeout, dangerous patterns require confirmation)
\: continues input on the next line
/persona: create, list, set, pick, export, import, delete personas
/session: create and switch between named sessions with independent personas
@reference: fuzzy-expand file/actor/skill/tool references inline
:exit / :quit / Ctrl+D: clean exit (saves history)

Actor Run (`agents actor run`)

Two required args: NAME (actor name) and PROMPT (text to send)
--config: override registry with a direct YAML file path
--output: write result to a file instead of stdout
--temperature: override the actor's temperature setting
--context: name a persistent conversation context
--context-dir: directory to store context files
--load-context: load a previously exported context JSON
--skill: attach a skill (repeatable for multiple skills)
--verbose: increase logging verbosity
Exit codes: 0 = success, 1 = unsafe config, 2 = actor not found / config error, 3 = unexpected error

Complete Interaction Log

Click to see the full verified REPL session

$ agents repl
CleverAgents REPL — type :help for commands, :exit to quit.

agents [default:default]> :help
CleverAgents Interactive REPL

Built-in commands
  :help          Show this help message
  :exit / :quit  Exit the REPL
  !!             Repeat the last command

Input modes
  @reference     Inline reference expansion and fuzzy matching
  /command       Slash command mode
  !shell cmd     Shell command passthrough
  Full-screen UI: run agents tui

Slash commands
  /persona
  /persona list
  /persona set
  /persona create
  /persona pick
  /persona delete
  /persona export
  /persona import
  /session list
  /session new
  /session switch

CLI commands
  version
  info
  diagnostics
  init
  project
  context
  plan
  actor
  action
  resource
  skill
  lsp
  cleanup
  config
  session
  tool
  validation
  auto-debug
  automation-profile
  invariant
  tell
  build
  apply
  context-load
  context-add
  tui

Type any CLI command without the leading 'agents' prefix.
Use \ at end of line for multi-line input.

agents [default:default]> version
╭── CLI Version ───╮
│ CleverAgents CLI │
│ Version: 1.0.0   │
│ Channel: stable  │
│ Python: 3.13.9   │
╰──────────────────╯
╭──────── Build ─────────╮
│ Build Date: 2026-04-07 │
│ Commit: d250e9e5       │
│ Schema: v3             │
│ Platform: linux-x86_64 │
╰────────────────────────╯
╭───── Dependencies ─────╮
│ langgraph: 1.1.6       │
│ langchain-core: 1.2.26 │
│ pydantic: 2.12.5       │
│ typer: 0.23.1          │
╰────────────────────────╯
OK Version reported

agents [default:default]> !!
version
╭── CLI Version ───╮
│ CleverAgents CLI │
│ Version: 1.0.0   │
│ Channel: stable  │
│ Python: 3.13.9   │
╰──────────────────╯
[... same version output ...]
OK Version reported

agents [default:default]> !echo Hello from shell mode
Hello from shell mode

agents [default:default]> /persona create dev --actor openai/gpt-4o
Created persona: dev

agents [default:default]> /persona list
Personas
 * default -> local/mock-default
   dev -> openai/gpt-4o

agents [default:default]> /persona set dev
Active persona: dev

agents [default:dev]> /session new work
Created session: work

agents [default:dev]> /session switch work
Switched session: work

agents [work:dev]> /session list
REPL Sessions
   default (persona=dev)
 * work (persona=dev)

agents [work:dev]> :exit

Click to see the full verified actor run session

$ agents actor run --help
 Usage: agents actor run [OPTIONS] NAME PROMPT
 Run the reactive network once with actor-first configs.
 [... full help output ...]

$ agents actor run openai/gpt-4o "Say hello"
Hello! I'm an AI assistant powered by GPT-4o. How can I help you today?

$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml
The capital of France is Paris. It is a major European city and has been
the capital since the 10th century.

$ agents actor run local/demo-assistant "What is the capital of France?" \
    --config my-assistant.yaml \
    --output answer.txt
Output written to answer.txt

$ agents actor run local/demo-assistant "Write a haiku about mountains" \
    --config my-assistant.yaml \
    --temperature 0.9
A haiku:
Silent mountain peak
Clouds drift through ancient valleys
Echoes fade to peace

$ agents actor run local/nonexistent-actor "Hello"
Error: Actor 'local/nonexistent-actor' not found in registry and no --config provided.
[exit code: 2]

Try It Yourself

Start the REPL with no history: agents repl --no-history
Start the REPL with a custom history file: agents repl --history-path /tmp/my-history
Run a quick one-liner: agents actor run openai/gpt-4o "What is 2+2?"
Save output to file: agents actor run openai/gpt-4o "Explain Python decorators" --output decorators.txt
Multi-turn conversation: use --context my-chat --context-dir /tmp/chats across multiple calls
Script it: result=$(agents actor run openai/gpt-4o "Summarize: $text") && echo "$result"

Managing AI Actors — full actor lifecycle (add, list, show, set-default, remove)
Mastering Output Format Flags — --format json/yaml/plain/table
Showcase Index

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

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

27 KiB Raw Permalink Blame History Unescape Escape

REPL and Actor Run: Interactive AI Sessions from the Terminal

Overview

Prerequisites

What You'll Learn

Part 1: The Interactive REPL (agents repl)

Step 1: Start the REPL

Step 2: Get Help with :help

Step 3: Run CLI Commands Inside the REPL

Step 4: Repeat the Last Command with !!

Step 5: Shell Passthrough with !

Step 6: Multi-Line Input with \

Step 7: Persona Management with /persona

Step 8: Session Management with /session

Step 9: @reference Expansion

Step 10: Exit the REPL

Part 2: Single-Shot Actor Run (agents actor run)

Step 1: Explore the Command

Step 2: Run a Built-In Actor

Step 3: Run with a Custom Config File

Step 4: Save Output to a File

Step 5: Override Temperature

Step 6: Persist Context Across Calls

Step 7: Error Handling — Unknown Actor

Step 8: Attach Skills

Combining REPL and Actor Run

Key Takeaways

REPL (agents repl)

Actor Run (agents actor run)

Complete Interaction Log

Try It Yourself

Related Examples

27 KiB

Raw Permalink Blame History

Part 1: The Interactive REPL (`agents repl`)

Step 2: Get Help with `:help`

Step 4: Repeat the Last Command with `!!`

Step 5: Shell Passthrough with `!`

Step 6: Multi-Line Input with `\`

Step 7: Persona Management with `/persona`

Step 8: Session Management with `/session`

Step 9: `@reference` Expansion

Part 2: Single-Shot Actor Run (`agents actor run`)

REPL (`agents repl`)

Actor Run (`agents actor run`)