SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场makers-agents

makers-agents

智能体与模型

查看项目

更新于 10-16 02:04

技能介绍

用途

本技能是一份在 EdgeOne Makers 上构建 AI 智能体端点的开发指南，目标是帮助开发者搭建生产级智能体端点。它覆盖五种受支持的框架路线：DeepAgents、LangGraph、CrewAI、OpenAI Agents SDK、Claude Agent SDK，并说明平台注入的运行时、基于文件的路由等约定。

适用场景包括：在 EdgeOne Makers 上创建新的 AI 智能体端点；将 DeepAgents / LangGraph / CrewAI / OpenAI Agents SDK / Claude Agent SDK 接入 Makers 项目；对照平台红线审查现有智能体模板；实现带中止支持的 SSE 流式输出；通过 context.store 持久化会话状态（LangGraph checkpointer / OpenAI session / Claude session）；通过 context.sandbox / context.tools 调用沙箱或平台工具；将 AI 推理（agents/）与数据 CRUD（cloud-functions/）分离。

不适用场景：普通 Edge Functions / Cloud Functions / 中间件（应使用 makers-cloud-functions / makers-edge-functions / makers-middleware）；部署工作流（应使用 makers-deploy）；EdgeOne Makers 项目之外的通用 AI 框架开发；其他平台（Cloudflare Workers AI、Vercel AI SDK、AWS Bedrock）。

主要能力

  • 五种框架路线：DeepAgents（Node + Python，适合简单智能体任务、自动上下文压缩、子智能体编排）、LangGraph（Node + Python，适合细粒度图控制、人在回路、持久化线程状态）、Claude Agent SDK（Node + Python，适合沙箱代码执行、文件处理、MCP 工具、会话记忆）、OpenAI Agents SDK（Node + Python，适合多智能体交接、护栏、会话自动前置）、CrewAI（仅 Python，适合多智能体角色分工，Sequential/Hierarchical，内置 skills/event_bus）。
  • 基于文件的路由：agents/<name>/index.ts 或 agents/<name>.ts 自动成为 POST /<name>，构建时自动扫描生成 .edgeone/agent-node/config.json，无需手写。
  • 平台注入运行时：通过 context 注入模型网关、沙箱、工具与会话存储。
  • SSE 流式协议：推荐事件类型 ai_response / tool_call / tool_result / usage / suggest_actions / file_output / ping / error_message，以 data: [DONE]\n\n 结束。
  • 会话状态持久化：context.store 提供完整 AgentMemory（含 openaiSession、claudeSessionStore、langgraphCheckpointer、langgraphStore）；context.agent.store 仅提供通用消息 API + openaiSession + claudeSessionStore。
  • 沙箱与工具：使用注入的 context.sandbox / context.tools，无需手写 /v1/sandbox/* 调用或解析令牌。

使用方式

面向编码智能体的使用步骤：先浏览 Mental Model（Makers 不等于通用 API 路由）；再走决策树选择五种框架路线之一；阅读对应的 references/*-route.md 获取可复制骨架；对照十二条红线自检；完成前走一遍 references/review-checklist.md。

环境准备：安装 EdgeOne CLI（npm install -g edgeone，用 edgeone -v 验证）；执行任何 edgeone CLI 命令前设置 export PAGES_SOURCE=skills，或内联前缀 PAGES_SOURCE=skills edgeone makers dev。本地开发流程：edgeone makers link（关联远程项目，拉取项目 ID 与环境变量）、edgeone makers env pull（拉取远程环境变量到本地 .env）、edgeone makers dev（启动本地开发服务器，同时运行智能体运行时与前端）。

环境变量：AI_GATEWAY_API_KEY、AI_GATEWAY_BASE_URL 由 CLI 在部署时自动提供，只需在 .env.example 中声明；使用 web_search 工具时需设置 WSA_API_KEY；自定义业务变量用 edgeone makers env set <KEY> <VALUE> 设置。

关键规则（红线）

  • 文件路由自动生效，不要手改 .edgeone/agent-node/config.json。
  • 入口签名固定：TS 为 export async function onRequest(context: any)，Python 为 async def handler(ctx):。
  • 通过 context.env 读取环境变量，禁止 process.env / os.environ（agents/ 与 cloud-functions/ 内均适用）。
  • Headers 是普通对象，用 context.request.headers['x-custom-header']，不要用 .get('x')。
  • 会话 ID 契约：AI 端点必须从前端接收 makers-conversation-id 请求头；/stop 端点从请求体接收 conversation_id。
  • 不要硬编码模型名 / base URL / API key，从 context.env 读取 AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL（可选 AI_GATEWAY_MODEL）。
  • SSE 协议是推荐约定（运行时只转发原始分块，不解析校验）。
  • 心跳与缓冲控制为强制项：每 5 秒发送 ping 事件；响应头须含 X-Accel-Buffering: no、Cache-Control: no-cache、Connection: keep-alive。
  • 始终响应 context.request.signal，循环内检查 signal?.aborted（TS）或 signal.is_set()（Python），中止时优雅退出。
  • 循环必须有上限，手动绑定工具循环使用硬性轮次限制，SDK 路线设置 maxTurns。
  • 错误不得中断流：每次模型 / 工具调用包裹 try/catch，静默吞掉 AbortError，其他错误以 error_message 事件发出。
  • 选对 store 入口：需要 langgraphStore.get/put 的端点必须放在 agents/ 下，放在 cloud-functions/ 会在运行时抛错。
  • 使用注入的 context.sandbox / context.tools，不要手写沙箱调用或解析令牌。

项目结构与配置

标准布局：agents/ 存放智能体后端（AI 推理、流式、工具调用，每个文件/目录是一个 SSE 端点）；cloud-functions/ 存放数据 CRUD（KV/Blob 读写、健康检查、历史，返回 JSON 非流式）；以 _ 前缀的文件为内部模块，不参与路由；app/ 或 src/ 为前端；lib/ 为跨切面工具。每个模板只选 TS 或 Python，不要混用。

edgeone.json 是部署配置文件，关键字段包括 buildCommand、outputDirectory、framework、cloudFunctions、agents。其中 agents.framework 决定控制台显示的框架图标，可选值：claude-agent-sdk、openai-agents-sdk、langgraph、crewai、deepagents。未设置或值无法识别时，控制台显示通用图标。纯后端项目可将 buildCommand 与 outputDirectory 设为空字符串。

适用场景与限制

适用：在 EdgeOne Makers 上开发、审查、调试 AI 智能体端点，尤其是需要流式输出、会话持久化、沙箱执行或平台工具调用的项目。

限制：仅面向 EdgeOne Makers 平台；不覆盖部署流程、普通函数与中间件；CrewAI 仅支持 Python；SSE 协议为推荐约定而非运行时强制；具体收费、价格、平台效果等资料未提供。