小程序开放平台

文档中心
Agent 框架
开发
开发 Agent
在小组件中集成 Agent
在小组件内调试本地 Agent
多模态能力接入
知识库能力接入

开发 Agent

应用开发
>
框架
>
开发
>
开发 Agent
>
更新时间:2025-12-03 12:30:08

快速开始

本文将演示如何基于

@vectorx/agent-runtime
@vectorx/functions-framework
创建一个最简单的云端 Agent 服务,并使用
@vectorx/ai-sdk
在前端/Node 环境中完成调用。整体流程面向小红书开放平台智能体的典型部署形态:后端提供统一的智能体 HTTP 接口,前端/业务应用通过 SDK 进行对话。

前置条件

  • 已准备好 Node.js 18+ 开发环境;
  • 已在云托管/云函数或本地环境中可以运行 HTTP 服务(本项目推荐使用
    @vectorx/functions-framework
    );
  • 本项目已安装依赖(通过根目录的包管理命令安装 workspace 依赖)。

1. 创建一个简单的 Agent 类(服务端)

在你的云函数或服务端代码中,新建一个 Agent 实现,例如

MyAgent

typescript
const { AgentRuntime, AgentDriver } = require("@vectorx/agent-runtime");

/**
 * @typedef {import('@vectorx/agent-runtime').IAgent} IAgent
 *
 * @class
 * @implements {IAgent}
 */
class MyAgent extends AgentRuntime {
  async sendMessage(message) {
    try {
      // 创建 qwen-doc-turbo 模型
      const model = this.createModel("qwen-doc-turbo");

      // 组装消息数组
      const messages = [];

      // 1. 处理文件:根据 fileSource 区分处理
      if (Array.isArray(message?.files) && message.files.length > 0) {
        message.files.forEach((file) => {
          if (file.fileSource === "openai") {
            // OpenAI 上传的文件:使用 file-id,通过 system role 传入
            const fileId = file.id;
            if (fileId) {
              messages.push({
                role: "system",
                content: `fileid://${fileId}`,
              });
            }
          } else if (file.fileSource === "standard" || !file.fileSource) {
            // 标准上传的文件:使用 URL,通过 user content 中的 doc_url 传入
            // 注意:标准上传的文件会在 user message 的 content 中处理
          }
        });
      }

      // 2. 添加 user 消息
      const userContent = [];

      // 2.1 添加标准上传的文件(doc_url)
      if (Array.isArray(message?.files) && message.files.length > 0) {
        message.files.forEach((file) => {
          if ((file.fileSource === "standard" || !file.fileSource) && file.url) {
            userContent.push({
              type: "doc_url",
              doc_url: [file.url],
            });
          }
        });
      }

      // 2.2 添加用户文本提示
      const userPrompt = message?.msg || "请分析这个文档";
      if (userPrompt.trim()) {
        userContent.push({
          type: "text",
          text: userPrompt.trim(),
        });
      }

      messages.push({
        role: "user",
        content: userContent,
      });

      // 3. 调用模型
      const modelResponse = await model.streamText({
        messages,
        parameters: {
          temperature: 0.3,
          max_tokens: 2000,
        },
        enable_thinking: true,
      });

      // 4. 流式返回结果
      for await (const chunk of modelResponse) {
        this.sseSender.send({ data: chunk });
      }
      this.sseSender.end();
    } catch (error) {
      console.error("qwen-doc-turbo stream error:", error);
      this.sseSender.end();
    }
  }
}

exports.main = function (event, context) {
  return AgentDriver.run(event, context, new MyAgent(context));
};

上述示例展示的是基于运行时基类封装多轮对话的常见模式,实际接入小红书开放平台智能体时,可以根据平台对话协议进一步裁剪字段和上下文结构。

2. 本地开发与调试建议

  • 使用
    @vectorx/functions-framework
    自带的启动命令在本地运行 Agent 服务;
  • 配合本仓库的
    vectorx-agent-simulator
    或 Web IDE,可以在浏览器中快速调试 Agent 对话效果;
  • 建议在开发阶段开启更详细的日志输出,便于排查大模型调用和 SSE 推送问题。

更多 Agent 能力(如多轮对话、知识库、工具调用等)的集成示例,会在“开发指南”文档中进一步展开。