cleveragents-core/docs/reference/actor_configuration.md

Actor Configuration Reference

Version: 3.0
Last Updated: 2026-02
Status: Stable

Overview

Actor configurations define how AI agents behave in CleverAgents v3. They are YAML files compiled to executable LangGraph workflows.

Key Concepts

• Actor: A configured AI agent that performs specific tasks
• Type: Determines actor behavior (LLM, TOOL, GRAPH)
• Compilation: YAML configs are compiled to LangGraph at runtime
• Composition: Actors can reference other actors (hierarchical design)

---

Top-Level Schema

version: "3"                    # Required: Schema version
name: string                    # Required: Actor identifier
description: string             # Required: Human-readable description
type: llm|tool|graph           # Required: Actor type

# LLM Configuration
provider: string                # Optional: openai, anthropic, google, etc.
model: string                   # Optional: Model identifier
temperature: float              # Optional: 0.0-2.0, default varies by type
system_prompt: string           # Optional: System prompt text

# Tools and Skills
tools: [ToolDefinition]         # Optional: Inline tool definitions
metadata:
  builtin_tools: [string]       # Optional: Built-in tool names

# Graph Topology (type=graph only)
routes: RouteDefinition         # Required for GRAPH actors

# Memory and Context
memory: MemoryConfig            # Optional: Conversation history settings
context: ContextConfigSchema    # Optional: Context window configuration

---

Field Definitions

Required Fields

version (string)

Schema version. Must be "3" for CleverAgents v3.

version: "3"

name (string)

Unique identifier for the actor. Used for references and logging.

Rules:

• Must be valid identifier (letters, numbers, hyphens, underscores)
• Should be descriptive and concise
• Case-insensitive for lookups

name: code-writer
name: security-analyzer
name: default-strategist

type (ActorType enum)

Determines how the actor is compiled and executed.

Values:

• llm: Simple single-agent with optional tools
• tool: Agent focused on tool execution (deprecated, use llm with tools)
• graph: Multi-node workflow with routing

type: llm       # Single agent
type: tool      # Tool-focused agent
type: graph     # Complex workflow

Type-specific requirements:

• llm: Requires model (provider optional if default set)
• tool: Requires model and at least one tool
• graph: Requires routes field

description (string)

Human-readable explanation of what the actor does.

description: Analyzes code for security vulnerabilities
description: Multi-step research and writing workflow
description: Default strategist for planning phase

LLM Configuration

provider (string, optional)

LLM provider identifier. If not specified, uses system default.

Supported providers:

• openai: OpenAI (GPT models)
• anthropic: Anthropic (Claude models)
• google: Google (Gemini models)
• azure: Azure OpenAI
• local: Local model server

provider: openai
provider: anthropic
provider: google

model (string, optional but recommended)

Model identifier specific to the provider.

OpenAI models:

model: gpt-4-turbo
model: gpt-4
model: gpt-3.5-turbo

Anthropic models:

model: claude-3-opus-20240229
model: claude-3-sonnet-20240229
model: claude-3-haiku-20240307

Google models:

model: gemini-pro
model: gemini-ultra

temperature (float, optional)

Sampling temperature for LLM outputs. Controls randomness.

Range: 0.0 - 2.0
Default: Varies by use case

• Strategy actors: 0.3 (more deterministic)
• Execution actors: 0.2 (very precise)
• General use: 0.7 (balanced)

temperature: 0.2   # Precise, deterministic
temperature: 0.7   # Balanced
temperature: 1.2   # Creative, varied

system_prompt (string, optional)

System-level prompt that defines the actor's behavior, personality, and constraints.

Best practices:

• Be specific about the actor's role
• Include output format requirements
• List available tools and when to use them
• Provide examples of good outputs
• Set clear boundaries and rules

system_prompt: |
  You are a code reviewer. Analyze code for:
  1. Security vulnerabilities
  2. Performance issues
  3. Code style violations
  
  Provide specific, actionable feedback with line numbers.

---

Tool Configuration

Inline Tools

Define custom tools with Python code that runs in a sandboxed environment.

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

ToolDefinition Schema

name: string                    # Required: Tool identifier
description: string             # Required: What the tool does (for LLM)
parameters: [ToolParameter]     # Optional: List of parameters
code: string                    # Required: Python code to execute
timeout: integer                # Optional: Timeout in seconds (default: 30)

ToolParameter Schema

name: string                    # Required: Parameter name
type: string                    # Required: JSON Schema type
description: string             # Required: What the parameter is for
required: boolean               # Optional: Default true
default: any                    # Optional: Default value if not provided
enum: [string]                  # Optional: Allowed values

JSON Schema types:

• string: Text values
• integer: Whole numbers
• number: Floating point numbers
• boolean: true/false
• object: JSON objects
• array: Lists
• null: Null value

Sandboxed Execution Environment

Inline tool code runs in a restricted Python environment:

Available:

• context: SkillContext instance (file operations, sandbox access)
• input_data: Dict of parameters passed by LLM
• Standard library: re, json, datetime, collections, math
• Safe builtins: len, range, str, int, float, list, dict

Restricted:

• open, exec, eval, compile, __import__
• File system access (must use context methods)
• Network access
• System calls

Example:

# Available in tool code
import json
import re
from datetime import datetime

# Access file through context
content = context.get_file(input_data["path"])

# Process data
lines = content.split("\n")
matches = [l for l in lines if re.search(input_data["pattern"], l)]

# Return result (must set 'result' variable)
result = {
    "matches": matches,
    "count": len(matches),
    "timestamp": datetime.now().isoformat()
}

Built-in Tools

Reference pre-implemented tools from CleverAgents core:

metadata:
  builtin_tools:
    - read_file
    - write_file
    - delete_file
    - list_directory
    - search_files
    - run_command

---

Graph Configuration (type=graph)

RouteDefinition Schema

routes:
  entry_point: string           # Required: Starting node name
  nodes:                        # Required: Dict of node name to NodeDefinition
    node_name: NodeDefinition
  edges: [EdgeDefinition]       # Optional: Connections between nodes

NodeDefinition Schema

type: agent|tool|conditional|subgraph  # Required: Node type
prompt: string                  # For agent nodes: LLM prompt
tool: string                    # For tool nodes: Tool name to execute
actor: string                   # For subgraph nodes: Actor reference
condition: string               # For conditional nodes: Condition expression

Node types:

1. agent: Makes an LLM call

planner:
  type: agent
  prompt: |
    Analyze the task and create a plan.

2. tool: Executes a tool/skill

validator:
  type: tool
  tool: run_tests

3. conditional: Routes based on conditions

router:
  type: conditional
  condition: state.iteration < max_iterations

4. subgraph: Invokes another actor

specialist:
  type: subgraph
  actor: local/security-analyzer

EdgeDefinition Schema

source: string                  # Required: Source node name
target: string                  # Required: Target node name
condition: string               # Optional: Condition for traversal
label: string                   # Optional: Edge label for visualization

Edge types:

1. Direct: Always traverse (no condition)

- source: planner
  target: executor

2. Conditional: Traverse only if condition true

- source: checker
  target: retry
  condition: 'content_contains("FAILED")'

3. Default: Fallback when no other conditions match

- source: router
  target: end
  condition: 'not any_other_condition'

Special Node Names

• start: Implicit entry point (optional, use entry_point instead)
• end: Implicit exit point (automatically created)

---

Memory Configuration

memory:
  enabled: boolean              # Default: false
  max_turns: integer            # Default: 10, range: 1-100
  include_system_messages: boolean  # Default: true

Fields

• enabled: Whether to maintain conversation history between invocations
• max_turns: Maximum conversation turns to retain (oldest pruned first)
• include_system_messages: Whether system messages count toward max_turns

Use Cases

Stateless (no memory):

memory:
  enabled: false

Use for: One-shot tasks, independent operations

Short-term memory:

memory:
  enabled: true
  max_turns: 10

Use for: Strategy planning, quick iterations

Long-term memory:

memory:
  enabled: true
  max_turns: 50

Use for: Complex implementations, extended conversations

---

Context Configuration

context:
  view: strategist|executor|reviewer|full  # Default: full
  include_files: [string]       # Glob patterns to include
  exclude_files: [string]       # Glob patterns to exclude
  max_file_size_kb: integer     # Default: 100, range: 1-10000
  include_hidden: boolean       # Default: false

Context Views

strategist: High-level architecture view

context:
  view: strategist
  include_files:
    - "README.md"
    - "docs/**/*.md"
    - "**/__init__.py"
  max_file_size_kb: 50

executor: Focused implementation view

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

reviewer: Validation and quality view

context:
  view: reviewer
  include_files:
    - "**/*.diff"
    - "**/*.test.*"
    - ".pylintrc"
  max_file_size_kb: 200

full: Complete project view (default)

context:
  view: full
  exclude_files:
    - "**/node_modules/**"
    - "**/__pycache__/**"

Glob Patterns

Standard glob syntax supported:

• *: Match any characters except /
• **: Match any characters including /
• ?: Match single character
• [abc]: Match any character in brackets
• {a,b}: Match either a or b

Examples:

include_files:
  - "src/**/*.py"           # All Python files under src/
  - "tests/**/test_*.py"    # All test files
  - "*.{md,txt}"            # All .md and .txt files in root
  - "docs/[a-z]*.md"        # docs/ .md files starting with lowercase

---

Metadata Configuration

metadata:
  timeout_seconds: integer      # Total execution timeout
  max_iterations: integer       # Max LLM calls per invocation
  builtin_tools: [string]       # Built-in tools to include
  
  # Custom metadata (actor-specific)
  custom_key: value

Common metadata fields:

metadata:
  timeout_seconds: 300          # 5 minutes
  max_iterations: 50            # Limit LLM calls
  
  # Strategy-specific
  strategy_config:
    max_steps: 15
    require_decision_rationale: true
  
  # Execution-specific
  execution_config:
    verify_syntax: true
    run_linter: true
  
  # Subgraph-specific
  subgraph_config:
    inherit_context: true
    subgraph_timeout: 180

---

Complete Examples

Minimal LLM Actor

version: "3"
name: simple-assistant
description: Basic coding assistant
type: llm
provider: openai
model: gpt-4-turbo
system_prompt: You are a helpful coding assistant.

Tool Actor with Inline Tools

version: "3"
name: file-analyzer
description: Analyzes file contents
type: llm
provider: openai
model: gpt-4-turbo

tools:
  - name: count_lines
    description: Count lines in a file
    parameters:
      - name: path
        type: string
        description: File path
    code: |
      content = context.get_file(input_data["path"])
      result = {"line_count": len(content.split("\n"))}

memory:
  enabled: true
  max_turns: 10

Graph Actor with Workflow

version: "3"
name: code-pipeline
description: Code generation and validation pipeline
type: graph
provider: openai
model: gpt-4-turbo

routes:
  entry_point: generator
  
  nodes:
    generator:
      type: agent
      prompt: Generate code based on requirements
    
    validator:
      type: tool
      tool: run_tests
    
    reviewer:
      type: subgraph
      actor: local/code-reviewer
    
    router:
      type: conditional
  
  edges:
    - source: generator
      target: validator
    - source: validator
      target: router
    - source: router
      target: reviewer
      condition: 'content_contains("PASS")'
    - source: router
      target: generator
      condition: 'content_contains("FAIL")'

memory:
  enabled: true
  max_turns: 30

---

Validation Rules

Schema Validation

1. Version check: Must be "3"
2. Type requirements:
   • llm: Must have model or system default configured
   • graph: Must have routes field
3. Tool names: Must be unique within actor
4. Graph topology:
   • Entry point must exist in nodes
   • All edge sources/targets must be valid nodes
   • Node names must be valid identifiers
5. Parameter types: Must be valid JSON Schema types
6. Code syntax: Tool code must be valid Python

Runtime Validation

1. Circular references: Detected across actor boundaries
2. Timeout enforcement: All operations have timeouts
3. Resource limits: File size, iteration counts enforced
4. Security: Sandboxed execution for inline code

---

Best Practices

1. Actor Design

• Single responsibility: Each actor should have one clear purpose
• Composability: Use subgraph nodes for reusable components
• Clear naming: Use descriptive names for actors and nodes
• Documentation: Include detailed descriptions and comments

2. System Prompts

• Be specific: Clearly define the actor's role and constraints
• Provide examples: Show the desired output format
• List tools: Explain when and how to use each tool
• Set boundaries: Define what the actor should NOT do

3. Temperature Settings

• Strategy: 0.3 - Consistent planning
• Execution: 0.2 - Precise code generation
• Review: 0.4 - Balanced analysis
• Creative: 0.8-1.2 - Varied outputs

4. Context Configuration

• Start specific: Use focused views (strategist, executor, reviewer)
• Expand as needed: Only increase scope if necessary
• Exclude aggressively: Remove irrelevant files
• Size limits: Set appropriate max_file_size_kb

5. Memory Management

• Short for strategy: 10-15 turns
• Long for execution: 30-50 turns
• Disable for stateless: One-shot operations

6. Graph Design

• Clear flow: Edges should form logical progression
• Avoid loops: Or ensure loop termination conditions
• Error handling: Include error paths and recovery
• Visualization: Use edge labels for clarity

---

Migration from v2

See Actor Configuration Migration Guide for detailed migration instructions.

Key changes:

• YAML format replaces reactive stream configs
• Simpler, more declarative syntax
• LangGraph compilation replaces RxPY streams
• Hierarchical composition via subgraph nodes
• Built-in context views (strategist, executor, reviewer)

---

See Also

• Actor Configuration Examples
• Actor Compilation Guide
• Skill Development Guide
• LangGraph Integration