From dbc07ee4050592d594307a3eca60cd2a25b57500 Mon Sep 17 00:00:00 2001 From: Aditya Chhabra Date: Mon, 9 Feb 2026 20:22:58 +0530 Subject: [PATCH] docs: add actor config migration guide - Comprehensive v2 to v3 migration guide - Key differences and architectural changes - Side-by-side migration examples - Field mapping reference - 5-phase migration strategy - Common challenges and solutions - Validation checklist Refs: C1.6c --- .../actor_configuration_migration.md | 595 ++++++++++++++++++ 1 file changed, 595 insertions(+) create mode 100644 docs/reference/actor_configuration_migration.md diff --git a/docs/reference/actor_configuration_migration.md b/docs/reference/actor_configuration_migration.md new file mode 100644 index 00000000..10645302 --- /dev/null +++ b/docs/reference/actor_configuration_migration.md @@ -0,0 +1,595 @@ +# 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:** +```yaml +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:** +```yaml +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:** +```yaml +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:** +```yaml +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:** +```yaml +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:** +```yaml +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:** +```yaml +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):** +```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):** +```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** + ```bash + 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:** +```python +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:** + ```python + 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:** + ```yaml + context: + view: strategist # or executor, reviewer + ``` + +2. **Configure memory appropriately:** + ```yaml + 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: + ```yaml + 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):** +```yaml +routing: + type: complex + operators: + - merge + - filter + - switch_map +``` + +**After (v3):** +```yaml +# 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: + +```bash +# 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](./actor_configuration.md) +- **Examples:** [Actor Configuration Examples](./actor_configuration_examples.md) +- **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.md) +- [Actor Configuration Examples](./actor_configuration_examples.md) +- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) +- [v2 to v3 Migration FAQ](./migration_faq.md) +