Engine Migration Guide
Benchmarked against: Anthropic — Migration guide Scope: Switching between engines for dispatch, search, and agent operations
When an engine changes its API, pricing, or capabilities — or when a better alternative emerges — you need to migrate. This guide covers engine migration at every level.
Migration levels
| Level | What changes | Who's affected | Complexity |
|---|---|---|---|
| Dispatch engine | engine= parameter in WO dispatch | Single WO | Low — just change the parameter |
| Default engine | Provider default in config | All new dispatches | Medium — test before switching |
| Embedding model | Vector dimensions, similarity | All UB search | High — requires re-embedding |
| Primary engine | Claude model version | All agents | High — affects all operations |
| Agentic line | Line 1 ↔ Line 2 architecture | Agent infrastructure | Very high — architecture change |
Dispatch engine migration
The simplest migration — change the engine for a specific Work Order:
# Before: using free Groq for research
dispatch_work_order(work_order_id="WO-2026-0305-001", engine="groq")
# After: switching to Gemini for better quality
dispatch_work_order(work_order_id="WO-2026-0305-001", engine="gemini-search")
No data migration needed — engine selection is per-dispatch, not persistent.
When to switch dispatch engines
| From | To | When |
|---|---|---|
groq | gemini | Need better quality or citations |
gemini | groq | Cost reduction for trivial tasks |
groq | claude | Task requires file operations |
claude | groq | Task is text-only, save costs |
groq-search | gemini-search | Need authoritative citations |
Default engine migration
Changing the default engine for call_model() or search_web():
# Check current defaults
list_models()
# Use a different provider
call_model(prompt="Analyze this...", provider="deepseek")
# Or for web search
search_web(query="Latest AI news", engine="gemini")
Testing checklist:
- Run 3–5 representative queries with the new engine
- Compare output quality with the previous engine
- Check for tool calling compatibility (flat vs nested mode)
- Verify response format matches expectations
- Monitor token usage and costs
Embedding model migration
This is a significant migration. Changing the embedding model means all existing vectors become incompatible.
Current setup: Gemini embedding-001 (768 dimensions)
Estimated time: Hours (depends on entry count) Risk: Search quality regression during transition
Migration steps
- Parallel deployment — Run new embedding model alongside existing
- Batch re-embed — Process all entries through new model
- Quality comparison — Run standard test queries against both indexes
- Switch — Point search_brain to new index
- Cleanup — Remove old index after verification period
Claude model version migration
When Anthropic releases new Claude versions:
| Phase | Action |
|---|---|
| Announcement | Check release notes, note breaking changes |
| Testing | Run representative tasks with new model |
| Gradual rollout | Switch Sonnet agents first, then Opus |
| Full migration | Update all agent configurations |
| Verification | Monitor for quality regression |
Key considerations:
- Max Plan quota is shared across all Claude models
- Model ID changes require config updates (e.g.,
claude-opus-4-6→ next version) - Agent behavior may change with model updates — test critical workflows
Agentic line migration
Moving work between Line 1 (Claude Agentic) and Line 2 (LangGraph):
| Aspect | Line 1 (Claude) | Line 2 (LangGraph) |
|---|---|---|
| Engine | Claude Code SDK | LangGraph + any engine |
| Tool access | Full MCP | Custom tool wiring |
| State management | Claude's context window | Checkpoint persistence |
| Cost | $$$ | $ (low-cost engines) |
Migration direction: Line 1 designs blueprints, Line 2 implements. Not a replacement — mutual rescue architecture.
Migration anti-patterns
| Anti-pattern | Why it fails | Better approach |
|---|---|---|
| Migrate everything at once | One failure breaks all operations | Gradual rollout, one agent at a time |
| Skip quality testing | New engine may degrade output | Always compare before switching |
| Hardcode engine choices | Can't adapt to new options | Use config-driven engine selection |
| Migrate during incident | Adds complexity when you need simplicity | Migrate during calm periods |
| Forget to update UB | Team doesn't know about the change | Ingest migration decision to UB |
Related pages
| Page | Relationship |
|---|---|
| Engine Overview | All engines |
| Choosing an Engine | Selection framework |
| Engine Deprecations | Sunset timelines |
| Backup & Recovery | Recovery if migration fails |