edgeone-makers-migration

EdgeOne Makers Migration Guide

Migrate existing AI agent projects to the EdgeOne Makers platform format. Covers structural conversion, API adaptation, and platform capability injection.

---

Migration Decision Tree

What type of project are you migrating?
├── Python project
│   ├── Using CrewAI → See §2 CrewAI
│   ├── Using LangChain/LangGraph/DeepAgents → See §3 LangGraph (Python)
│   ├── Using OpenAI Agents SDK → See §4 OpenAI Agents (Python)
│   └── Using Claude Agent SDK → See §5 Claude SDK (Python)
└── Node/TS project
    ├── Using Express/Next.js API routes → See §6 Express → Makers
    ├── Using LangGraph/DeepAgents → See §3 LangGraph (Node)
    ├── Using OpenAI Agents SDK → See §4 OpenAI Agents (Node)
    └── Using Claude Agent SDK → See §5 Claude SDK (Node)

---

⚠️ Migration Checklist (common to all frameworks)

Before starting framework-specific changes, check these global items:

• Create edgeone.json with correct agents.framework and buildCommand/outputDirectory
• Move backend code from Express routes / Next.js API routes into agents/ directory
• Replace process.env / os.environ with context.env / ctx.env
• Replace req.headers.get('x') with context.request.headers['x'] (Node) or plain dict access (Python)
• Replace await req.json() with context.request.body (already parsed)
• Replace direct model API calls (OpenAI, Anthropic) with AI_GATEWAY_* env vars
• Add SSE streaming for AI endpoints (replace res.json() / return {"data": ...})
• Add makers-conversation-id header to frontend fetch calls
• Wire platform tools through context.tools instead of custom tool implementations
• Wire conversation history through context.store instead of in-memory or custom DB
• If using web_search, set WSA_API_KEY env var and use context.tools.get("web_search")
• Set up edgeone makers dev for local development

---

§1. Standard API Route → Makers Handler

This is the most common migration pattern. Applies to Express/Next.js API routes, plain HTTP handlers, etc.