cleveragents-core/docs/reference/actor_configuration_migration.md

Actor Configuration Migration Guide (v2 → v3)

Guide for migrating CleverAgents v2 reactive stream configurations to v3 actor configurations.

Overview

What's changing:

• Format: RxPY reactive stream configs → Simple YAML actor configs
• Execution: Reactive streams → LangGraph workflows
• Complexity: Complex observable chains → Declarative actor definitions
• Composition: Stream bridging → Hierarchical subgraph actors

Migration timeline:

• v2 configurations deprecated but supported until v3.5
• New features only available in v3 format
• Gradual migration recommended

---

Key Differences

Architecture

Aspect	v2 (Old)	v3 (New)
Config Format	YAML with reactive streams	YAML with LangGraph topology
Execution Model	RxPY observables	LangGraph state machines
Agent Definition	agents: list with complex routing	type: llm/tool/graph
Workflows	Observable chains + operators	Graph with nodes and edges
Composition	Route bridging	Subgraph actor references
Tool Calling	Separate skill system	Inline tools + built-in skills
Context	Manual file loading	Context views (strategist/executor/reviewer)

Conceptual Mapping

v2 Agent → v3 Actor Types:

• Simple agent → type: llm
• Tool-using agent → type: llm with tools:
• Multi-agent workflow → type: graph with routes:

v2 Routes → v3 Graphs:

• Route chains → Sequential edges
• Conditional routes → Conditional edges with conditions
• Message routing → Graph topology with conditionals

v2 Skills → v3 Tools:

• Registered skills → Built-in tools (metadata.builtin_tools)
• Custom skills → Inline tools (tools: section)
• Skill context → Same SkillContext interface

---

Migration Examples

Example 1: Simple Agent

v2 Configuration:

version: "2"
agents:
  - name: assistant
    model: gpt-4
    provider: openai
    system_prompt: You are a helpful assistant
    temperature: 0.7

routing:
  type: direct
  target: assistant

v3 Configuration:

version: "3"
name: assistant
description: Simple helpful assistant
type: llm
provider: openai
model: gpt-4
temperature: 0.7
system_prompt: You are a helpful assistant

Changes:

• Removed agents: list (one actor per file)
• Removed routing: section (implicit for LLM type)
• Added description field (required)
• Added type: llm to specify actor type

---

Example 2: Agent with Tools

v2 Configuration:

version: "2"
agents:
  - name: file-reader
    model: gpt-4
    provider: openai
    system_prompt: You can read files
    skills:
      - read_file
      - list_directory

routing:
  type: direct
  target: file-reader

v3 Configuration:

version: "3"
name: file-reader
description: Agent that reads and lists files
type: llm
provider: openai
model: gpt-4
system_prompt: You can read files

metadata:
  builtin_tools:
    - read_file
    - list_directory

context:
  view: executor
  include_files:
    - "**/*.py"

Changes:

• skills: → metadata.builtin_tools:
• Added context: section for file access control
• No separate routing section needed

---

Example 3: Multi-Agent Workflow

v2 Configuration:

version: "2"
agents:
  - name: planner
    model: gpt-4
    system_prompt: Plan the task
  
  - name: executor
    model: gpt-4
    system_prompt: Execute the plan
  
  - name: reviewer
    model: gpt-4
    system_prompt: Review the work

routing:
  type: sequential
  routes:
    - from: planner
      to: executor
    - from: executor
      to: reviewer
    - from: reviewer
      to: planner
      condition: needs_revision

v3 Configuration:

version: "3"
name: plan-execute-review
description: Sequential workflow with review loop
type: graph
provider: openai
model: gpt-4

routes:
  entry_point: planner
  
  nodes:
    planner:
      type: agent
      prompt: Plan the task
    
    executor:
      type: agent
      prompt: Execute the plan
    
    reviewer:
      type: agent
      prompt: |
        Review the work.
        Output: APPROVED or NEEDS_REVISION: [issues]
    
    router:
      type: conditional
  
  edges:
    - source: planner
      target: executor
    - source: executor
      target: reviewer
    - source: reviewer
      target: router
    - source: router
      target: end
      condition: 'content_contains("APPROVED")'
    - source: router
      target: planner
      condition: 'content_contains("NEEDS_REVISION")'

memory:
  enabled: true
  max_turns: 30

Changes:

• Multiple agents → Single graph actor with multiple nodes
• agents: list → routes.nodes: dict
• routing.routes: → routes.edges:
• Conditions embedded in edges
• Added explicit router node for conditional logic

---

Example 4: Hierarchical Composition

v2 Configuration:

version: "2"
agents:
  - name: coordinator
    model: gpt-4
    system_prompt: Coordinate review
  
  - name: security-check
    model: gpt-4
    system_prompt: Check security
  
  - name: style-check
    model: gpt-4
    system_prompt: Check style

routing:
  type: bridge
  main: coordinator
  subroutes:
    - agent: security-check
      trigger: needs_security_check
    - agent: style-check
      trigger: needs_style_check

v3 Configuration:

Main actor (coordinator.yaml):

version: "3"
name: coordinator
description: Review coordinator with specialist delegation
type: graph
provider: openai
model: gpt-4

routes:
  entry_point: analyzer
  
  nodes:
    analyzer:
      type: agent
      prompt: Determine which checks are needed
    
    security_check:
      type: subgraph
      actor: local/security-checker
    
    style_check:
      type: subgraph
      actor: local/style-checker
    
    aggregator:
      type: agent
      prompt: Combine all review results
  
  edges:
    - source: analyzer
      target: security_check
    - source: analyzer
      target: style_check
    - source: security_check
      target: aggregator
    - source: style_check
      target: aggregator

Specialist actors (security-checker.yaml, style-checker.yaml):

version: "3"
name: security-checker
description: Security analysis specialist
type: llm
provider: openai
model: gpt-4
system_prompt: Analyze code for security issues
context:
  view: reviewer

Changes:

• routing.type: bridge → type: graph with subgraph nodes
• Subroutes → Separate actor files referenced via actor: local/name
• Triggers → Explicit edges in graph
• Each specialist is now a standalone, reusable actor

---

Field Mapping Reference

Top-Level Fields

v2 Field	v3 Field	Notes
version: "2"	version: "3"	Required change
agents:	N/A	One actor per file
agents[].name	name:	Top-level field
agents[].model	model:	Top-level field
agents[].provider	provider:	Top-level field
agents[].system_prompt	system_prompt:	Top-level field
agents[].temperature	temperature:	Top-level field
agents[].skills	metadata.builtin_tools	New location
routing:	routes: (for graph actors)	New structure
N/A	type:	New required field
N/A	description:	New required field

Routing → Routes

v2 Routing	v3 Routes	Notes
routing.type: direct	type: llm	No routes needed
routing.type: sequential	type: graph + linear edges	Sequential edges
routing.type: conditional	type: graph + conditional edges	Condition on edges
routing.type: bridge	type: graph + subgraph nodes	Hierarchical composition
routing.routes[].from	edges[].source	Edge source node
routing.routes[].to	edges[].target	Edge target node
routing.routes[].condition	edges[].condition	Condition expression

Skills → Tools

v2 Skills	v3 Tools	Notes
agents[].skills: [name]	metadata.builtin_tools: [name]	Built-in tools
Custom skill registration	tools: section	Inline tool definitions
N/A	tools[].code	New: inline Python code

---

Migration Strategy

Phase 1: Inventory (Week 1)

1. List all v2 configurations

   find . -name "*.yaml" -exec grep -l "version: \"2\"" {} \;
   

2. Categorize by complexity:

   • Simple agents (direct routing)
   • Multi-agent workflows (sequential/conditional)
   • Complex bridged workflows

3. Identify dependencies:

   • Shared skills
   • Route bridges
   • Custom configurations

Phase 2: Migrate Simple Actors (Week 2)

Start with simple agents (no routing complexity):

1. Copy v2 config to v3 format
2. Update version: "2" → "3"
3. Add required fields: type, description
4. Remove routing section (for simple LLM actors)
5. Migrate skills to metadata.builtin_tools
6. Add context configuration (optional but recommended)
7. Test actor compilation

Validation:

from cleveragents.actor.schema import ActorConfigSchema

config = ActorConfigSchema.from_yaml("new_actor.yaml")
print(f"✓ Actor {config.name} validated successfully")

Phase 3: Migrate Workflows (Week 3-4)

For multi-agent workflows:

1. Identify workflow pattern:

   • Sequential: A → B → C
   • Conditional: A → (B or C) → D
   • Loop: A → B → A (with termination)
   • Hierarchical: A → [B1, B2, B3] → A

2. Create graph actor:

   • Set type: graph
   • Define nodes (one per v2 agent)
   • Map routing to edges

3. Handle conditionals:

   • Extract condition logic
   • Add conditional nodes or edge conditions
   • Test routing logic

4. Test workflow execution:

   from cleveragents.actor.compiler import ActorCompiler
   
   compiler = ActorCompiler(registry, llm_factory)
   compiled = compiler.compile(config)
   result = await compiled.invoke({"input": "test"})
   

Phase 4: Optimize (Week 5)

Once migrated, optimize v3 actors:

1. Add context views:

   context:
     view: strategist  # or executor, reviewer
   

2. Configure memory appropriately:

   memory:
     enabled: true
     max_turns: 20  # Adjust based on use case
   

3. Extract reusable components:

   • Common specialists → separate actor files
   • Use subgraph nodes for composition

4. Add inline tools for simple operations:

   tools:
     - name: custom_operation
       code: |
         result = # custom logic
   

Phase 5: Decommission v2 (Week 6+)

1. Verify all v3 actors working
2. Update references in code
3. Archive v2 configurations
4. Update documentation

---

Common Migration Challenges

Challenge 1: Complex Routing Logic

Problem: v2 had complex reactive stream operators.

Solution:

• Break into explicit nodes and edges
• Use conditional nodes for routing decisions
• Consider splitting into multiple actors

Before (v2):

routing:
  type: complex
  operators:
    - merge
    - filter
    - switch_map

After (v3):

# Use graph with conditional routing
routes:
  nodes:
    router:
      type: conditional
      condition: # extract logic here

Challenge 2: Shared State

Problem: v2 agents shared observable state.

Solution:

• Use graph state in v3
• Pass information via node outputs
• Use memory for conversation history

Challenge 3: Dynamic Agent Creation

Problem: v2 dynamically created agents at runtime.

Solution:

• Pre-define actor templates
• Use actor registry for dynamic loading
• Consider subgraph nodes with dynamic actor references

Challenge 4: Custom Stream Operators

Problem: v2 used custom RxPY operators.

Solution:

• Reimplement as inline tools
• Use conditional nodes for filtering/mapping
• Consider custom LangGraph nodes (advanced)

---

Validation Checklist

After migration, verify:

• Actor YAML validates against v3 schema
• Actor compiles without errors
• Actor executes and produces expected output
• Tools/skills work correctly
• Memory behaves as expected
• Context configuration appropriate
• Performance acceptable (vs v2)
• Error handling works
• Integration tests pass
• Documentation updated

---

Automated Migration Tool (Future)

A migration tool is planned for v3.1:

# Convert v2 config to v3 (planned)
cleveragents migrate v2-config.yaml --output v3-config.yaml

# Batch migration (planned)
cleveragents migrate-batch configs/v2/*.yaml --output-dir configs/v3/

# Validation only (planned)
cleveragents validate-migration v2-config.yaml

---

Getting Help

• Documentation: Actor Configuration Reference
• Examples: Actor Configuration Examples
• Community: GitHub Discussions
• Support: #cleveragents-v3 Slack channel

---

FAQ

Q: Can I run v2 and v3 actors together?
A: Yes, during migration period. v2 actors automatically bridge to v3 runtime.

Q: Do I need to migrate everything at once?
A: No, migrate incrementally. Start with simple actors.

Q: Will my v2 skills work in v3?
A: Yes, skill interface unchanged. Just update config format.

Q: What if my workflow doesn't map to v3 patterns?
A: Consult migration guide or ask in #cleveragents-v3. Most patterns have direct equivalents.

Q: Performance differences between v2 and v3?
A: v3 is generally faster (LangGraph vs RxPY) and uses less memory.

Q: When is v2 support ending?
A: v2 supported until CleverAgents v3.5 (estimated 6 months after v3.0 release).

---

See Also

• Actor Configuration Reference
• Actor Configuration Examples
• LangGraph Documentation
• v2 to v3 Migration FAQ