使用 @vectorx/agent-runtime 对接平台 AI 能力
更新时间：2025-08-11 11:27:53
一、 @vectorx/functions-framework 与 @vectorx/agent-runtime 关系
- @vectorx/functions-framework 是一个函数式代码运行框架，提供了标准的 云函数 加载策略，并提供 context 上下文管理、日志、服务发现、SSE 网络请求等 AI 开发的核心能力。其内部包含对开放平台「鉴权」、「用户身份」识别等核心能力，拥有：
- 原生面向 HTTP，支持本地、线上环境运行
- 支持热重启，易于在本地开发与调试
- 提供面向用户的多层次、结构化日志输出
- 提供开放平台鉴权、身份识别等核心能力
- 支持标准的 SSE 长链、http 等能力
- @vectorx/agent-runtime 是一套面向开放平台的 agent 开发范式，提供开放平台的模型库、知识库、数据库、工具集、长/短期记忆等核心能力，是一套开平 Agent 开发能力的 NodeJS 实现。其拥有：
- 模型库、知识库、数据库、工具集调用能力
- 标准化的接口 Agent 对话能力
- 历史消息与会话管理能力
- 对话信息长期记忆能力
- Tools 工具调用能力
关于 @vectorx/functions-framework 与 @vectorx/agent-runtime 的关系，可参考：如何基于开放平台开发 「函数式 Agent 智能体」
二、@vectorx/functions-framework 与 @vectorx/agent-runtime 使用与安装
以下是一个标准的 NodeJS 范式 agent 开发目录与各目录的介绍
json
weather-agent/ ├── src/ ---------------------------------- ## 项目根目录 │ └── index.js ---------------------------------- ## agent 云函数所在目录 ├── dist/ ---------------------------------- ## agent 构建产物所在地址（cli 可通过参数自行指定，参考 rcb build -h） │ └── agent.zip ├── logs/ ---------------------------------- ## 本地服务日志目录 ├── node_modules/ ---------------------------------- ## 项目依赖包 ├── .gitignore ---------------------------------- ## .gitignore ├── agent-cloudbase-functions.json ------------------- ## agent 函数配置目录 ├── package.json ---------------------------------- ## package.json 依赖声明 └── project.config.json ------------------------------- ## 项目配置文件
有关于 agent-cloudbase-functions.json 、project.config.json 项目配置，可参考:
借助云开发提供的AI智能体开发框架 agent-framework ，仅几行代码，即可快速实现一个基于 函数型 Agent 的智能体搭建，以下为一个简单的 函数型 AI 智能体 示例代码，可将下列的函数代码写入的 src/index.js 下：
📢 注：推荐使用 IDE 或者 cli 工具初始化项目模板，在集成化的环境下进行开发，可参考：使用 @vectorx/xhs-cloud-cli 工具开发智能体
ts
const { AgentRuntime, AgentDriver } = require("@vectorx/agent-runtime");
const test_answer = "hi，我是开放平台智能体，我可以帮你做很多事情！";
/**
* @typedef {import('@vectorx/agent-runtime').IAgent} IAgent
*
* @class
* @implements {IAgent}
*/
class MyAgent extends AgentRuntime {
async sendMessage() {
return new Promise((res) => {
const charArr = test_answer.split("");
const interval = setInterval(() => {
const char = charArr.shift();
if (typeof char === "string") {
// 返回标准的结构定义
this.sseSender.send({
data: {
choices: [
{
message: {
role: "assistant",
type: "answer",
content: char
},
},
],
},
});
} else {
clearInterval(interval);
this.sseSender.end();
res();
}
}, 50);
});
}
}
// 基于云函数进行发布
exports.main = function (event, context) {
return AgentDriver.run(event, context, new MyAgent(context));
};
使用 npm/pnpm/yarn 安装依赖：
bash
npm i @vectorx/agent-runtime -S // 或指定 latest npm i @vectorx/functions-framework -S // 或指定 latest
在项目中引入依赖，按照标准开发范式进行 agent 开发：
ts
const { AgentRuntime, AgentDriver } = require("@vectorx/agent-runtime");
// 继承 AgentRuntime 基类，获取 开平 AI 核心能力
class MyAgent extends AgentRuntime {
...
}
// 基于「云函数」的方式注册智能体，agent 服务框架（ @vectorx/functions-framework ）会自动加载函数
exports.main = function (event, context) {
return AgentDriver.run(event, context, new MyAgent(context));
};
在项目根目录 package.json 中，声明相关依赖：
json
{
"version": "1.0.0",
"description": "智能体模板",
"scripts": {
"start": "rcb-ff" // 通过 functions-framework 启动函数式框架
},
"dependencies": {
"@vectorx/agent-runtime": "^0.0.1",
"@vectorx/functions-framework": "^0.0.1"
}
}
运行 npm run start，即可唤起 agent
三、@vectorx/agent-runtime 能力介绍
Agent 方法
IAgent 完整的方法定义及对应的服务如下：
1、sendMessage()
- 函数签名 sendMessage(input: SendMessageInput): Promise
- 服务 URI POST /v1/aiagent/agents/:agentId/send-message
与 Agent 问答对话接口实现，接口内需要通过 this.sseSender 发送 Server-Sent Events 给客户端 SendMessageInput 参数数据结构：
字段 | 描述 | 是否必传 |
|---|---|---|
| msg | 消息 | 是 |
| histroy | 历史消息 | 是(可传 [] ) |
2、createModel()
- 有序列表函数签名 createModel(model: string): models.ReactModel
- 服务 URI 【不支持外部调用】
返回一个提供 AI 生成文本能力的对象。支持的模型和参数：
ReactModel.streamText() 以流式调用大模型生成文本。流式调用时，生成的文本及其他响应数据会通过 SSE 返回，该接口的返回值对 SSE 做了不同程度的封装，开发者能根据实际需求获取到文本流和完整数据流。
使用示例：
ts
sendMessage() {
const model = this.createModel('deepseek-r1')
const modelResponse = await model.streamText({
messages: [
{
role: 'system',
content: systemPrompt
},
{
role: 'user',
content: {
type: 'text',
content: JSON.stringify(input.msg)
}
}
]
})
for await (const chunk of modelResponse) {
this.sseSender.send({ data: chunk });
}
this.sseSender.end();
}
ChatModel.generateText() 调用大模型生成文本(非流式)
使用示例:
ts
sendMessage() {
const model = this.createModel('deepseek-r1')
const modelResponse = await model.generateText({
messages: [
{
role: 'system',
content: systemPrompt
},
{
role: 'user',
content: {
type: 'text',
content: JSON.stringify(input.msg)
}
}
]
})
const resp = {
content: modelResponse.choices[0].message.content || '',
reasoning_content: '',
role: 'assistant',
type: 'text',
}
this.sseSender.send({ data: resp });
this.sseSender.end();
}
类型声明
function generateText(data: unknown): Promise
3、getAgentInfo()
- 函数签名 getAgentInfo(): Promise
- 服务 URI GET /v1/aiagent/agents/:agentId/info
获取当前智能体的信息
4、createRecordPair()
- 函数签名 createRecordPair(params: CreateRecordPairParams): Promise
- 服务 URI 【不支持外部调用】
创建对话记录
CreateRecordPairParams 入参结构
字段名 | 字段描述&类型 |
|---|---|
| conversation_id | 会话 ID string |
| user_input | 消息内容 content: z.string()、** 角色 role: z.string() |
| assistant_output | 内容content: z.string().optional()、角色 role: z.string().optional()、推理内容 reasoning_content: z.string().optional(),、类型type: z.string().optional(), |
5、getHistoryMessages
- 函数签名 getHistoryMessages(params: GetHistoryMessagesParams): Promise
- 服务 URI GET /v1/aiagent/agents/:agentId/messages
创建对话记录 GetHistoryMessagesParams 入参结构
- | 字段描述及类型 |
|---|---|
| conversation_id | 会话 ID string |
| cursor | 消息内容 content: z.string(),请求的游标 cursor: z.string() |
| count | 类型 number |
| sort | 排序 'desc'、'asc' |
云开发框架配置文件 - agent-cloudbase-functions.json
用于在 云函数 框架启动阶段加载，支持定义 "函数式智能体" 加载入口 及 触发路径 以如下目录为例：
json
├── node_modules # 项目依赖 ├── src # 函数 echo │ └── index.js # 默认函数入口文件 ├── package.json ├── cloudbase-functions.json # 多函数配置文件 ├── project.config.json # 项目配置文件
在 cloudbase-functions.json 配置文件中，需要对 默认函数（index.js）函数进行声明和路由，配置文件如下：
json
{
"functionsRoot": "./src",
"functions": [
{
"triggerPath": "/",
"name": "main",
"directory": "./",
"source": "index.js"
}
]
}
字段 | 子字段 | 描述 |
|---|---|---|
| functionsRoot | - | 函数根目录 |
| functions | triggerPath | 函数触发路径 |
| 同上 | name | 函数名称 |
| 同上 | directory | 函数源码目录，相对于函数 functionsRoot 的路径 |
| 同上 | source | 函数源码目录 |
项目配置文件 - project.config.json
字段 | 描述 |
|---|---|
| agentId | 当前智能体 id |
| version | 当前智能体 版本号（需符合 https://semver.org/ 规范 ） |
| 其他字段 | IDE 内消费 |
日志场景分类
模拟器使用
系统日志分组
业务云函数异常日志
该文档是否对您有帮助？