# Actor Configuration Examples Practical examples and patterns for configuring CleverAgents v3 actors. ## Table of Contents - [Basic Patterns](#basic-patterns) - [Common Use Cases](#common-use-cases) - [Advanced Patterns](#advanced-patterns) - [Anti-Patterns](#anti-patterns) --- ## Basic Patterns ### Pattern: Simple Q&A Actor **Use case:** Answer questions without file access or tools. ```yaml 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. ```yaml 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. ```yaml 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:** ```yaml 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:** ```yaml 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:** ```yaml 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_.py) - Descriptive test names (test__) - 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. ```yaml 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. ```yaml 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. ```yaml 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: 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:** ```yaml 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:** ```yaml # 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:** ```yaml 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:** ```yaml # 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:** ```yaml 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:** ```yaml memory: enabled: true max_turns: 20 # Reasonable limit ``` --- ### ❌ Anti-Pattern: Tool Without Error Handling **Problem:** ```yaml 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:** ```yaml 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:** ```yaml 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:** ```yaml 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:** ```yaml # 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:** ```yaml # Extract common logic to shared actor # actor-a and actor-b both reference actor-shared # No circular dependencies ``` --- ## See Also - [Actor Configuration Reference](./actor_configuration.md) - [Actor Compilation Guide](./actor_compilation.md) - [Best Practices for Actor Design](./actor_best_practices.md)