部署第一个 AI Agent：EdgeOne Makers 从 CLI 创建到生产上线完整教程

摘要： 本文给出在 EdgeOne Makers 上部署 AI Agent 的完整流程：安装 CLI、创建项目、目录与入口约定、本地调试与可观测面板、edgeone.json 配置、Git 与 CLI 两种部署方式、会话请求头规则，以及替换默认模型的两种做法。

部署一个 Agent 到生产，实际要落地的只有五件事：CLI 创建项目、把入口改成 handler(context)、在 edgeone.json 里声明框架、推送生产分支或执行 deploy、调用时带上 Makers-Conversation-Id 请求头。EdgeOne Makers 把运行时、会话存储、沙箱、模型网关、链路追踪都做成了平台内置能力，业务代码不需要引入任何平台 SDK。下面按顺序走完一遍。

一、开始前需要准备什么

三样东西：

一个腾讯云账号，并在控制台开通 EdgeOne Makers 服务。

本地 Node.js 环境，用于安装命令行工具。即使 Agent 本身用 Python 写，CLI 也通过 npm 安装。

一个 Git 平台账号，支持 GitHub、Gitee、Coding、GitLab、Bitbucket。如果打算用 Git 自动部署，这一步必需；只用 CLI 部署可以跳过。

二、安装 EdgeOne CLI 并创建 Agent 项目

通过 npm 全局安装：

npm install -g edgeone

验证安装结果与查看全部命令：

edgeone -v
edgeone -h

登录账号：

edgeone login

基于官方模板创建一个 Agent 项目。下面这条命令创建的是 OpenAI Agents SDK 的基础模板：

edgeone makers create --template openai-agents-starter-node

如果当前目录已存在同名项目，手动指定项目名：

edgeone makers create my-agent --template openai-agents-starter-node

除命令行外，控制台的 Agents 选项卡也提供模板创建入口，既有框架基础模板，也有贴合业务场景的模板。通过控制台模板首次创建项目时需要先关联 Git 平台，平台会在你的仓库账户下基于该模板创建一个仓库。

三、Agent 项目的目录结构与入口约定

EdgeOne 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

下划线前缀的文件或目录是私有模块，不生成路由。 需要放工具函数、提示词模板这类不该被直接请求的代码时，用 _utils.ts、_prompts/ 这样的命名。

入口改造只有一件事：导出平台约定的处理函数，通过 context 获取平台注入的能力。

TypeScript 入口示例：

export async function onRequest(context: any) {
  // 你的 Agent 业务逻辑
}

Python 入口示例：

# Agent 入口
async def handler(context):
    # 你的 Agent 业务逻辑
    pass

迁移已有 Agent 项目也是同一套改造路径：调整目录结构、改造入口与配置、按需接入会话存储与沙箱。需要让 Agent 拥有记忆能力时接入会话管理；需要执行命令、读写文件、操作浏览器或运行代码时接入沙箱工具。

四、本地调试：8088 端口与 agent-metrics 可观测面板

先把控制台已配置的环境变量同步到本地。执行关联命令，按提示输入控制台里的项目名：

edgeone makers link

进入项目根目录启动本地开发服务：

edgeone makers dev

CLI 会同时启动两个服务：

本地 HTTP server，默认地址 http://localhost:8088。Agent 服务和前端项目服务运行在同一端口，不需要额外配代理。

本地可观测面板，默认地址 http://localhost:8088/agent-metrics。这个面板提供本地可调试的全链路追踪，用于在本地看清每一轮对话里模型调用和工具调用的实际路径。排查"Agent 为什么没调用工具""为什么多绕了一圈"这类问题时，先看这个面板比加日志更快。

五、edgeone.json 要配哪些字段

项目根目录的 edgeone.json 控制 Agent 与沙箱的运行参数：

{
  "agents": {
    "framework": "openai-agents-sdk",
    "dir": "agents",
    "timeout": 300,
    "sandbox": {
      "timeout": 300
    }
  }
}

字段含义与取值范围：

framework 字段必须填对。它决定平台按哪种框架形态向 context 注入会话存储与工具能力，填错会导致 context 上拿不到预期的接口。

六、部署到生产：Git 部署与 CLI 部署

Git 部署（推荐）

把代码推送到远程仓库（GitHub、Gitee、Coding 等），在控制台把项目导入 EdgeOne Makers，平台会自动构建部署并生成一个线上 URL。项目被导入后，对指定生产分支（默认为 main）的所有提交都会自动触发新的部署。团队协作和持续交付场景用这种方式，不需要任何人手动执行部署命令。

CLI 部署

适合个人项目、临时验证或还没接入 Git 的情况：

npm install -g edgeone
edgeone login
edgeone makers deploy -n vite-react-demo

部署成功后，命令行会输出控制台链接，点进去可以看到本次构建信息和部署后的访问 URL。

七、调用 Agent 时必须带的请求头

平台用 conversation_id 标识一段连续对话。它同时驱动三件事：会话粘性路由、对话归属、沙箱实例归属（一对话一沙箱）。所有对 Agent 的请求都必须在请求头携带这个值。

生成方式：由客户端或业务后端在新建对话时生成全局唯一 ID，UUID 即可，并自行维护。继续历史对话时取出原值重用。

// 业务生成（推荐）：用 UUID 保证全局唯一，避免冲突
const conversationId = crypto.randomUUID();

传递方式：统一用请求头 Makers-Conversation-Id。建议在前端的 fetch 拦截器里全局注入，避免每个调用点重复书写。

// 调 Agent
await fetch('/customer-service', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Makers-Conversation-Id': conversationId,
  }
})

格式约束与错误处理：

免费版的会话最大并发运行数为 40 个，Agents 执行次数为 20 万/月。客户端做重试时务必遵守 Retry-After，不要固定间隔硬重试。

八、把默认模型换成自己的

创建 Agent 项目时默认使用 Makers Models 内置模型，便于免费快速跑通功能。需要更换时有两条路径。

路径一：继续用 Makers Models，换成自费模型

1. 在 Models 的模型与密钥页面托管厂商 API Key。
2. 修改环境变量 AI_GATEWAY_MODEL（默认变量名）的前缀为厂商前缀。例如默认值为 @makers/deepseek-v4-flash，托管的厂商是 deepseek，则改为：

AI_GATEWAY_MODEL=deepseek/deepseek-v4-flash

1. 重新部署项目。

路径二：直连原生厂商或自定义厂商

1. 在项目环境变量设置页把 AI_GATEWAY_BASE_URL 和 AI_GATEWAY_API_KEY 换成厂商提供的地址与密钥。
2. 把 AI_GATEWAY_MODEL 改为该厂商要求的模型名，不带平台前缀：

AI_GATEWAY_MODEL=deepseek-v4-flash

1. 重新部署项目。

两种方式的差别在于请求是否经过平台模型网关。走网关可以享受边缘转发与网络安全防护，直连则完全由你掌控链路。

总结

整条链路可以压缩成一组命令和两个约定。命令是 npm install -g edgeone → edgeone makers create → edgeone makers link → edgeone makers dev → edgeone makers deploy；两个约定是入口放在 agents/<name>/index.* 并导出 handler(context)，调用时带上 Makers-Conversation-Id。配置层面只需在 edgeone.json 里填对 framework，运行时、会话存储、沙箱、模型网关和链路追踪由 EdgeOne Makers 平台提供。

遇到 400 先查请求头格式，遇到 429 按 Retry-After 退避，这两类是接入阶段最高频的问题。

产品完整能力与控制台入口见 EdgeOne Makers 产品页：https://cloud.tencent.com/product/makers

当前首购特惠 EdgeOne Makers 专业版 Pro 套餐 39 元/月，具体以活动页实际展示为准：https://cloud.tencent.com/act/pro/makers-pro