Edgeone Makers Agents

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 → makers-edge-functions / makers-cloud-functions / makers-middleware
• Deployment workflows → makers-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)

1. Skim the Mental Model below — Makers ≠ generic API routes
2. Walk the Decision Tree to pick one of the five framework routes
3. Read the matching references/*-route.md for a copy-paste skeleton
4. Self-check against the Twelve Red Lines
5. Run through references/review-checklist.md before considering the work done

⛔ Critical Rules (never skip)

1. File-based routing is automatic. agents/<name>/index.ts or agents/<name>.ts becomes POST /<name>. Never hand-edit .edgeone/agent-node/config.json.
2. 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.
3. 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.
4. Headers are plain objects, not the Web Headers API. Use context.request.headers['x-custom-header'], never .get('x').
5. 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.
6. 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).
7. 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.
8. Heartbeat + buffering control are mandatory. Send a ping event every 5 s. Response headers must include X-Accel-Buffering: no, Cache-Control: no-cache, Connection: keep-alive.
9. Always honor context.request.signal. Check signal?.aborted (TS) or signal.is_set() (Python) inside loops; exit gracefully on abort, do not throw.
10. Cap your loops. Manual bind-tools loops use a hard turn limit (e.g. for (let i = 0; i < 4; i++)); SDK routes set maxTurns. No unbounded "until model says stop" loops.
11. Errors must not crash the stream. Wrap every model / tool call in try/catch. Swallow AbortError silently. Emit other errors as error_message events without ending the stream prematurely.
12. Pick the right store entry point — they are NOT shape-equivalent.
    • context.store (agent endpoints, agents/<name>/): full AgentMemory, includes all adapters (openaiSession, claudeSessionStore, langgraphCheckpointer, langgraphStore, conversation state, claudeSessionBinding).
    • context.agent.store (cloud-function endpoints, cloud-functions/<name>/): runtime strips langgraphCheckpointer and langgraphStore. Only generic message API + openaiSession + claudeSessionStore (+ state / claudeSessionBinding) are available.
    • Consequence: any endpoint that needs langgraphStore.get/put MUST live under agents/. Putting it in cloud-functions/ will throw kv.get is not a function at runtime.
    • Never write store?.langgraphStore ?? store as a fake fallback — in cloud-function context this falls back to the store itself, which has no .get, and crashes.
13. Use injected context.sandbox / context.tools. Do not hand-write /v1/sandbox/* calls or parse tokens. context.tools shape is determined by edgeone.json's agents.framework (claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents — there is no basic). Use context.tools.all(), .get(name), .files(), .browser(). Sandbox: sandbox.runCode(...) is top-level (not code_interpreter.runCode); screenshot({ fullPage: true }) takes an object, not a boolean; timeout is in seconds.

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.

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

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:

⚠️ 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",  // your frontend build command
  "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