/makers-agents

name: edgeone-makers-agents
description: >-
  This skill guides building AI agent endpoints on EdgeOne Makers — five
  framework routes (DeepAgents, LangGraph, CrewAI, OpenAI Agents SDK,
  Claude Agent SDK), platform-injected `context.store` /
  `context.tools` / `context.sandbox`, conversation_id dual-channel routing,
  SSE streaming, and `agents/` vs `cloud-functions/` separation.
  It should be used when the user wants to create or review an AI agent endpoint
  on EdgeOne Makers — e.g. "build an agent on EdgeOne Makers", "create a Claude
  agent endpoint", "wire LangGraph into Makers", "stream LLM responses with SSE",
  "review my agent template", "use context.store / context.sandbox / context.tools".
  Do NOT trigger for plain Edge Functions, Cloud Functions, or middleware
  (those don't run AI logic — use edgeone-pages-dev instead).
  Do NOT trigger for deployment workflows (use edgeone-pages-deploy).
  Do NOT trigger for generic AI framework development outside
  an EdgeOne Makers project.
pathPatterns:
  - agents/**
validate:
  - pattern: "process\\.env|os\\.environ"
    message: "Read env via context.env inside agents/ and cloud-functions/, never process.env or os.environ (Critical Rule 3)."
  - pattern: "headers\\s*\\.\\s*get\\s*\\("
    message: "Headers are plain objects here: context.request.headers['x-name'], not .get('x-name') (Critical Rule 4)."
  - pattern: "langgraphStore\\s*\\?\\?\\s*store"
    message: "Never write `store?.langgraphStore ?? store` — in cloud-function context it falls back to a store with no .get and crashes (Critical Rule 12)."
metadata:
  author: edgeone
  version: "1.0.0"

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)

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 say