forked from cleveragents/cleveragents-core
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
This commit is contained in:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user