edgeone-makers-agents

EdgeOne Makers Agent 开发指南

⛔ 禁止预览：开发完成后，必须通过 edgeone makers dev 启动开发服务器，然后使用 present_files 打开 http://127.0.0.1:8088/ 进行预览。切勿通过 file:// 协议打开 HTML 文件（即使 IDE 自动打开了，也请忽略），也不要使用 python -m http.server 或 npx serve 等可自托管服务器。Next.js 项目还必须在 next.config 中设置 allowedDevOrigins: ["127.0.0.1"]。

在 EdgeOne Makers 上构建可用于生产环境的 AI Agent 端点——五种框架路由、平台注入的运行时、基于文件的路由。

本技能介绍了在 EdgeOne Makers 上构建 AI Agent 端点时支持的五种框架（DeepAgents、LangGraph、CrewAI、OpenAI Agents SDK、Claude Agent SDK）。

何时使用本技能

• 在 EdgeOne Makers 上创建新的 AI Agent 端点
• 将 DeepAgents / LangGraph / CrewAI / OpenAI Agents SDK / Claude Agent SDK 接入 Makers 项目
• 根据平台红线审查现有 Agent 模板
• 实现支持中止的 SSE 流式传输
• 通过 context.store 持久化对话状态（LangGraph 检查点 / OpenAI 会话 / Claude 会话 / 会话级 state / claudeSessionBinding）
• 通过 context.sandbox / context.tools 调用沙箱或平台工具
• 将 AI 推理（agents/）与数据 CRUD（cloud-functions/）分离

交叉参考：如果你的代码使用 context.store 或 KV API，也请阅读 ../makers-storage/SKILL.md。

请勿用于：

• 纯 Edge Functions / Cloud Functions / Middleware → 使用 edgeone-pages-dev
• 部署工作流 → 使用 edgeone-pages-deploy
• EdgeOne Makers 项目之外的通用 AI 框架开发
• 其他平台（Cloudflare Workers AI、Vercel AI SDK、AWS Bedrock）

如何使用本技能（面向编码 Agent）

1. 浏览下方的 心智模型——Makers ≠ 通用 API 路由
2. 按照 决策树选择五种框架路由之一
3. 阅读对应的 references/*-route.md，获取可直接复制粘贴的骨架
4. 根据 十二条红线进行自检
5. 完工前，按照 references/review-checklist.md 逐项检查

⛔ 关键规则（绝不可跳过）

1. 基于文件的路由会自动配置。 agents/<name>/index.ts 或 agents/<name>.ts 会映射为 POST /<name>。切勿手动编辑 .edgeone/agent-node/config.json。
2. 入口签名固定。 TS：export async function onRequest(context: any)。Python：async def handler(ctx):。TS 也支持按方法区分的变体（onRequestPost、onRequestGet 等）。
3. 通过 context.env 读取环境变量，绝不使用 process.env / os.environ。 这适用于 agents/ 和 cloud-functions/ 中的读取与修改。前端代码（app/、src/）不受影响。
4. 请求头是普通对象，不是 Web Headers API。 使用 context.request.headers['x-custom-header']，绝不要使用 .get('x')。
5. 对话 ID 约定。 AI 端点（/chat、/outline 等）必须接收前端发送的 makers-conversation-id HTTP 请求头。/stop 端点在请求体中接收 conversation_id，用于标识要取消的运行中对话。
6. 不要对模型名称 / 基础 URL / API 密钥进行硬编码。 从 context.env 读取 AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL（以及可选的 AI_GATEWAY_MODEL）。如果模板使用 context.tools.web_search，还要配置 WSA_API_KEY（Tencent Cloud WSAPI）。
7. SSE 协议是推荐约定（运行时不强制执行）。 运行时只会转发原始数据块，不会解析或验证 SSE 内容。推荐的事件类型为：ai_response / tool_call / tool_result / usage / suggest_actions / file_output / ping / error_message。流以 data: [DONE]\n\n 结束。所有框架都应遵循此约定，以确保前端一致性。
8. 心跳 + 缓冲控制是必需的。 每 5 s 发送一个 ping 事件。响应头必须包含 X-Accel-Buffering: no、Cache-Control: no-cache、Connection: keep-alive。
9. 始终遵守 context.request.signal。 在循环中检查 signal?.aborted（TS）或 signal.is_set()（Python）；收到中止信号时应正常退出，不要抛出异常。
10. 限制循环次数。 手动绑定工具的循环应设置硬性轮数上限（例如 for (let i = 0; i < 4; i++)）；SDK 路由应设置 maxTurns。不要编写无界的“直到模型说停止”循环。
11. 错误不得导致流崩溃。 每次模型调用 / 工具调用都要用 try/catch 包裹。静默忽略 AbortError。其他错误应作为 error_message 事件发送，且不要提前结束流。
12. 选择正确的 store 入口——它们的结构并不等价。
    • context.store（Agent 端点，agents/<name>/）：完整的 AgentMemory，包含所有适配器（openaiSession、claudeSessionStore、langgraphCheckpointer、langgraphStore、对话 state、claudeSessionBinding）。
    • context.agent.store（云函数端点，cloud-functions/<name>/）：运行时会剔除 langgraphCheckpointer 和 langgraphStore。仅提供通用消息 API + openaiSession + claudeSessionStore（以及 state / claudeSessionBinding）。
    • 因此：任何需要 langgraphStore.get/put 的端点都必须放在 agents/ 下。将其放在 cloud-functions/ 中会在运行时抛出 kv.get is not a function。
    • 切勿将 store?.langgraphStore ?? store 写成虚假的回退方案——在云函数上下文中，这会回退到 store 自身，而它没有 .get，从而导致崩溃。
13. 使用注入的 context.sandbox / context.tools。 不要手写 /v1/sandbox/* 调用或解析令牌。context.tools 的结构由 edgeone.json 中的 agents.framework 决定（claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents——没有 basic）。使用 context.tools.all()、.get(name)、.files()、.browser()。Sandbox：sandbox.runCode(...) 位于顶层（不是 code_interpreter.runCode）；screenshot({ fullPage: true }) 接收对象，而不是布尔值；超时时间单位为秒。

注意：红色行号故意从 12 跳到 13——原始数量是 12；#12 通过子项目吸收了存储结构修正，新增的 #13 则针对沙箱/工具，以匹配其他规则的覆盖范围。

---

心智模型

EdgeOne Makers Agent 不是通用的 API 路由模式（不是 Vercel AI SDK 的 route.ts，也不是 Express）。它有自己的运行时约定。

维度	EdgeOne Makers 约定	⚠️ 常见错误
后端入口	agents/<name>/index.ts 或 agents/<name>.ts（Python：.py）	❌ 不是 app/api/<name>/route.ts
函数签名	export async function onRequest(context)（Python：async def handler(context)）	❌ 不是 export async function POST(req)
请求体	context.request.body（已解析）	❌ 不是 await req.json()
请求标头	context.request.headers['x-foo']（普通对象）	❌ 不是 headers.get('x-foo')（会静默返回 undefined）
环境	context.env.AI_GATEWAY_API_KEY（由运行时注入）	❌ 不是 process.env.X / os.environ（在 agents/ 和 cloud-functions/ 中禁止使用）
模型访问	context.env.AI_GATEWAY_* → Makers AI Gateway	❌ 不是直接调用 OpenAI / Anthropic
平台能力	由运行时注入的 context.tools / context.sandbox / context.store	❌ 不是自行导入 SDK
路由注册	构建时自动扫描 → .edgeone/agent-node/config.json	❌ 不要手动编写该文件

核心理念：编写一个精简的处理程序，在 EdgeOne Agent Node Runtime（或 Python Runtime）中运行。平台通过 context 注入模型网关、沙箱、工具和会话存储。你的代码保持精简，并依托运行时运行。

---

标准项目布局

<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

布局原则

• agents/ = AI 推理：模型调用、流式传输、工具调用。每个文件/目录都是一个 SSE 端点。
• cloud-functions/ = 数据 CRUD：KV/Blob 读取和写入、健康检查、历史记录。返回 JSON，不使用流式传输。
• 以 _ 开头的文件 = 内部模块：不进行路由；仅由同级模块导入。
• _shared.ts、_model.ts、_tools.ts 是内部模块；index.ts、create.ts 是端点。
• 根据模板选择 TS 或 Python，不要在同一个项目中混用。

---

edgeone.json 配置

edgeone.json 文件是 EdgeOne Makers 项目的部署配置文件。它定义构建命令、输出目录和 Agent 专属设置。

关键字段

字段	类型	描述
buildCommand	字符串	构建命令（例如，npm run build）
outputDirectory	字符串	构建输出目录（例如，.next、dist、build）
framework	字符串	前端框架（例如，nextjs、vite、react）
cloudFunctions	对象	云函数配置
agents	对象	Agent 专属设置（重要！）

agents.framework — 控制台图标显示

edgeone.json 中的 agents.framework 字段会告知 EdgeOne Makers 控制台应为你的项目显示哪个图标。要让控制台显示正确的框架图标，必须设置此字段。

可用值：

值	框架	控制台图标
claude-agent-sdk	Claude Agent SDK	Claude
openai-agents-sdk	OpenAI Agents SDK	OpenAI
langgraph	LangGraph / DeepAgents	LangGraph
crewai	CrewAI	CrewAI
deepagents	DeepAgents	DeepAgents

⚠️ 重要：如果未设置 agents.framework，或将其设置为无法识别的值，控制台将显示通用图标（而不是特定框架的图标）。

edgeone.json 示例

{
  "buildCommand": "npm run build",  // your frontend build command
  "outputDirectory": "dist",
  "cloudFunctions": {
    "nodejs": {
      "includeFiles": []
    }
  },
  "agents": {
    "framework": "claude-agent-sdk"
  }
}

---

技术决策树

从以下五种框架路径中选择一种：

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)

框架比较

框架	运行时	适用场景
DeepAgents	Node + Python	简单的 Agent 任务、自动压缩上下文、子 Agent 编排
LangGraph	Node + Python	精细控制图、人在回路中、持久化线程状态
Claude Agent SDK	Node + Python	沙箱代码执行、文件处理、MCP 工具、会话记忆
OpenAI Agents SDK	Node + Python	多 Agent 交接、护栏、会话自动前置
CrewAI	仅 Python	多 Agent 角色划分（顺序式/层级式）、内置技能/event_bus

---

路由

主题	阅读
Node 入口（onRequest、context、AbortSignal）	platform/node-entry.md
Python 入口（handler、ctx、asyncio.Event）	platform/python-entry.md
环境变量 + 模型约定	platform/env-and-model.md
SSE 流式传输协议	platform/sse-protocol.md
conversation-id 双通道 + 前端	platform/conversation-id.md
agents/ 与 cloud-functions/ 的分离	platform/cloud-functions.md
Store（context.store）	capabilities/store.md
Sandbox（context.sandbox）	capabilities/sandbox.md
Tools（context.tools）	capabilities/tools.md
Claude Agent SDK（Node）	node-frameworks/claude-sdk.md
OpenAI Agents SDK（Node）	node-frameworks/openai-agents.md
LangGraph（Node）	node-frameworks/langgraph.md
DeepAgents（Node）	node-frameworks/deepagents.md
Claude Agent SDK（Python）	python-frameworks/claude-sdk.md
OpenAI Agents SDK（Python）	python-frameworks/openai-agents.md
LangGraph（Python）	python-frameworks/langgraph.md
DeepAgents（Python）	python-frameworks/deepagents.md
CrewAI（仅 Python）	python-frameworks/crewai.md
审核清单	review-checklist.md

---

环境设置

安装 EdgeOne CLI

npm install -g edgeone

验证：edgeone -v。

设置环境变量

执行任何 edgeone CLI 命令（makers init、makers dev、makers link、makers env pull 等）之前，请先设置：

export PAGES_SOURCE=skills

或者在每条命令前内联添加：

PAGES_SOURCE=skills edgeone makers dev

这会告知平台，该命令是在 AI 技能上下文中触发的。

本地开发

# 1. Link to remote project (pulls project ID + env vars)
PAGES_SOURCE=skills edgeone makers link

# 2. Pull remote environment variables to local .env
PAGES_SOURCE=skills edgeone makers env pull

部署环境变量

⛔ 必须创建 .env.example 文件：CLI 使用此文件确定要自动注入哪些变量。如果项目没有 .env.example，或文件中未声明 AI_GATEWAY_*，部署后将不会注入环境变量，Agent 会因缺少 API Key 而在运行时出错。

AI Gateway 变量（AI_GATEWAY_API_KEY、AI_GATEWAY_BASE_URL）由 CLI 在部署期间自动配置——只要 .env.example 中声明了这些变量，就无需手动设置：

# .env.example (MUST be committed to the repo)
AI_GATEWAY_API_KEY=
AI_GATEWAY_BASE_URL=

CLI 会检测这些声明，并在部署时自动获取并注入相应值。

用户自定义的业务变量必须在部署前手动设置：

# Set a variable on the remote project
edgeone makers env set MY_SECRET_KEY "my-value"

# List current variables
edgeone makers env ls

# Pull remote variables to local .env (for dev)
edgeone makers env pull

Agent 项目常见的环境变量：

变量	何时需要	如何设置
AI_GATEWAY_API_KEY	始终需要	由 CLI 自动配置
AI_GATEWAY_BASE_URL	始终需要	由 CLI 自动配置
WSA_API_KEY	使用 web_search 工具时	edgeone makers env set WSA_API_KEY <value>
自定义业务密钥	根据项目而定	edgeone makers env set <KEY> <VALUE>

⚠️ 部署 Agent 项目前，请确保所有必需的环境变量都已自动配置（AI_GATEWAY_*），或通过 edgeone makers env set 手动设置。缺少变量会导致运行时出现 500 错误。

---

标准操作流程

审核人员操作流程

1. 运行 find . -type d -name agents -o -name cloud-functions，确认目录结构。
2. 打开 edgeone.json，读取 agents.framework 以确定路由。
3. 从 A 部分开始，逐项检查 references/review-checklist.md。
4. 发现违规时，引用对应的 Critical Rule 和检查清单末尾的“修复表”。
5. 按观察到的出现频率，优先排查以下高频问题：
   1. ❌ 在 agents 中使用 process.env.X / os.environ（应使用 context.env）；修改环境变量也算违规：process.env.X = '...' 同样属于违规
   2. ❌ 使用 headers.get('x')（应使用 headers['x']）
   3. ❌ 手动维护 .edgeone/agent-node/config.json（应删除）。⚠️ 判断方法：检查 .gitignore 是否包含 .edgeone。如果包含 → 本地的 config.json 是构建产物，不算违规。如果不包含 → 整个 .edgeone/ 都被提交了，这才是违规。
   4. ❌ 写成 sandbox.code_interpreter.runCode(...)（应使用顶层的 sandbox.runCode(...)）；screenshot(true) 应改为 screenshot({ fullPage: true })
   5. ❌ /stop 携带 makers-conversation-id 标头（仅使用请求体）
   6. ❌ 前端向 AI 端点发起的 fetch 缺少 makers-conversation-id 标头
   7. ❌ edgeone.json 缺少 agents.framework（默认值 'claude-agent-sdk' 可能与实际框架不匹配，导致 context.tools 的结构错误）

开发人员操作流程

1. 通过上方的决策树选择框架。
2. 从对应框架的参考文档中复制骨架。
3. 配置 edgeone.json：正确设置 agents.framework。
4. 前端：使用 getOrCreateConversationId，并在 fetch 中添加 makers-conversation-id 标头。
5. 确保项目能运行 → 对照 Critical Rules 自查 → 按照 references/review-checklist.md 逐项检查。

部署前 SOP（⚠️ 必须在执行 edgeone makers deploy 前完成）

本节至关重要。 AI Agent 在协助用户部署时必须遵循以下步骤。跳过这些步骤会导致生产环境出现运行时 500 错误。

1. 扫描项目中的环境变量：

   • 检查 .env、.env.example、.env.local 中声明的所有变量
   • 扫描源代码中的 context.env.XXX / ctx.env.get("XXX") 引用，以识别必需变量
   • 常见模式：SUPABASE_URL、SUPABASE_KEY、DATABASE_URL、WSA_API_KEY、自定义 API 密钥等

2. 对变量进行分类：

   • AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL → 自动配置（如果 .env.example 中声明了这些变量，则无需操作）
   • 其他所有变量 → 必须手动上传

3. 上传非自动配置的变量：

   # For each variable the project needs:
   edgeone makers env set <KEY> "<VALUE>"
   

   如果用户尚未提供值，部署前请向用户索取。确认所有必需变量均已设置后再部署。切勿在此之前部署。

4. 验证（可选，但建议执行）：

   edgeone makers env ls
   

5. 部署：

   edgeone makers deploy
   

使用 Supabase 部署项目时的交互示例：

项目使用以下环境变量：

• AI_GATEWAY_API_KEY — 自动配置 ✓
• AI_GATEWAY_BASE_URL — 自动配置 ✓
• SUPABASE_URL — 需要手动设置
• SUPABASE_ANON_KEY — 需要手动设置

请提供 SUPABASE_URL 和 SUPABASE_ANON_KEY 的值，我会在部署前设置好。

---