cleveragents-core/docs/reference/actor_configuration_examples.md

Actor Configuration Examples

Practical examples and patterns for configuring CleverAgents v3 actors.

Table of Contents

• Basic Patterns
• Common Use Cases
• Advanced Patterns
• Anti-Patterns

---

Basic Patterns

Pattern: Simple Q&A Actor

Use case: Answer questions without file access or tools.

version: "3"
name: qa-assistant
description: Simple question-answering assistant
type: llm
provider: openai
model: gpt-4-turbo
temperature: 0.7

system_prompt: |
  You are a knowledgeable assistant. Answer questions clearly and concisely.
  Provide examples when helpful.

memory:
  enabled: true
  max_turns: 10

When to use:

• General Q&A
• Conceptual explanations
• No file operations needed

---

Pattern: File Reader Actor

Use case: Read and analyze files.

version: "3"
name: file-inspector
description: Reads and analyzes file contents
type: llm
provider: openai
model: gpt-4-turbo
temperature: 0.5

system_prompt: |
  You analyze file contents. Use read_file to examine files.
  Provide insights about structure, patterns, and quality.

tools:
  - name: read_file
    description: Read file contents
    parameters:
      - name: path
        type: string
        description: File path
    code: |
      result = context.get_file(input_data["path"])
    timeout: 10

context:
  view: executor
  include_files:
    - "src/**/*.py"
  max_file_size_kb: 200

When to use:

• Code review preparation
• File analysis
• Content inspection

---

Pattern: Sequential Workflow

Use case: Multi-step process with clear sequence.

version: "3"
name: sequential-pipeline
description: Three-step sequential workflow
type: graph
provider: openai
model: gpt-4-turbo

routes:
  entry_point: step_1
  
  nodes:
    step_1:
      type: agent
      prompt: First step - gather information
    
    step_2:
      type: agent
      prompt: Second step - process information
    
    step_3:
      type: agent
      prompt: Third step - generate output
  
  edges:
    - source: step_1
      target: step_2
    - source: step_2
      target: step_3

When to use:

• Clear sequential steps
• No branching logic needed
• Simple workflows

---

Common Use Cases

Use Case: Code Review Actor

Problem: Need automated code review with security, style, and performance checks.

Solution:

version: "3"
name: comprehensive-reviewer
description: Multi-faceted code review
type: graph
provider: openai
model: gpt-4-turbo
temperature: 0.4

routes:
  entry_point: coordinator
  
  nodes:
    coordinator:
      type: agent
      prompt: |
        Analyze code changes. Determine which checks are needed:
        - security (if handling user input, auth, data)
        - style (always)
        - performance (if loops, database, API calls)
        
        Output: LIST_OF_CHECKS: [check1, check2, ...]
    
    security:
      type: subgraph
      actor: local/security-checker
    
    style:
      type: subgraph
      actor: local/style-checker
    
    performance:
      type: subgraph
      actor: local/performance-checker
    
    aggregator:
      type: agent
      prompt: |
        Combine all review results. Provide:
        1. Summary of findings
        2. Critical issues (must fix)
        3. Suggestions (nice to have)
        4. Overall assessment: APPROVE/NEEDS_WORK/REJECT
  
  edges:
    - source: coordinator
      target: security
    - source: coordinator
      target: style
    - source: coordinator
      target: performance
    - source: security
      target: aggregator
    - source: style
      target: aggregator
    - source: performance
      target: aggregator

context:
  view: reviewer
  include_files:
    - "**/*.py"
    - "**/*.diff"
    - ".pylintrc"

memory:
  enabled: true
  max_turns: 20

Why this works:

• Hierarchical decomposition (coordinator + specialists)
• Reusable specialist actors
• Parallel execution of checks
• Clear aggregation step

---

Use Case: Research and Documentation

Problem: Research a topic across codebase and generate documentation.

Solution:

version: "3"
name: doc-generator
description: Research codebase and generate documentation
type: graph
provider: openai
model: gpt-4-turbo
temperature: 0.6

routes:
  entry_point: researcher
  
  nodes:
    researcher:
      type: agent
      prompt: |
        Research the topic across the codebase:
        1. Find relevant files
        2. Extract key information
        3. Identify patterns and examples
        
        Use search_files and read_file tools.
    
    outliner:
      type: agent
      prompt: |
        Create a documentation outline based on research:
        - Introduction
        - Key Concepts
        - Examples
        - API Reference
        - Best Practices
    
    writer:
      type: agent
      prompt: |
        Write comprehensive documentation following the outline.
        Include code examples and clear explanations.
    
    reviewer:
      type: agent
      prompt: |
        Review documentation for:
        - Accuracy
        - Completeness
        - Clarity
        - Examples work correctly
        
        Output: APPROVED or NEEDS_REVISION: [specific issues]
    
    router:
      type: conditional
  
  edges:
    - source: researcher
      target: outliner
    - source: outliner
      target: writer
    - source: writer
      target: reviewer
    - source: reviewer
      target: router
    - source: router
      target: end
      condition: 'content_contains("APPROVED")'
    - source: router
      target: writer
      condition: 'content_contains("NEEDS_REVISION")'

tools:
  - name: search_files
    description: Search for patterns in files
    parameters:
      - name: pattern
        type: string
        description: Regex pattern
      - name: file_glob
        type: string
        description: File pattern
        default: "**/*.py"
    code: |
      import re
      matches = context.search_files(
          input_data.get("file_glob", "**/*.py"),
          input_data["pattern"]
      )
      result = {"matches": matches[:20]}

memory:
  enabled: true
  max_turns: 40

context:
  view: strategist
  include_files:
    - "src/**/*.py"
    - "docs/**/*.md"
    - "README.md"

Why this works:

• Research before writing
• Structured outlining phase
• Iterative refinement with reviewer
• Appropriate context view (strategist for high-level)

---

Use Case: Test Generation

Problem: Generate unit tests for existing code.

Solution:

version: "3"
name: test-generator
description: Generates unit tests for code
type: llm
provider: openai
model: gpt-4-turbo
temperature: 0.3

system_prompt: |
  You generate comprehensive unit tests for Python code.
  
  Process:
  1. Read the source file
  2. Identify functions and classes to test
  3. Generate test cases covering:
     - Happy path
     - Edge cases
     - Error conditions
  4. Write tests using pytest
  5. Verify test structure is correct
  
  Test format:
  - One test file per source file (test_<module>.py)
  - Descriptive test names (test_<function>_<scenario>)
  - Arrange-Act-Assert pattern
  - Fixtures for common setup

tools:
  - name: read_source
    description: Read source file to generate tests for
    parameters:
      - name: path
        type: string
        description: Path to source file
    code: |
      result = context.get_file(input_data["path"])

  - name: write_test
    description: Write generated test file
    parameters:
      - name: path
        type: string
        description: Test file path
      - name: content
        type: string
        description: Test file content
    code: |
      context.write_file(input_data["path"], input_data["content"])
      result = {"written": input_data["path"]}

context:
  view: executor
  include_files:
    - "src/**/*.py"
  exclude_files:
    - "**/test_*.py"
  max_file_size_kb: 200

memory:
  enabled: true
  max_turns: 15

Why this works:

• Focused on test generation task
• Low temperature for consistent test patterns
• Executor view for precise code access
• Clear system prompt with test guidelines

---

Advanced Patterns

Pattern: Iterative Refinement with Limits

Use case: Iteratively improve output with max iteration limit.

version: "3"
name: iterative-writer
description: Writes and refines content iteratively
type: graph
provider: openai
model: gpt-4-turbo

routes:
  entry_point: writer
  
  nodes:
    writer:
      type: agent
      prompt: Write content. Iteration {{state.iteration}} of {{state.max_iterations}}
    
    evaluator:
      type: agent
      prompt: |
        Evaluate quality (1-10). If <8, provide specific improvements needed.
    
    router:
      type: conditional
  
  edges:
    - source: writer
      target: evaluator
    - source: evaluator
      target: router
    - source: router
      target: end
      condition: 'score >= 8 or state.iteration >= state.max_iterations'
    - source: router
      target: writer
      condition: 'score < 8 and state.iteration < state.max_iterations'

metadata:
  max_iterations: 5

Why this pattern:

• Prevents infinite loops
• Quality-driven iteration
• Clear termination conditions

---

Pattern: Parallel Processing with Aggregation

Use case: Process multiple items in parallel, then aggregate.

version: "3"
name: parallel-analyzer
description: Analyzes multiple files in parallel
type: graph
provider: openai
model: gpt-4-turbo

routes:
  entry_point: splitter
  
  nodes:
    splitter:
      type: agent
      prompt: |
        Split task into independent subtasks.
        Output: SUBTASKS: [task1, task2, task3]
    
    processor_1:
      type: agent
      prompt: Process subtask 1
    
    processor_2:
      type: agent
      prompt: Process subtask 2
    
    processor_3:
      type: agent
      prompt: Process subtask 3
    
    aggregator:
      type: agent
      prompt: Combine results from all processors
  
  edges:
    - source: splitter
      target: processor_1
    - source: splitter
      target: processor_2
    - source: splitter
      target: processor_3
    - source: processor_1
      target: aggregator
    - source: processor_2
      target: aggregator
    - source: processor_3
      target: aggregator

Why this pattern:

• Parallel execution (when supported by runtime)
• Independent subtasks
• Centralized aggregation

---

Pattern: Specialist Delegation

Use case: Coordinator delegates to domain-specific specialists.

version: "3"
name: smart-coordinator
description: Intelligent task routing to specialists
type: graph
provider: openai
model: gpt-4-turbo

routes:
  entry_point: coordinator
  
  nodes:
    coordinator:
      type: agent
      prompt: |
        Analyze the task. Route to appropriate specialist:
        - backend-specialist: API, database, server logic
        - frontend-specialist: UI, components, styling
        - devops-specialist: deployment, infrastructure, CI/CD
        - fullstack-specialist: cross-cutting concerns
        
        Output: ROUTE_TO: <specialist_name>
    
    router:
      type: conditional
    
    backend_specialist:
      type: subgraph
      actor: local/backend-expert
    
    frontend_specialist:
      type: subgraph
      actor: local/frontend-expert
    
    devops_specialist:
      type: subgraph
      actor: local/devops-expert
    
    fullstack_specialist:
      type: subgraph
      actor: local/fullstack-expert
  
  edges:
    - source: coordinator
      target: router
    - source: router
      target: backend_specialist
      condition: 'content_contains("ROUTE_TO: backend")'
    - source: router
      target: frontend_specialist
      condition: 'content_contains("ROUTE_TO: frontend")'
    - source: router
      target: devops_specialist
      condition: 'content_contains("ROUTE_TO: devops")'
    - source: router
      target: fullstack_specialist
      condition: 'content_contains("ROUTE_TO: fullstack")'

Why this pattern:

• Domain expertise specialization
• Clear routing logic
• Reusable specialists

---

Anti-Patterns

❌ Anti-Pattern: Overly Complex Graphs

Problem:

routes:
  entry_point: step_1
  nodes:
    step_1: {...}
    step_2: {...}
    step_3: {...}
    # ... 20 more nodes
  edges:
    # ... 50+ edges with complex conditions

Why it's bad:

• Hard to understand and maintain
• Difficult to debug
• Likely has hidden bugs in conditions
• Poor performance

Better approach:

# Break into multiple actors
# Use hierarchical composition
routes:
  entry_point: phase_1
  nodes:
    phase_1:
      type: subgraph
      actor: local/phase-1-workflow
    phase_2:
      type: subgraph
      actor: local/phase-2-workflow

---

❌ Anti-Pattern: Ignoring Context Views

Problem:

context:
  view: full  # Always using full context

Why it's bad:

• Wastes tokens on irrelevant files
• Slower performance
• May exceed context limits on large projects

Better approach:

# Use specific view for the role
context:
  view: strategist  # For planning
  # or
  view: executor    # For implementation
  # or
  view: reviewer    # For validation

---

❌ Anti-Pattern: No Memory Limits

Problem:

memory:
  enabled: true
  max_turns: 1000  # Way too high

Why it's bad:

• Excessive token usage
• Slower responses
• Costs escalate quickly
• Older context becomes irrelevant

Better approach:

memory:
  enabled: true
  max_turns: 20  # Reasonable limit

---

❌ Anti-Pattern: Tool Without Error Handling

Problem:

tools:
  - name: divide
    code: |
      result = input_data["a"] / input_data["b"]

Why it's bad:

• No validation
• Division by zero crashes
• No error messages for LLM

Better approach:

tools:
  - name: divide
    code: |
      a = input_data.get("a")
      b = input_data.get("b")
      
      if a is None or b is None:
          result = {"error": "Missing parameters a or b"}
      elif b == 0:
          result = {"error": "Cannot divide by zero"}
      else:
          result = {"value": a / b, "success": True}

---

❌ Anti-Pattern: Vague System Prompts

Problem:

system_prompt: "You are a helpful assistant."

Why it's bad:

• No specific guidance
• Unpredictable behavior
• LLM doesn't know available tools
• No output format specified

Better approach:

system_prompt: |
  You are a code review assistant specializing in Python.
  
  Your tasks:
  1. Read code using read_file tool
  2. Identify issues: security, style, performance
  3. Provide specific, actionable feedback
  
  Output format:
  ## Issues Found
  - [SEVERITY] [File:Line] [Description]
  
  ## Recommendations
  - [Specific fix with code example]
  
  Available tools:
  - read_file(path): Read source code
  - search_files(pattern): Find code patterns

---

❌ Anti-Pattern: Circular Actor References

Problem:

# actor-a.yaml
routes:
  nodes:
    step:
      type: subgraph
      actor: local/actor-b

# actor-b.yaml
routes:
  nodes:
    step:
      type: subgraph
      actor: local/actor-a  # Circular!

Why it's bad:

• Infinite recursion
• Stack overflow
• Impossible to compile

Better approach:

# Extract common logic to shared actor
# actor-a and actor-b both reference actor-shared
# No circular dependencies

---

See Also

• Actor Configuration Reference
• Actor Compilation Guide
• Best Practices for Actor Design