cleveragents-core/docs/reference/actors_examples.md

Actor YAML Examples

Overview

This document provides comprehensive examples of actor YAML configurations, demonstrating various use cases and patterns. Each example is aligned with the CleverAgents specification and shows best practices for actor design.

Related Documentation:

• Actor YAML Schema Reference - Complete schema documentation
• Module: cleveragents.actor.schema
• Schema Version: 1.0

---

Table of Contents

1. Simple LLM Actors
2. Strategist Actors
3. Executor Actors
4. Reviewer Actors
5. Estimation Actors
6. Tool-Only Actors
7. Validation-Node Actors
8. Graph Workflows
9. Hierarchical Actor Graphs
10. Strategy Actor with Subplan Spawning

---

Simple LLM Actors

Minimal Code Reviewer

File: examples/actors/simple_llm.yaml

A basic LLM actor with system prompt, memory, and context configuration.

name: assistants/code_reviewer
type: llm
description: Reviews Python code for best practices, style, and potential bugs
version: "1.0"

model: gpt-4
system_prompt: |
  You are an expert Python code reviewer. Review code for:
  - PEP 8 style compliance
  - Best practices and design patterns
  - Potential bugs and edge cases
  - Performance considerations
  - Security vulnerabilities

  Provide constructive feedback with specific suggestions for improvement.

context_view: reviewer
memory:
  enabled: true
  max_messages: 20
  max_tokens: 4000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
  include_dirs:
    - "src/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
    - "**/.pytest_cache/**"
  max_context_tokens: 8000

Use Cases:

• Code review assistants
• Documentation reviewers
• Simple conversational agents
• Single-purpose analysis tools

---

Strategist Actors

Planning & Decomposition Actor

Purpose: Breaks down high-level goals into actionable subplans.

name: strategists/task_planner
type: llm
description: Analyzes requirements and creates detailed execution plans
version: "1.0"

model: gpt-4
system_prompt: |
  You are a strategic planning expert. Your role is to:

  1. Analyze the user's high-level goal
  2. Break it down into concrete, actionable steps
  3. Identify dependencies between steps
  4. Suggest parallel execution opportunities
  5. Estimate effort and risk for each step
  6. Recommend tools and resources needed

  Think carefully about edge cases and potential obstacles.
  Provide clear, specific instructions for each step.

context_view: strategist
memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000

context:
  include_files:
    - "README.md"
    - "ARCHITECTURE.md"
    - "requirements.txt"
  include_dirs:
    - "src/"
    - "docs/"
    - "tests/"
  max_context_tokens: 32000

tools:
  - files/read_file
  - files/list_directory
  - git/get_status

Key Features:

• Large context window for complex planning
• Read-only tools for information gathering
• Strategist context view for high-level perspective
• Extended memory for multi-turn planning

Use Cases:

• Strategize phase of plan execution
• Project decomposition
• Task dependency analysis
• Multi-project coordination

---

Executor Actors

Implementation & Execution Actor

Purpose: Executes concrete tasks with write capabilities.

name: executors/code_writer
type: llm
description: Implements code changes based on detailed specifications
version: "1.0"

model: gpt-4
system_prompt: |
  You are an expert software engineer. Your role is to:

  1. Read and understand the specification
  2. Implement clean, well-tested code
  3. Follow project conventions and style guides
  4. Write comprehensive docstrings and comments
  5. Consider edge cases and error handling

  Always verify your changes don't break existing tests.
  Write new tests for new functionality.

context_view: executor
memory:
  enabled: true
  max_messages: 30
  max_tokens: 8000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
    - "CONTRIBUTING.md"
  include_dirs:
    - "src/"
    - "tests/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "**/.pytest_cache/**"
    - "**/htmlcov/**"
  max_context_tokens: 16000

tools:
  - files/read_file
  - files/write_file
  - files/create_directory
  - git/add
  - testing/run_pytest

Key Features:

• Write-capable tools for code modification
• Executor context view for implementation focus
• Testing tools for verification
• Project-aware context filtering

Use Cases:

• Execute phase of plan execution
• Code implementation tasks
• File system operations
• Test-driven development

---

Reviewer Actors

Code Quality & Standards Reviewer

Purpose: Reviews changes for quality, standards compliance, and correctness.

name: reviewers/quality_gate
type: llm
description: Reviews code changes for quality, standards, and correctness
version: "1.0"

model: gpt-4
system_prompt: |
  You are a senior code reviewer and quality expert. Review changes for:

  **Code Quality:**
  - Clean code principles
  - SOLID design patterns
  - DRY (Don't Repeat Yourself)
  - Proper error handling

  **Standards:**
  - Project coding standards
  - Documentation completeness
  - Type hints and static typing
  - Test coverage

  **Correctness:**
  - Logic errors
  - Edge cases
  - Race conditions
  - Security vulnerabilities

  Provide specific, actionable feedback with examples.

context_view: reviewer
memory:
  enabled: true
  max_messages: 40
  max_tokens: 12000

context:
  include_files:
    - "README.md"
    - "CONTRIBUTING.md"
    - "docs/coding_standards.md"
  include_dirs:
    - "src/"
    - "tests/"
    - "docs/"
  max_context_tokens: 24000

tools:
  - files/read_file
  - files/list_directory
  - git/diff
  - testing/run_pytest
  - linting/run_ruff
  - linting/run_pyright

Key Features:

• Read-only + linting tools
• Reviewer context view
• Large context for thorough review
• Access to coding standards

Use Cases:

• Apply phase review gate
• Pull request review
• Quality assurance
• Standards compliance checking

---

Estimation Actors

Structured Estimation Reporter

File: examples/actors/estimator.yaml

This actor is intended for the optional estimation_actor slot on actions. It uses context_view: strategist, declares role_hint: estimation, and defines response_format with an EstimationReport JSON-schema metadata object. Runtime provider-level structured-output enforcement is planned in a future follow-up.

---

LLM Actors with Tools

Strategist with File Access

File: examples/actors/llm_with_tools.yaml

An LLM actor with tool access for strategic planning and analysis.

name: strategists/task_planner
type: llm
description: Strategic planning and task decomposition
version: "1.0"

model: gpt-4
system_prompt: |
  You are a strategic planner. Break down complex goals into actionable steps.
  Use available tools to analyze the codebase and understand the context.

context_view: strategist

tools:
  - files/read_file
  - files/list_directory

memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
  include_dirs:
    - "src/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
  max_context_tokens: 16000

Use Cases:

• Strategic planners with file access
• Analysts needing codebase inspection
• Planning agents that need to read documentation

Key Features:

• Read-only file tools for safety
• Large memory buffer for complex planning
• Strategist context view

---

Tool-Only Actors

File Operations Toolkit

File: examples/actors/tool_collection.yaml

Purpose: Provides a reusable collection of file operation tools without LLM interaction.

name: utilities/file_ops
type: tool
description: Collection of file system operation tools
version: "1.0"

tools:
  - files/read_file
  - files/write_file
  - files/create_directory
  - files/delete_file
  - files/move_file
  - files/copy_file
  - files/list_directory

Key Features:

• No LLM required
• Pure tool collection
• Reusable across multiple actors
• Minimal configuration

Use Cases:

• Shared tool libraries
• Utility tool bundles
• Tool composition in graph actors
• Testing tool collections

Git Operations Toolkit

name: utilities/git_ops
type: tool
description: Collection of Git operation tools
version: "1.0"

tools:
  - git/status
  - git/add
  - git/commit
  - git/diff
  - git/log
  - git/branch

---

Validation-Node Actors

Validation & Linting Actor

Purpose: Runs validation checks without modifying code.

name: validators/python_checker
type: llm
description: Validates Python code for correctness and style
version: "1.0"

model: gpt-4
system_prompt: |
  You are a validation expert. Your role is to:

  1. Run all configured validators and linters
  2. Analyze the results
  3. Categorize issues by severity
  4. Provide clear explanations of each issue
  5. Suggest specific fixes

  Focus on actionable feedback. Explain WHY something is an issue.

context_view: reviewer
memory:
  enabled: false

context:
  include_files:
    - "pyproject.toml"
    - "ruff.toml"
  include_dirs:
    - "src/"
  max_context_tokens: 8000

tools:
  - files/read_file
  - linting/run_ruff
  - linting/run_pyright
  - testing/run_pytest
  - security/run_bandit

Key Features:

• Read-only + validation tools
• No memory (stateless validation)
• Reviewer context view
• Security scanning included

Use Cases:

• Apply phase validation gate
• Pre-commit validation
• CI/CD quality checks
• Security scanning

---

Graph Workflows

Linear Graph: Three-Step Review

File: examples/actors/simple_graph.yaml

Purpose: Simple linear workflow with three sequential steps.

name: workflows/simple_review
type: graph
description: Linear workflow for code review in three steps
version: "1.0"

model: gpt-4

route:
  nodes:
    - id: analyzer
      type: agent
      name: Code Analyzer
      description: Analyzes code structure and patterns
      config:
        model: gpt-4
        prompt: "Analyze the code structure and identify patterns"
        tools:
          - files/read_file
          - files/list_directory

    - id: reviewer
      type: agent
      name: Code Reviewer
      description: Reviews code for quality issues
      config:
        model: gpt-4
        prompt: "Review code for quality, style, and best practices"
        tools:
          - files/read_file

    - id: reporter
      type: agent
      name: Report Generator
      description: Generates summary report
      config:
        model: gpt-4
        prompt: "Generate a comprehensive review report"
        tools:
          - files/write_file

  edges:
    - from_node: analyzer
      to_node: reviewer
    - from_node: reviewer
      to_node: reporter

  entry_node: analyzer
  exit_nodes:
    - reporter

context_view: reviewer
memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000

Key Features:

• Linear execution flow
• Three sequential agent nodes
• Single entry and exit point
• Shared context and memory

Use Cases:

• Simple multi-step workflows
• Pipeline processing
• Sequential analysis tasks

---

Complex Graph: Test-Driven Development

File: examples/actors/graph_workflow.yaml

Purpose: Complex workflow with conditional routing, retry logic, and subgraphs.

name: workflows/test_driven_dev
type: graph
description: Test-driven development workflow with automated testing and feedback loops
version: "1.0"

model: gpt-4

route:
  nodes:
    # Entry: Planning
    - id: planner
      type: agent
      name: Test Planner
      description: Plans test cases based on requirements
      config:
        model: gpt-4
        prompt: |
          You are a test planning expert. Analyze the requirements and create
          a comprehensive test plan covering unit tests, integration tests,
          and edge cases.
        tools:
          - files/read_file
          - files/list_directory

    # Write tests first
    - id: test_writer
      type: agent
      name: Test Writer
      description: Writes test cases based on the plan
      config:
        model: gpt-4
        prompt: |
          You are a test writing expert. Write pytest tests based on the plan.
          Follow best practices: descriptive names, docstrings, fixtures,
          and test one thing per test.
        tools:
          - files/write_file
          - files/read_file

    # Run the tests (should fail initially)
    - id: run_tests
      type: tool
      name: Test Runner
      description: Executes pytest test suite
      config:
        tool_name: testing/run_pytest
        parameters:
          verbose: true
          coverage: true

    # Check test results - CONDITIONAL
    - id: check_results
      type: conditional
      name: Test Result Checker
      description: Routes based on test pass/fail status
      config:
        conditions:
          - check: "state.get('tests_passed') == True"
            route_to: code_review
          - check: "state.get('tests_passed') == False"
            route_to: implementation_writer

    # Write implementation to make tests pass
    - id: implementation_writer
      type: agent
      name: Implementation Writer
      description: Writes code to make the tests pass
      config:
        model: gpt-4
        prompt: |
          You are an implementation expert. Write clean, well-documented code
          that makes the failing tests pass. Follow SOLID principles.
        tools:
          - files/write_file
          - files/read_file

    # Run tests again after implementation
    - id: rerun_tests
      type: tool
      name: Test Rerunner
      description: Re-executes tests after implementation
      config:
        tool_name: testing/run_pytest
        parameters:
          verbose: true
          coverage: true

    # Verify tests pass - CONDITIONAL with RETRY
    - id: verify_tests
      type: conditional
      name: Test Verification
      description: Verify tests pass after implementation
      config:
        conditions:
          - check: "state.get('tests_passed') == True"
            route_to: code_review
          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) < 3"
            route_to: debug_failures
          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) >= 3"
            route_to: escalate

    # Debug test failures
    - id: debug_failures
      type: agent
      name: Debugger
      description: Analyzes and fixes test failures
      config:
        model: gpt-4
        prompt: |
          You are a debugging expert. Analyze the test failures and fix the
          implementation. Look for logic errors, edge cases, type mismatches,
          and missing error handling.
        tools:
          - files/read_file
          - files/write_file

    # Code review (subgraph)
    - id: code_review
      type: subgraph
      name: Code Reviewer
      description: Runs code review workflow
      config:
        actor_path: examples/actors/simple_llm.yaml

    # Escalate if tests keep failing
    - id: escalate
      type: tool
      name: Escalation Handler
      description: Escalates persistent failures to human
      config:
        tool_name: notifications/send_alert
        parameters:
          channel: engineering
          priority: high

  edges:
    - from_node: planner
      to_node: test_writer
    - from_node: test_writer
      to_node: run_tests
    - from_node: run_tests
      to_node: check_results
    - from_node: implementation_writer
      to_node: rerun_tests
    - from_node: rerun_tests
      to_node: verify_tests
    - from_node: debug_failures
      to_node: rerun_tests

  entry_node: planner
  exit_nodes:
    - code_review
    - escalate

context_view: strategist
memory:
  enabled: true
  max_messages: 100
  max_tokens: 16000
  summarize_old: true

context:
  include_files:
    - "README.md"
    - "requirements.txt"
    - "pyproject.toml"
  include_dirs:
    - "src/"
    - "tests/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
    - "**/.pytest_cache/**"
    - "**/htmlcov/**"
  max_context_tokens: 32000

env_vars:
  PYTEST_ARGS: --verbose --cov --cov-report=html
  MAX_RETRIES: "3"

Key Features:

• Conditional routing based on test results
• Retry logic with configurable max attempts
• Subgraph invocation for code review
• Escalation path for persistent failures
• Tool nodes for test execution
• Agent nodes for planning, writing, debugging
• Multiple exit points (success or escalation)

Use Cases:

• Test-driven development workflows
• Multi-stage validation pipelines
• Workflows with retry and error handling
• Complex agentic loops

---

Hierarchical Actor Graphs

Graph with Subgraph: Multi-Level Planning

Purpose: Demonstrates hierarchical composition with nested subgraphs.

name: workflows/hierarchical_planner
type: graph
description: Multi-level planning with strategic and tactical subgraphs
version: "1.0"

model: gpt-4

route:
  nodes:
    # Top-level strategic planner
    - id: strategic_planner
      type: agent
      name: Strategic Planner
      description: High-level goal decomposition
      config:
        model: gpt-4
        prompt: |
          You are a strategic planner. Break down the high-level goal into
          major phases. For each phase, define success criteria and
          dependencies.
        tools:
          - files/read_file

    # Tactical planning subgraph
    - id: tactical_planning
      type: subgraph
      name: Tactical Planner
      description: Detailed task planning for each phase
      config:
        actor_path: examples/actors/tactial_planner.yaml
        context_override:
          context_view: strategist
          max_context_tokens: 16000

    # Parallel execution coordinator
    - id: execution_coordinator
      type: agent
      name: Execution Coordinator
      description: Coordinates parallel task execution
      config:
        model: gpt-4
        prompt: |
          You are an execution coordinator. Identify which tasks can run
          in parallel and which have dependencies. Create execution plan.
        tools:
          - files/read_file

    # Task execution subgraph (invoked multiple times)
    - id: task_executor
      type: subgraph
      name: Task Executor
      description: Executes individual tasks
      config:
        actor_path: examples/actors/task_executor.yaml
        parallel: true
        max_parallel: 3

    # Results aggregation
    - id: results_aggregator
      type: agent
      name: Results Aggregator
      description: Collects and summarizes results
      config:
        model: gpt-4
        prompt: |
          Aggregate results from all task executions. Identify successes,
          failures, and any issues that need attention.
        tools:
          - files/read_file
          - files/write_file

    # Quality review subgraph
    - id: quality_review
      type: subgraph
      name: Quality Reviewer
      description: Comprehensive quality review
      config:
        actor_path: examples/actors/quality_reviewer.yaml

  edges:
    - from_node: strategic_planner
      to_node: tactical_planning
    - from_node: tactical_planning
      to_node: execution_coordinator
    - from_node: execution_coordinator
      to_node: task_executor
    - from_node: task_executor
      to_node: results_aggregator
    - from_node: results_aggregator
      to_node: quality_review

  entry_node: strategic_planner
  exit_nodes:
    - quality_review

context_view: strategist
memory:
  enabled: true
  max_messages: 200
  max_tokens: 32000
  summarize_old: true

context:
  include_files:
    - "README.md"
    - "ARCHITECTURE.md"
  include_dirs:
    - "src/"
    - "docs/"
    - "tests/"
  max_context_tokens: 64000

Key Features:

• Three levels of hierarchy: Strategic → Tactical → Execution
• Subgraph composition: Each level invokes specialized subgraphs
• Parallel execution: Task executor runs multiple tasks concurrently
• Context override: Each subgraph can customize context settings
• Large context window: Supports complex multi-level planning

Use Cases:

• Large-scale project planning
• Multi-team coordination
• Complex system refactoring
• Hierarchical decomposition tasks

---

Multi-Level Planner/Executor Graph

Purpose: Separate planning and execution phases with feedback loops.

name: workflows/planner_executor_loop
type: graph
description: Iterative planning and execution with feedback
version: "1.0"

model: gpt-4

route:
  nodes:
    # Phase 1: Planning
    - id: requirements_analyzer
      type: agent
      name: Requirements Analyzer
      description: Analyzes and clarifies requirements
      config:
        model: gpt-4
        prompt: "Analyze requirements and identify ambiguities"
        tools:
          - files/read_file

    - id: plan_generator
      type: subgraph
      name: Plan Generator
      description: Generates detailed execution plan
      config:
        actor_path: examples/actors/strategists/task_planner.yaml

    # Phase 2: Execution
    - id: executor_pool
      type: subgraph
      name: Executor Pool
      description: Parallel task execution
      config:
        actor_path: examples/actors/executors/code_writer.yaml
        parallel: true
        max_parallel: 5

    # Phase 3: Validation
    - id: validator
      type: subgraph
      name: Validator
      description: Validates execution results
      config:
        actor_path: examples/actors/validators/python_checker.yaml

    # Phase 4: Decision Point - CONDITIONAL
    - id: validation_check
      type: conditional
      name: Validation Check
      description: Decides next action based on validation
      config:
        conditions:
          - check: "state.get('validation_passed') == True"
            route_to: final_review
          - check: "state.get('validation_passed') == False and state.get('iteration', 0) < 3"
            route_to: issue_analyzer
          - check: "state.get('validation_passed') == False and state.get('iteration', 0) >= 3"
            route_to: escalate_to_human

    # Feedback Loop: Analyze Issues
    - id: issue_analyzer
      type: agent
      name: Issue Analyzer
      description: Analyzes validation failures
      config:
        model: gpt-4
        prompt: "Analyze validation failures and suggest fixes"
        tools:
          - files/read_file

    # Feedback Loop: Replanning
    - id: replanner
      type: subgraph
      name: Replanner
      description: Creates corrective plan
      config:
        actor_path: examples/actors/strategists/task_planner.yaml
        context_override:
          additional_context: "Previous execution failed. Focus on issues."

    # Final Review
    - id: final_review
      type: subgraph
      name: Final Reviewer
      description: Comprehensive final review
      config:
        actor_path: examples/actors/reviewers/quality_gate.yaml

    # Escalation
    - id: escalate_to_human
      type: tool
      name: Human Escalation
      description: Escalates to human intervention
      config:
        tool_name: notifications/send_alert
        parameters:
          priority: high

  edges:
    # Planning phase
    - from_node: requirements_analyzer
      to_node: plan_generator

    # Execution phase
    - from_node: plan_generator
      to_node: executor_pool

    # Validation phase
    - from_node: executor_pool
      to_node: validator
    - from_node: validator
      to_node: validation_check

    # Feedback loop
    - from_node: issue_analyzer
      to_node: replanner
    - from_node: replanner
      to_node: executor_pool  # Back to execution

  entry_node: requirements_analyzer
  exit_nodes:
    - final_review
    - escalate_to_human

context_view: strategist
memory:
  enabled: true
  max_messages: 150
  max_tokens: 24000
  summarize_old: true

Key Features:

• Multi-phase workflow: Requirements → Plan → Execute → Validate → Review
• Feedback loop: Failed validation triggers replanning and re-execution
• Iteration limiting: Maximum 3 attempts before human escalation
• Parallel execution: Multiple executors run concurrently
• Context preservation: Memory carries through iterations

Use Cases:

• Iterative development workflows
• Self-correcting automation
• Quality-gated deployment pipelines
• Complex refactoring with validation

---

---

Strategy Actor with Subplan Spawning

Strategist Using builtin/plan-subplan

File: examples/actors/strategy_with_subplan.yaml

Purpose: Demonstrates a strategy actor that emits SUBPLAN_SPAWN or SUBPLAN_PARALLEL_SPAWN decisions using the built-in builtin/plan-subplan tool.

name: strategists/subplan_coordinator
type: llm
description: Strategy actor that decomposes goals into child subplans
version: "1.0"

model: gpt-4
context_view: strategist

tools:
  - builtin/plan-subplan

Key Features:

• Uses builtin/plan-subplan to emit typed subplan decisions
• Supports serial (SUBPLAN_SPAWN) and parallel (SUBPLAN_PARALLEL_SPAWN) spawning
• Optional DecisionService injection for persistent decision recording
• merge_strategy, max_parallel, dependencies, and context_view are all configurable per spawn call

Use Cases:

• Decomposing large plans into independently executable child plans
• Coordinating parallel workstreams with dependency tracking
• Recording auditable decision trees for plan explain output

---

Best Practices

Naming Conventions

✅ Good:

• assistants/code_reviewer
• strategists/task_planner
• executors/code_writer
• workflows/test_driven_dev

❌ Bad:

• CodeReviewer (not namespaced)
• assistant-1 (not descriptive)
• my_actor (ambiguous namespace)

Context Configuration

• Strategist actors: Large context (32k-64k tokens), broad file access
• Executor actors: Medium context (16k tokens), focused on implementation
• Reviewer actors: Medium-large context (24k tokens), access to standards
• Validation actors: Small context (8k tokens), focused on specific checks

Memory Settings

• Simple tasks: Disable memory or use small buffer (10-20 messages)
• Planning tasks: Large memory (50-100 messages) with summarization
• Execution tasks: Medium memory (20-40 messages)
• Stateless validators: Disable memory

Tool Selection

• Read-only actors: Only query tools (read, list, diff, status)
• Write actors: Full tool access (read, write, create, delete)
• Validators: Read + linting/testing tools only

---

Testing Your Actors

All example actors in examples/actors/ are validated through automated tests:

1. Schema Validation (features/actor_schema.feature)

   • Ensures YAML structure is valid
   • Validates required fields present
   • Checks namespaced names format

2. Loading Tests (robot/actor_schema.robot)

   • Loads each example file
   • Verifies parsing succeeds
   • Checks expected fields

3. Integration Tests

   • Tests actor invocation
   • Validates tool execution
   • Checks context assembly

Run tests with:

nox -s unit_tests        # Behave tests
nox -s integration_tests # Robot tests

---

Related Documentation

• Actor YAML Schema Reference - Complete schema specification
• Skill Registry - Skills used by actors
• Tool Router - Tools available to actors
• Specification: Actor section (lines 8800+)

---

Last Updated: 2026-02-18
Schema Version: 1.0