跳到主要内容

在 Web 中调用

Web 应用可以通过云开发 JS SDK 调用 Agent，支持流式输出。

先确认你的 Agent 使用的协议

Agent 的通信协议由创建时的模板决定：控制台「接入 & 调试」页端点以 /acp 结尾的（cloudbase-agent 模板），使用 ACP 协议；自建 HTTP Agent 使用 AG-UI 协议。下文示例按协议分节。

前置条件​

  • 已创建云开发环境
  • 已创建 Agent
  • 已获取 Publishable Key（获取地址）

安装​

npm install @cloudbase/js-sdk

调用 ACP 协议 Agent（cloudbase-agent 模板）​

参数写 ACP 协议 的 JSON-RPC 格式，从 dataStream 解析 session/update 事件（textStream 仅适用于旧版响应格式，ACP 响应请勿使用）：

const res = await ai.bot.sendMessage({
  // botId 必填，标识调用的 Agent
  botId: 'your-agent-id',
  jsonrpc: '2.0',
  id: 1,
  method: 'session/prompt',
  params: {
    prompt: [{ type: 'text', text: '你好' }]
  }
});

let text = '';
let sessionId = '';
for await (const frame of res.dataStream) {
  if (frame?.params?.sessionId) sessionId = frame.params.sessionId;
  const update = frame?.params?.update;
  if (update?.sessionUpdate === 'agent_message_chunk') {
    text += update.content.text;   // 正文增量
  }
}

// 多轮会话：下一轮把 sessionId 传回 params.sessionId 即可延续上下文
const res2 = await ai.bot.sendMessage({
  botId: 'your-agent-id',
  jsonrpc: '2.0',
  id: 2,
  method: 'session/prompt',
  params: {
    sessionId,
    prompt: [{ type: 'text', text: '我们刚才聊到哪了？' }]
  }
});

调用 AG-UI 协议 Agent（自建 HTTP Agent）​

基础调用​

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: 'your-env-id',
  accessKey: '<YOUR_PUBLISHABLE_KEY>',
});

const ai = app.ai();

const res = await ai.bot.sendMessage({
  // botId 必填，标识调用的 Agent
  botId: 'your-agent-id',
  // 入参结构参考前后端通信协议：
  // https://docs.cloudbase.net/ai/agent/http-agent-protocol
  threadId: 'your-thread-id',
  runId: 'your-run-id',
  messages: [
    { id: 'msg-1', role: 'user', content: '你好' }
  ],
  tools: [],
  context: [],
  state: {},
  forwardedProps: {}
});

// 流式接收响应
let text = '';

for await (const data of res.dataStream) {
  // 根据事件类型输出，响应事件参考文档：
  // https://docs.cloudbase.net/ai/agent/http-agent-protocol#%E5%93%8D%E5%BA%94%E4%BA%8B%E4%BB%B6
  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      text += data.delta;
      console.log(data.delta);  // 实时输出
      break;

    case 'RUN_ERROR':
      console.error('运行出错:', data.message);
      break;

    case 'RUN_FINISHED':
      // 运行结束
      break;
  }
}

console.log('完整响应:', text);

多轮对话​

多轮对话通过 threadId 来关联同一会话，通过 messages 传递历史消息：

import { v4 as uuidv4 } from 'uuid';

// 使用同一个 threadId 来关联多轮对话
const threadId = uuidv4();
const messages = [];

// 第一轮对话
messages.push({ id: uuidv4(), role: 'user', content: '你好' });

const res1 = await ai.bot.sendMessage({
  botId: 'your-agent-id',
  threadId: threadId,
  runId: uuidv4(),
  messages: messages,
});

let answer1 = '';
for await (const data of res1.dataStream) {
  if (data.type === 'TEXT_MESSAGE_CONTENT') {
    answer1 += data.delta;
  }
}

// 记录 AI 回复
messages.push({ id: uuidv4(), role: 'assistant', content: answer1 });

// 第二轮对话
messages.push({ id: uuidv4(), role: 'user', content: '继续聊聊' });

const res2 = await ai.bot.sendMessage({
  botId: 'your-agent-id',
  threadId: threadId,
  runId: uuidv4(),
  messages: messages,
});

相关文档​