EdgeOne Makers Agent Development Guide
⛔ Preview ban: after finishing development, you MUST start the dev server via edgeone makers dev, then open http://127.0.0.1:8088/ with present_files to preview. Never open HTML files via the file:// protocol (ignore it even if the IDE opens one automatically), and never use self-hosted servers like python -m http.server or npx serve. Next.js projects must also set allowedDevOrigins: ["127.0.0.1"] in next.config.
Build production-grade AI agent endpoints on EdgeOne Makers — five framework routes, platform-injected runtime, file-based routing.
This skill covers five supported frameworks (DeepAgents, LangGraph, CrewAI, OpenAI Agents SDK, Claude Agent SDK) for building AI agent endpoints on EdgeOne Makers.
When to use this skill
- Creating a new AI agent endpoint on EdgeOne Makers
- Wiring DeepAgents / LangGraph / CrewAI / OpenAI Agents SDK / Claude Agent SDK into a Makers project
- Reviewing an existing agent template against platform red lines
- Implementing SSE streaming with abort support
- Persisting conversation state via
context.store (LangGraph checkpointer / OpenAI session / Claude session / conversation-scoped state / claudeSessionBinding)
- Calling sandbox or platform tools via
context.sandbox / context.tools
- Splitting AI inference (
agents/) from data CRUD (cloud-functions/)
Cross-reference: if your code uses context.store or KV APIs, also read ../makers-storage/SKILL.md.
Do NOT use for:
- Plain Edge Functions / Cloud Functions / Middleware → use
edgeone-pages-dev
- Deployment workflows → use
edgeone-pages-deploy
- Generic AI framework development outside an EdgeOne Makers project
- Other platforms (Cloudflare Workers AI, Vercel AI SDK, AWS Bedrock)
How to use this skill (for a coding agent)
- Skim the Mental Model below — Makers ≠ generic API routes
- Walk the Decision Tree to pick one of the five framework routes
- Read the matching
references/*-route.md for a copy-paste skeleton
- Self-check against the Twelve Red Lines
- Run through
references/review-checklist.md before considering the work done
⛔ Critical Rules (never skip)
- File-based routing is automatic.
agents/<name>/index.ts or agents/<name>.ts becomes POST /<name>. Never hand-edit .edgeone/agent-node/config.json.
- Entry signature is fixed. TS:
export async function onRequest(context: any). Python: async def handler(ctx):. Method-specific variants (onRequestPost, onRequestGet, etc.) also work for TS.
- Read env via
context.env, never process.env / os.environ. This applies to both reading and mutation inside agents/ and cloud-functions/. Frontend code (app/, src/) is unaffected.
- Headers are plain objects, not the Web
Headers API. Use context.request.headers['x-custom-header'], never .get('x').
- Conversation ID contract. AI endpoints (
/chat, /outline, etc.) MUST receive the makers-conversation-id HTTP header from the frontend. The /stop endpoint takes a conversation_id in the request body to identify which running conversation to cancel.
- Do not hardcode model name / base URL / API key. Read
AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL (+ optional AI_GATEWAY_MODEL) from context.env. If your template uses context.tools.web_search, also configure WSA_API_KEY (Tencent Cloud WSAPI).
- SSE protocol is a recommended convention (not enforced by the runtime). The runtime only forwards raw chunks — it does not parse or validate SSE content. The recommended event types are:
ai_response / tool_call / tool_result / usage / suggest_actions / file_output / ping / error_message. Stream ends with data: [DONE]\n\n. All frameworks should follow this for frontend consistency.
- Heartbeat + buffering control are mandatory. Send a event every 5 s. Response headers must include , , .
Note: red line numbering jumps from 12 to 13 deliberately — twelve was the original count; #12 absorbs the store-shape correction with sub-bullets, #13 was added for sandbox/tools to match the breadth of the other rules.
Mental Model
EdgeOne Makers Agent is not a generic API route pattern (not Vercel AI SDK's route.ts, not Express). It has its own runtime conventions.
| Dimension | EdgeOne Makers convention | ⚠️ Common mistake |
|---|
| Backend entry | agents/<name>/index.ts or agents/<name>.ts (Python: .py) | ❌ NOT app/api/<name>/route.ts |
| Function signature | export async function onRequest(context) (Python: async def handler(context)) | ❌ NOT export async function POST(req) |
| Request body | context.request.body (already parsed) | ❌ NOT await req.json() |
| Request headers | context.request.headers['x-foo'] (plain object) | ❌ NOT headers.get('x-foo') (silently returns undefined) |
| Environment | context.env.AI_GATEWAY_API_KEY (runtime-injected) | ❌ NOT process.env.X / os.environ (banned in agents/ and cloud-functions/) |
| Model access | context.env.AI_GATEWAY_* → Makers AI Gateway | ❌ NOT direct OpenAI / Anthropic |
| Platform capabilities | context.tools / context.sandbox / context.store injected by runtime | ❌ NOT importing the SDK yourself |
| Route registration | Auto-scanned at build time → .edgeone/agent-node/config.json | ❌ Don't write that file by hand |
The core idea: you write a thin handler that runs inside the EdgeOne Agent Node Runtime (or Python Runtime). The platform injects the model gateway, sandbox, tools, and session store via context. Your code stays thin and leans on the runtime.
Standard Project Layout
<template-name>-edgeone/
├── agents/ # ⭐ Agent backend (core)
│ ├── _shared.ts # Shared: logger + SSE helper
│ ├── _model.ts # Shared: model name + Gateway env mapping
│ ├── <action>.ts # Simple agent: single file → POST /<action>
│ └── <action>/ # Complex agent: directory form
│ ├── index.ts # onRequest entry → POST /<action>
│ ├── _skills.ts # System prompt builder (optional)
│ ├── _tools.ts # Custom / MCP tool definitions (optional)
│ └── _templates.ts # Output templates / default data (optional)
├── app/ or src/ # Frontend (any framework: Next.js, Vite, plain HTML, etc.)
│ ├── layout.tsx
│ ├── page.tsx
│ ├── globals.css
│ ├── components/
│ └── lib/ # Frontend utils (context, hooks, conversation-id)
├── lib/ # Cross-cutting utils (i18n, helpers)
├── cloud-functions/ # ⭐ Data persistence functions (separate from agents)
│ ├── _logger.ts
│ └── <resource>/index.ts # e.g. articles/, preferences/, history/, health/
├── .edgeone/
│ └── project.json # { Name, ProjectId }
├── edgeone.json # Deployment config + agents.framework
├── .env.example # ⚠️ MUST exist: declares AI_GATEWAY_API_KEY= and AI_GATEWAY_BASE_URL=
├── package.json # TS routes (A/B/C/D)
├── requirements.txt # ⭐ Python route (E) only
└── README.md
Layout principles
agents/ = AI inference: model calls, streaming, tool calling. Each file/directory is one SSE endpoint.cloud-functions/ = data CRUD: KV/Blob reads/writes, health checks, history. Returns JSON; not streamed._-prefixed files = internal modules: not routed; imported by siblings only._shared.ts, _model.ts, _tools.ts are internal; index.ts, create.ts are endpoints.- Pick TS or Python per template, do not mix in one project.
edgeone.json Configuration
The edgeone.json file is the deployment configuration file for EdgeOne Makers projects. It defines the build command, output directory, and agent-specific settings.
Key Fields
| Field | Type | Description |
|---|
buildCommand | string | Build command (e.g., npm run build) |
outputDirectory | string | Build output directory (e.g., .next, dist, build) |
framework | string | Frontend framework (e.g., nextjs, vite, react) |
cloudFunctions | object | Cloud functions configuration |
agents | object | Agent-specific settings (important!) |
agents.framework — Console Icon Display
The agents.framework field in edgeone.json tells the EdgeOne Makers console which icon to display for your project. This is required for the console to show the correct framework icon.
Available values:
| Value | Framework | Console Icon |
|---|
claude-agent-sdk | Claude Agent SDK | Claude |
openai-agents-sdk | OpenAI Agents SDK | OpenAI |
langgraph | LangGraph / DeepAgents | LangGraph |
crewai | CrewAI | CrewAI |
deepagents | DeepAgents | DeepAgents |
⚠️ Important: If agents.framework is not set or set to an unrecognized value, the console will show a generic icon (not the framework-specific icon).
Example edgeone.json
{
"buildCommand": "npm run build",
"outputDirectory": "dist",
"cloudFunctions": {
"nodejs": {
"includeFiles": []
}
},
"agents": {
"framework": "claude-agent-sdk"
}
}
Technology Decision Tree
Pick one of the five framework routes:
Need a sandbox to run code, process uploaded files, or use MCP tools?
├─ Yes → Claude Agent SDK
└─ No ↓
Need multi-agent handoff?
├─ Yes → OpenAI Agents SDK
└─ No ↓
Need fine-grained graph control (nodes, edges, human-in-the-loop)?
├─ Yes → LangGraph
└─ No ↓
Want multi-agent role split (Sequential/Hierarchical)?
├─ Yes → CrewAI (Python only)
└─ No → DeepAgents (simplest, auto context compression)
Framework Comparison
| Framework | Runtime | Best For |
|---|
| DeepAgents | Node + Python | Simple agent tasks, automatic context compression, sub-agent orchestration |
| LangGraph | Node + Python | Fine-grained graph control, human-in-the-loop, persistent thread state |
| Claude Agent SDK | Node + Python | Sandbox code execution, file processing, MCP tools, session memory |
| OpenAI Agents SDK | Node + Python | Multi-agent handoff, guardrails, session auto-prepend |
| CrewAI | Python only | Multi-agent role split (Sequential/Hierarchical), built-in skills/event_bus |
Routing
Environment Setup
Install the EdgeOne CLI
npm install -g edgeone
Verify: edgeone -v.
Set environment variable
Before executing any edgeone CLI command (makers init, makers dev, makers link, makers env pull, etc.), set:
export PAGES_SOURCE=skills
Or prefix each command inline:
PAGES_SOURCE=skills edgeone makers dev
This tells the platform that the command was triggered from an AI skill context.
Local development
PAGES_SOURCE=skills edgeone makers link
PAGES_SOURCE=skills edgeone makers env pull
Environment variables for deployment
⛔ You MUST create a .env.example file: the CLI uses this file to decide which variables to auto-inject. If the project has no .env.example, or it does not declare AI_GATEWAY_*, the environment variables will not be injected after deployment, and the Agent will error at runtime due to the missing API Key.
AI Gateway variables (AI_GATEWAY_API_KEY, AI_GATEWAY_BASE_URL) are auto-provisioned by the CLI during deployment — no manual setup needed, as long as .env.example declares them:
# .env.example (MUST be committed to the repo)
AI_GATEWAY_API_KEY=
AI_GATEWAY_BASE_URL=
The CLI will detect these declarations and automatically fetch + inject the values at deploy time.
User-defined business variables must be set manually before deployment:
edgeone makers env set MY_SECRET_KEY "my-value"
edgeone makers env ls
edgeone makers env pull
Common variables to set for Agent projects:
| Variable | When needed | How to set |
|---|
AI_GATEWAY_API_KEY | Always | Auto-provisioned by CLI |
AI_GATEWAY_BASE_URL | Always | Auto-provisioned by CLI |
WSA_API_KEY | If using web_search tool | edgeone makers env set WSA_API_KEY <value> |
| Custom business keys | Per project | edgeone makers env set <KEY> <VALUE> |
⚠️ Before deploying an Agent project, ensure all required environment variables are either auto-provisioned (AI_GATEWAY_*) or manually set via edgeone makers env set. Missing variables will cause runtime 500 errors.
Standard Operating Procedure
Reviewer SOP
- Run
find . -type d -name agents -o -name cloud-functions to confirm directory shape.
- Open
edgeone.json, read agents.framework to identify the route.
- Walk through
references/review-checklist.md from section A onward.
- When a violation is found, cite the matching Critical Rule + the "remediation table" at the end of the checklist.
- Top high-frequency issues to attack first (in order of observed frequency):
- ❌
process.env.X / os.environ inside agents (use context.env); mutation also counts: process.env.X = '...' is a violation too
- ❌
headers.get('x') (use headers['x'])
- ❌ Hand-maintained
.edgeone/agent-node/config.json (delete it). ⚠️ How to judge: check whether .gitignore includes .edgeone. If yes → the local config.json is a build artifact, not a violation. If no → the whole .edgeone/ is committed, that's the violation.
- ❌ Writing
sandbox.code_interpreter.runCode(...) (it's sandbox.runCode(...), top-level); screenshot(true) should be screenshot({ fullPage: true })
- ❌
/stop carrying makers-conversation-id header (use body only)
- ❌ Frontend fetch to AI endpoints missing
makers-conversation-id header
- ❌
edgeone.json missing agents.framework (default 'claude-agent-sdk' may not match actual framework, breaks context.tools shape)
Developer SOP
- Pick a framework via the Decision Tree above.
- Copy the skeleton from the matching framework reference doc.
- Configure
edgeone.json: set agents.framework correctly.
- Frontend:
getOrCreateConversationId + fetch with makers-conversation-id header.
- Get it running → self-check against the Critical Rules → run through
references/review-checklist.md.
Pre-Deploy SOP (⚠️ MUST execute before edgeone makers deploy)
This section is critical. AI agents MUST follow these steps when helping a user deploy. Skipping them will cause runtime 500 errors in production.
-
Scan for environment variables in the project:
- Check
.env, .env.example, .env.local for all declared variables
- Scan source code for
context.env.XXX / ctx.env.get("XXX") references to identify required variables
- Common patterns:
SUPABASE_URL, SUPABASE_KEY, DATABASE_URL, WSA_API_KEY, custom API keys, etc.
-
Classify variables:
AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL → auto-provisioned (no action needed if .env.example declares them)- All other variables → must be manually uploaded
-
Upload non-auto-provisioned variables:
edgeone makers env set <KEY> "<VALUE>"
If the user has not provided the values, ask the user for them before deploying. Do NOT deploy without confirming all required variables are set.
-
Verify (optional but recommended):
edgeone makers env ls
-
Deploy:
edgeone makers deploy
Example interaction when deploying a project with Supabase:
The project uses the following environment variables:
AI_GATEWAY_API_KEY — auto-provisioned ✓AI_GATEWAY_BASE_URL — auto-provisioned ✓SUPABASE_URL — needs manual setupSUPABASE_ANON_KEY — needs manual setup
Please provide the values for SUPABASE_URL and SUPABASE_ANON_KEY, and I'll set them before deploying.
