Progressive Migration
Waxell is designed for incremental adoption. You do not need to rewrite your agents to get value. Each phase below builds on the previous one, and every phase delivers standalone value -- you can stop at any phase and still have a better system than where you started.
The Migration Staircase
Phase 4: Full Native Waxell
Durable workflows, domains, native governance, generation layer
──────────────────────────────────────────────────────────
Phase 3: Agent Builder
AI-assisted conversion of existing agents (coming soon)
──────────────────────────────────────────────────────────
Phase 2: Signals
Webhook-triggered execution, centralized orchestration
──────────────────────────────────────────────────────────
Phase 1: Observe
Observability, cost tracking, policy enforcement
──────────────────────────────────────────────────────────
Your Existing Agents
LangChain, CrewAI, custom Python, anything else
Each level adds capabilities without removing what you already have. Your existing agents keep running throughout the process.
Phase 1: Add Observability
What it is: Install waxell-observe and wrap your existing agents with a decorator, context manager, or LangChain callback handler. No agent code changes required.
What you gain:
- Execution run tracking with inputs, outputs, and status
- LLM call visibility with token counts and cost estimates
- Pre-execution policy enforcement (budget limits, rate limiting)
- A dashboard to see what your agents are doing
Effort level: Minutes. Install the package, add a few lines of configuration, wrap your agent entry points.
Read more: Phase 1: Add Observability
Phase 2: Add Signals
Signals require the Waxell Framework, which launches March 2nd. Start with Phase 1 (Observe) today.
What it is: Move from ad-hoc agent triggering to signal-driven execution. Register webhook endpoints with Waxell and trigger agent runs via HTTP POST.
What you gain:
- Centralized orchestration of all your agents from one place
- Built-in retry logic and error handling for triggers
- Audit trail of what triggered each agent run and when
- Scheduling and deduplication via idempotency keys
Effort level: Hours. Register signal endpoints, update your trigger code to POST to Waxell instead of calling agents directly.
Read more: Phase 2: Add Signals
Phase 3: Agent Builder
What it is: An AI-assisted tool that analyzes your existing agent code and generates native Waxell equivalents. It maps your patterns to Waxell SDK constructs and lets you review the output before committing.
What you gain:
- Automated translation of existing agent logic to
@agent,@workflow,@tooldecorators - Pattern recognition (your LLM calls become
@decision, your orchestration becomes@workflow) - Review-and-customize workflow so you stay in control
Effort level: Minimal. Run the tool, review the output, customize as needed.
Agent Builder is currently in development. Sign up for early access to be notified when it is available.
Read more: Phase 3: Agent Builder
Phase 4: Go Fully Native
The native SDK and Runtime launch March 2nd. Start with Phase 1 (Observe) today.
What it is: Build your agents using the Waxell SDK from the ground up. Define agents, workflows, tools, and decisions declaratively. Run on Waxell's durable runtime with full infrastructure support.
What you gain:
- Declarative agent definitions with
@agent,@workflow,@tool,@router - Durable workflows with checkpoint/resume via
WorkflowEnvelope - Full governance lifecycle with
DynamicPolicyManager - Production infrastructure: Redis backends, Celery task execution, Django ORM
- Generation layer for RAG, prompt versioning, and content synthesis
- Multi-tenancy with per-tenant policies, model configs, and billing
Effort level: Days to weeks depending on agent complexity. This is a full rewrite, but you have full control over the architecture.
Read more: Phase 4: Go Fully Native
Decision Tree: Which Phase Should I Target?
Use this to decide where to start -- and where to stop.
"I just want visibility into what my agents are doing."
Start and stop at Phase 1. Install waxell-observe, add a decorator or context manager to your agent entry points, and you are done. You get a dashboard, cost tracking, and policy enforcement with no agent rewrites.
"I want centralized orchestration of my agents."
Go to Phase 2. After setting up observability in Phase 1, register signal endpoints to trigger your agents via webhooks. This gives you a single control point for all agent execution, with retry logic and audit trails.
"I want durable workflows and full governance."
Target Phase 4. If your use case demands checkpoint/resume, approval workflows, or infrastructure-grade durability, the native Waxell SDK is the right choice. Consider using Agent Builder (Phase 3) to accelerate the migration.
"I am not sure yet."
Start with Phase 1. It takes minutes, delivers immediate value, and gives you the data to make an informed decision about further migration. Once you can see what your agents are doing -- how much they cost, how often they fail, where they spend time -- the right next step usually becomes obvious.
Comparison of Phases
| Phase 1: Observe | Phase 2: Signals | Phase 3: Builder | Phase 4: Native | |
|---|---|---|---|---|
| Agent code changes | None to minimal | Trigger code only | AI-assisted | Full rewrite |
| Time to value | Minutes | Hours | Minutes | Days to weeks |
| Observability | Yes | Yes | Yes | Yes |
| Cost tracking | Yes | Yes | Yes | Yes |
| Policy enforcement | Basic | Basic | Full | Full |
| Centralized triggering | No | Yes | Yes | Yes |
| Durable workflows | No | No | Yes | Yes |
| Approval workflows | No | No | Yes | Yes |
| Multi-tenancy | API-level | API-level | Native | Native |
Next Steps
- LangChain vs Waxell -- Side-by-side comparison with code examples
- CrewAI vs Waxell -- Side-by-side comparison with code examples
- Feature Comparison Matrix -- Comprehensive feature table
- Phase 1: Add Observability -- Get started in 5 minutes