cleveragents-core/docs/reference/actor_configuration.md

Actor Configuration API Reference

Overview

CleverAgents uses an actor-first architecture where all AI interactions are performed through actors. Actors encapsulate provider, model, and configuration details into a single reusable entity.

Actor Configuration Format

Actor configurations use YAML or JSON format and must conform to the v2 schema. No alternative schemas or extensions are supported.

Basic Structure

# Minimal actor configuration
provider: openai
model: gpt-4

# Extended configuration with options
provider: anthropic
model: claude-3-opus
options:
  temperature: 0.7
  max_tokens: 4000
  
# Graph-based actor with tools
graph: ToolAgentGraph
provider: openai
model: gpt-4
tools:
  - name: code_search
    description: Search codebase for patterns
  - name: file_reader
    description: Read file contents
options:
  temperature: 0.5

Configuration Fields

Core Fields

provider (required)

• Type: string
• Description: The AI provider to use
• Valid Values: openai, anthropic, google, azure, groq, cohere, together, gemini, openrouter, mock
• Example: provider: openai

model (required)

• Type: string
• Description: The specific model from the provider
• Examples:
  • OpenAI: gpt-4, gpt-3.5-turbo
  • Anthropic: claude-3-opus, claude-3-sonnet
  • Google: gemini-pro, gemini-pro-vision

graph (optional)

• Type: string
• Description: The LangGraph workflow to use
• Default: BasicChatGraph
• Available Graphs:
  • BasicChatGraph - Simple chat completion
  • PlanGenerationGraph - Multi-step plan generation
  • ContextAnalysisAgent - Code analysis workflow
  • AutoDebugGraph - Error detection and fixing
  • ToolAgentGraph - Tool-calling agent

options (optional)

• Type: object
• Description: Provider-specific configuration options
• Common Options:

  options:
    temperature: 0.7          # Creativity (0.0-1.0)
    max_tokens: 4000         # Maximum response length
    top_p: 0.9              # Nucleus sampling
    frequency_penalty: 0.0   # Reduce repetition
    presence_penalty: 0.0    # Encourage new topics
    stop: ["```", "\n\n"]   # Stop sequences
  

Advanced Fields

tools (optional)

• Type: array
• Description: Tools available to the actor (requires compatible graph)
• Structure:

  tools:
    - name: tool_name
      description: What the tool does
      parameters:
        param1: string
        param2: number
  

context (optional)

• Type: object
• Description: Initial context variables injected at runtime
• Example:

  context:
    project_type: web_app
    language: python
    framework: fastapi
  

unsafe (optional)

• Type: boolean
• Description: Explicitly mark configuration as unsafe
• Default: Auto-detected based on content
• Note: Unsafe actors require --unsafe flag when adding

Graph Descriptors

Graph descriptors are automatically generated from the configuration and describe the actor's capabilities:

{
  "type": "PlanGenerationGraph",
  "capabilities": ["streaming", "retry", "validation"],
  "nodes": ["analyze", "generate", "validate"],
  "edges": ["conditional", "retry"],
  "requires_context": true
}

Capability Flags

• streaming - Supports real-time output streaming
• retry - Has built-in retry logic
• validation - Validates outputs before returning
• tools - Can use external tools
• memory - Maintains conversation history
• context - Requires or uses context

Unsafe Detection Rules

Configurations are analyzed for potentially unsafe operations:

Automatically Detected as Unsafe

1. Shell/System Access

   tools:
     - name: shell_execute
       description: Execute shell commands
   

2. File System Writes

   tools:
     - name: file_write
       description: Write to filesystem
       parameters:
         path: string
         content: string
   

3. Network Access

   tools:
     - name: http_request
       description: Make HTTP requests
   

4. Code Execution

   graph: CodeExecutionGraph
   options:
     allow_exec: true
   

Marking as Safe

If auto-detection incorrectly flags a configuration:

# Override auto-detection
unsafe: false
provider: openai
model: gpt-4
# ... rest of config

Environment Variable Interpolation

Actor configurations support environment variable interpolation:

provider: openai
model: ${MODEL_NAME:-gpt-4}
options:
  api_key: ${OPENAI_API_KEY}
  temperature: ${TEMPERATURE:-0.7}
  max_tokens: ${MAX_TOKENS:-4000}

Interpolation Syntax

• ${VAR} - Use environment variable VAR
• ${VAR:-default} - Use VAR or default value if not set
• ${VAR:?error message} - Error if VAR not set

Provider/Model Mapping

Actor configurations map to provider implementations:

OpenAI Example

provider: openai
model: gpt-4

Maps to:

• Provider class: OpenAIProvider
• Model identifier: gpt-4
• API endpoint: https://api.openai.com/v1

Custom Endpoints

provider: openai
model: gpt-4
options:
  base_url: http://localhost:8080/v1
  api_key: local-key

Configuration Hash Calculation

The configuration hash is a SHA-256 digest of the canonical JSON representation:

1. Parse YAML/JSON to object
2. Remove comments and formatting
3. Sort keys alphabetically
4. Serialize to canonical JSON
5. Calculate SHA-256 hash

Example:

config_hash = hashlib.sha256(
    json.dumps(config, sort_keys=True).encode()
).hexdigest()

Usage in Commands

Creating Custom Actors

# From configuration file
agents actor add --name assistant --config ./assistant.yaml

# Results in actor: local/assistant

Using Actors

# Use specific actor
agents tell "refactor this function" --actor local/assistant

# Use with options override
agents build --actor openai/gpt-4 --option temperature=0.2

Built-in Actor Names

Built-in actors follow the pattern <provider>/<model>:

• openai/gpt-4
• openai/gpt-3.5-turbo
• anthropic/claude-3-opus
• google/gemini-pro
• mock/test-model

Error Handling

Common Configuration Errors

1. Missing Required Fields

   ERROR: Configuration missing required field 'provider'
   

2. Invalid Provider/Model

   ERROR: Unknown provider 'invalid'
   

3. Unsafe Without Flag

   ERROR: Configuration appears unsafe. Add --unsafe flag to confirm.
   

4. Invalid YAML/JSON

   ERROR: Failed to parse configuration: expected ':', got '}'
   

Best Practices

1. Use Descriptive Names

   agents actor add --name code-reviewer --config ./reviewer.yaml
   

2. Set Appropriate Options

   # For code generation
   options:
     temperature: 0.2  # Lower for consistency
     max_tokens: 8000  # Higher for complete code
   

3. Document Custom Actors

   # Code review assistant optimized for Python
   provider: openai
   model: gpt-4
   context:
     purpose: code_review
     language: python
   

4. Version Control Configurations

   • Store actor configs in ./actors/ directory
   • Track changes in git
   • Use meaningful commit messages