快速开始
本指南帮助你快速部署第一个 Agent，并掌握本地调试、生产部署会话请求的完整流程。
从模板开始
进入控制台，选择 Agents 选项卡，进入到选择 Agent 模板页面，你可以从框架基础模板起步，也可以直接选用贴合业务场景的模板。
部署过程将自动开始，我们会在您的 GitHub 账户上基于该模板创建一个仓库。您可以将此仓库克隆到本地进行进一步开发，并根据需要推送更改。
从 CLI 创建项目开始
1. 安装
通过 npm 来安装 CLI：
npm install -g edgeone
通过
edgeone - v 命令，可以查看是否安装成功。通过 edgeone -h 命令，可以查看相关的所有命令。2. 创建项目
您可以基于以下命令快速创建一个基于 OpenAI Agents SDK 的基础模板。
edgeone makers create --template openai-agents-starter-node
如果已经存在同名项目，可以手动指定项目名称，edgeone makers create [项目名称] --template openai-agents-starter-node
3. 本地调试
执行命令默认会在本地 8088 端口起一个服务，Makers Agent 的服务和前端项目的服务都运行在同一个端口上，无需额外代理。
edgeone makers dev
您可通过
http://localhost:8088/ 访问 Agent 页面。通过
http://localhost:8088/agent-metrics访问 本地可观测链路追踪页面。
改造已有 Agent 项目
如果你已经有自己的 Agent 项目，想迁移到我们平台，只需 3 步即可部署。
1. 调整目录结构
我们 Makers Agents 使用独立目录，遵循文件即路由约定，目录名默认为 agents/，可通过项目配置自定义。把每个 Agent 的入口文件放到
agents/<name>/index.{js,ts,py}：your-project/├── agents/│ ├── researcher/│ │ ├── index.py # 主入口：handler(context)│ │ └── stop.py # 可选：中断处理│ └── customer-service/│ └── index.js└── edgeone.json
_ 前缀的文件或目录为私有模块，不生成路由.
2. 改造入口与配置
业务代码只需把入口改成 handler(context)——平台通过 context 一个对象注入全部能力，无需引入任何平台 SDK；再在 edgeone.json 里声明框架等运行参数即可（详细配置参考下文）。
TS 示例
export async function onRequest(context: any) {// 你的 Agent 业务逻辑}
Python 示例
# Agent 入口async def handler(context):# 你的 Agent 业务逻辑
3. 按需接入 Store / Sandbox
本地调试
1. 关联项目
将控制台已设置的环境变量同步到本地调试，可以执行关联项目命令，按要求输入项目名称，这里的项目名为准备工作中已创建的 Makers 项目名。
edgeone makers link
2. 本地开发
进入项目根目录运行：
edgeone makers dev
CLI 会同时启动：
1. 本地 HTTP server（默认
http://localhost:8080）2. 本地可观测面板（默认
http://localhost:8080/agent-metrics）部署到生产
Git 部署（推荐）
1. 将您的代码推送到远程仓库（GitHub、Gitee、Coding 仓库）。
2. 将项目导入 到 EdgeOne Makers。
3. EdgeOne Makers 会自动构建部署并生成一个线上 URL。
CLI 部署
1. 安装 EdgeOne CLI 并初始化。
2. 运行
edgeone makers deploy -n <project name> 来部署。npm install -g edgeoneedgeone loginedgeone makers deploy -n vite-react-demo
部署成功后点击 Console 的链接可以访问具体构建信息和部署后的 URL。
会话管理
平台用
conversation_id 标识一段连续对话，所有请求必须在请求头携带。它同时驱动三件事：会话粘性路由（agents/）、对话存储归属（agents/ + cloud-functions/ ）、沙箱实例归属（一对话一沙箱）。生成方式
由客户端 / 业务后端在新建对话时生成全局唯一 ID（UUID 即可）并维护，继续历史对话时直接取出原
conversation_id 重用。// 业务生成（推荐）：用 UUID 保证全局唯一，避免冲突const conversationId = `conv_${crypto.randomUUID().replace(/-/g, '')}`;
请求头携带
统一用请求头
Makers-Conversation-Id 传递（所有 agents/*调用都要带），建议在前端 fetch 拦截器里全局注入，避免每个调用点重复书写。// 调 Agentawait fetch('/customer-service', {method: 'POST',headers: {'Content-Type': 'application/json','Makers-Conversation-Id': conversationId,}})
请求头格式与错误
Makers-Conversation-Id 需满足：长度 6–36 个字符，仅允许 0-9 a-z A-Z - _ .。请求头缺失或不合法时，Agent 路由会返回 400。edgeone.json 配置
项目根目录的
edgeone.json 控制 Agent 与沙箱的运行参数：{"agents": {"framework": "openai-agents-sdk", // claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents"dir": "agents", // 可选，默认 "agents""timeout": 300, // 可选，单次 run 上限秒数（30 ~ 3600）"sandbox": {"timeout": 300 // 可选，沙箱实例存活时长（300 ~ 3600）}}}
字段 | 作用 |
agents.framework | 决定 context.store / context.tools 的框架适配形态 |
agents.dir | Agent 源码目录，默认 agents/ |
agents.timeout | 单次任务执行的最大执行秒数 |
agents.sandbox.timeout | 沙箱实例的存活时长 |
