文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>边缘安全加速平台 EO>Makers>Agents>快速开始

快速开始

最近更新时间：2026-06-12 16:43:01

我的收藏

本页目录：

本指南帮助你快速部署第一个 Agent，并掌握本地调试、生产部署会话请求的完整流程。

从模板开始

进入控制台，选择 Agents 选项卡，进入到选择 Agent 模板页面，你可以从框架基础模板起步，也可以直接选用贴合业务场景的模板。



首次通过模板创建项目需选择 Git 平台，如何关联 Git 平台可参考文档 导入 Git 仓库。设置完项目的配置信息后即可单击立即创建。



部署过程将自动开始，我们会在您的 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

能力
接入条件
文档
对话存储
需要让 Agent 拥有记忆能力
沙箱工具
需要执行命令 / 读写文件 / 操作浏览器 / 运行代码时接入

本地调试

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。
在你的项目被导入和部署后，对指定生产分支（默认为“main”）的所有提交都会自动触发新的部署。查看 Git 集成 了解更多。

CLI 部署

1. 安装 EdgeOne CLI 并初始化。
2. 运行 edgeone makers deploy -n <project name> 来部署。
npm install -g edgeone
edgeone login
edgeone 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 拦截器里全局注入，避免每个调用点重复书写。
// 调 Agent
await 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。
Agent 请求还受并发会话数与站点频率限制约束，超限时返回 429，请按响应头 Retry-After 指定的时间退避后重试。完整错误码说明见 错误码。

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
沙箱实例的存活时长

中国站