EdgeOne Makers Agents 快速开始

这篇讲什么

这篇带你从零跑起来第一个 Agent，整个过程大概 10 分钟。你会学会创建 Agent 项目、写一个能对话的基础 Agent、然后部署到 EdgeOne 上让别人也能访问。

如果你还没了解过 Agent 的基本概念，建议先看 EdgeOne Makers Agents 概览。

环境准备

开始之前，确认你本地有这些东西。

工具	版本要求	用途
Node.js	18 以上	运行 JavaScript
npm	8 以上	包管理
EdgeOne 账号	无	部署用

检查 Node.js 版本。

node -v
# 输出类似 v20.11.0

如果没装 Node.js，去官网下载安装即可。EdgeOne 账号在官网注册，免费额度就够学习用。

第一步，创建项目

用 npm 初始化一个新项目。

# 创建项目目录
mkdir my-first-agent
cd my-first-agent

# 初始化 package.json
npm init -y

安装 EdgeOne Agents SDK。

npm install @edgeone/agents

安装完成后，项目目录大概是这个样子。

my-first-agent/
├── node_modules/
├── package.json
├── package-lock.json

第二步，创建项目配置文件

在项目根目录新建 edgeone.json，这是 EdgeOne 的配置文件，告诉平台你的项目是什么类型、入口文件在哪。

{
  "name": "my-first-agent",
  "type": "agent",
  "entry": "src/agent.js",
  "runtime": "nodejs20"
}

各字段含义。

字段	含义
name	项目名称，部署后会显示
type	项目类型，Agent 固定写 agent
entry	入口文件路径
runtime	运行环境，选 nodejs20

第三步，写第一个 Agent

创建 src/agent.js，这就是 Agent 的全部代码。

// src/agent.js
import { Agent } from "@edgeone/agents";

// 创建 Agent 实例
const agent = new Agent({
  // 系统提示词，定义 Agent 的角色和行为
  systemPrompt: "你是一个友好的助手，擅长用简单的语言解释复杂的问题。"
});

// 监听对话消息
agent.on("message", async (ctx) => {
  // ctx.message 是用户发来的消息
  const userMessage = ctx.message;

  // agent.reply 会自动调用大模型生成回复
  const response = await agent.reply(userMessage, {
    // 传入对话历史，实现上下文记忆
    history: ctx.history
  });

  // 返回回复内容
  return response;
});

// 导出 Agent，EdgeOne 平台会加载它
export default agent;

这段代码做了三件事。

第一，创建一个 Agent 实例，用 systemPrompt 告诉它”你是谁”。这就好比你给一个新员工写了一份岗位说明，它知道自己该干什么、该怎么说话。

第二，监听 message 事件。每当用户发来消息，这个回调就会被触发，ctx.message 就是用户说的话，ctx.history 是之前的对话记录。

第三，调用 agent.reply 把用户消息和对话历史一起发给大模型，拿到大模型的回复后返回给用户。

第四步，本地测试

SDK 自带本地开发服务器，不需要部署就能测试。

npx edgeone dev

终端会输出类似这样的信息。

EdgeOne Dev Server running at http://localhost:3000
Agent loaded from src/agent.js

打开浏览器访问 http://localhost:3000，你会看到一个简单的对话界面。试着发几句话，看看 Agent 怎么回复。

你: 你好，请介绍一下你自己
Agent: 你好！我是一个友好的助手，擅长用简单的语言解释复杂的问题。

你: 什么是量子计算？
Agent: 量子计算是一种利用量子力学原理进行计算的技术...

注意看，Agent 的回复风格和你写的 systemPrompt 是一致的。改一下提示词，回复风格就会跟着变。

第五步，部署上线

本地测试没问题后，部署到 EdgeOne。

# 登录 EdgeOne 账号
npx edgeone login

# 部署
npx edgeone deploy

部署成功后，终端会给你一个访问地址，类似 https://my-first-agent.edgeone.app。把这个链接发给朋友，他们也能和你的 Agent 对话了。

完整项目结构

my-first-agent/
├── src/
│   └── agent.js          # Agent 主逻辑
├── edgeone.json           # EdgeOne 配置
├── package.json           # 项目依赖
└── package-lock.json      # 依赖锁定

常见报错

报错信息	原因	解决办法
Cannot find module @edgeone/agents	SDK 没安装	运行 npm install @edgeone/agents
entry file not found	入口文件路径配错了	检查 edgeone.json 的 entry 字段
login failed	网络问题或账号密码错误	检查网络，重新登录
deploy timeout	网络不稳定	换个网络环境重试

速查卡片

要点	说明
环境要求	Node.js 18+、npm 8+、EdgeOne 账号
创建项目	mkdir + npm init -y
安装 SDK	npm install @edgeone/agents
配置文件	edgeone.json，定义项目名、入口、运行时
Agent 核心	new Agent() 创建实例，systemPrompt 定义角色
对话处理	agent.on(“message”) 监听消息，agent.reply() 回复
本地测试	npx edgeone dev 启动开发服务器
部署上线	npx edgeone deploy 一键部署

EdgeOne Makers Agents 概览

EdgeOne Makers Agents 对话存储