Skip to main content

Calling from Web

Web applications can call Agents through the CloudBase JS SDK with streaming output support.

Check which protocol your Agent uses

An Agent's communication protocol is determined by the template it was created from. If its endpoint on the console's "Integration & Debugging" page ends with /acp (the cloudbase-agent template), it uses the ACP protocol; self-hosted HTTP Agents use the AG-UI protocol. The examples below are grouped by protocol.

Prerequisites​

  • CloudBase environment activated
  • Agent created
  • Publishable Key obtained (Get it here)

Installation​

npm install @cloudbase/js-sdk

Calling an ACP Protocol Agent (cloudbase-agent template)​

Pass the parameters in the JSON-RPC format of the ACP protocol, and parse session/update events from dataStream. Do not use textStream with ACP responses — it only understands the legacy response format:

const res = await ai.bot.sendMessage({
  // botId is required, identifies the Agent to call
  botId: 'your-agent-id',
  jsonrpc: '2.0',
  id: 1,
  method: 'session/prompt',
  params: {
    prompt: [{ type: 'text', text: 'Hello' }]
  }
});

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;   // reply text increment
  }
}

// Multi-turn: pass sessionId back in params.sessionId to keep context
const res2 = await ai.bot.sendMessage({
  botId: 'your-agent-id',
  jsonrpc: '2.0',
  id: 2,
  method: 'session/prompt',
  params: {
    sessionId,
    prompt: [{ type: 'text', text: 'What were we just talking about?' }]
  }
});

Calling an AG-UI Protocol Agent (self-hosted HTTP Agent)​

Basic Usage​

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 is required, identifies the Agent to call
  botId: 'your-agent-id',
  // Parameter structure reference front-end and back-end communication protocol:
  // https://docs.cloudbase.net/ai/agent/http-agent-protocol
  threadId: 'your-thread-id',
  runId: 'your-run-id',
  messages: [
    { id: 'msg-1', role: 'user', content: 'Hello' }
  ],
  tools: [],
  context: [],
  state: {},
  forwardedProps: {}
});

// Stream the response
let text = '';

for await (const data of res.dataStream) {
  // Output based on event type, response events reference:
  // 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);  // Real-time output
      break;

    case 'RUN_ERROR':
      console.error('Error:', data.message);
      break;

    case 'RUN_FINISHED':
      // Run finished
      break;
  }
}

console.log('Complete response:', text);

Multi-turn Conversation​

Multi-turn conversations are linked through threadId for the same session, passing historical messages through messages:

import { v4 as uuidv4 } from 'uuid';

// Use the same threadId to link multi-turn conversations
const threadId = uuidv4();
const messages = [];

// First round of conversation
messages.push({ id: uuidv4(), role: 'user', content: 'Hello' });

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;
  }
}

// Record AI reply
messages.push({ id: uuidv4(), role: 'assistant', content: answer1 });

// Second round of conversation
messages.push({ id: uuidv4(), role: 'user', content: 'Continue chatting' });

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