JavaScript SDK

The ZeebeeAI JavaScript client library provides a simple and intuitive way to integrate AI functionality into your JavaScript applications, with support for multiple AI models, agent orchestration, and real-time interactions.

Compatibility: This SDK is designed to work in both browser and Node.js environments, with full support for modern JavaScript features.

Installation

You can install the ZeebeeAI JavaScript SDK using npm or yarn:

npm install zeebee-ai-client
# or
yarn add zeebee-ai-client

Client Initialization

To start using the SDK, you need to initialize the ZeebeeClient with your API key:

import { ZeebeeClient } from 'zeebee-ai-client';

// Initialize the client
const client = new ZeebeeClient({
  apiKey: 'your-api-key' // You can also use process.env.ZEEBEE_API_KEY
});

AI Chat

The ZeebeeAI SDK provides a powerful chat interface for interacting with large language models through the chat() method of the ZeebeeClient class.

Function Signature

chat(params)

Sends a message to the AI and returns a response.

Parameters:

params.message string: The user message to send to the AI.
params.conversationId string, optional: ID for continuing a conversation. If not provided, a new conversation will be created.
params.model string, default="gpt-4o": The language model to use for generating responses.
params.systemPrompt string, optional: A system prompt to guide the AI's behavior.
params.template object, optional: Template configuration with name and variables properties.
params.stream boolean, default=false: Whether to stream the response instead of waiting for the complete response.
params.layout string, optional: Specific layout for the response.
params.maxTokens number, optional: Maximum number of tokens in the response.
params.temperature number, default=0.7: Controls randomness in response generation (0-1).
params.topP number, default=1.0: Controls diversity via nucleus sampling (0-1).
params.frequencyPenalty number, default=0.0: Reduces repetition of token sequences (0-2).
params.presencePenalty number, default=0.0: Reduces repetition of topics (0-2).
params.stopSequences string[], optional: Sequences that will stop response generation.
params.userId string, optional: User identifier for tracking purposes.
params.metadata object, optional: Additional metadata to include with the request.

Returns:

Promise<Object> or ReadableStream: Response object or stream of response chunks if stream=true.

Basic Example

Here's a simple example of how to use the SDK for basic chat functionality:

import { ZeebeeClient } from 'zeebee-ai-client';

// Initialize the client
const client = new ZeebeeClient({
  apiKey: 'your-api-key'
});

// Send a simple message
async function sendMessage() {
  const response = await client.chat({
    message: "Hello, how can you help me today?",
    model: "gpt-4o"
  });
  console.log(response.message);
}

// Create a conversation for multi-turn interactions
async function createConversation() {
  // First message in a new conversation
  const response = await client.chat({
    message: "Tell me about quantum computing",
    model: "gpt-4o"
  });
  console.log(response.message);
  
  // Continue the conversation using the conversation ID
  const followUp = await client.chat({
    message: "How is that related to cryptography?",
    conversationId: response.conversationId,
    model: "gpt-4o"
  });
  console.log(followUp.message);
}

Voice Chat

The ZeebeeAI SDK provides WebSocket-based voice chat functionality for real-time audio streaming interactions. This allows your application to send audio recordings and receive responses both as text and audio.

Function Signature

startVoiceChat(params)

Starts a real-time voice chat session using WebSockets.

Parameters:

params.audioSource MediaStream|Blob|File: Audio source (microphone stream or pre-recorded audio).
params.conversationId string, optional: Optional conversation ID for continuity.
params.model string, default="gpt-4o": LLM model to use.
params.sttModel string, default="whisper": Speech-to-text model to use.
params.ttsModel string, default="openai_tts": Text-to-speech model to use.
params.voiceId string, default="default": Voice ID for speech synthesis.
params.languageCode string, default="en-US": Language code for speech recognition and synthesis.
params.onTranscription function, optional: Callback for transcription updates.
params.onAIResponse function, optional: Callback for AI text responses.
params.onSpeech function, optional: Callback for speech audio.
params.onError function, optional: Callback for errors.
params.onStatus function, optional: Callback for status updates.
params.block boolean, default=true: Whether to block until response is complete.
params.timeout number, default=60: Timeout in seconds for waiting for response.

Returns:

Promise<Object>: Chat session with control methods.

Alternative Method - createVoiceChatSession

createVoiceChatSession(options)

Creates a voice chat session that can be managed manually, giving more control over the session lifecycle.

Parameters:

options.conversationId string, optional: Optional conversation ID for continuing a previous conversation.
options.model string, default="gpt-4o": LLM model to use.
options.sttProvider string, default="openai": Speech-to-text provider.
options.ttsProvider string, default="openai": Text-to-speech provider.
options.languageCode string, default="en-US": Language code for speech recognition and synthesis.
options.voiceId string, optional: Voice ID for speech synthesis.
options.onTranscript function, optional: Callback for transcription updates.
options.onResponse function, optional: Callback for AI text responses.
options.onAudio function, optional: Callback for speech audio data.
options.onError function, optional: Callback for error events.
options.onStatus function, optional: Callback for status updates.

Returns:

Object: Voice chat session with the following methods:

connect(): Connects to the WebSocket server. Returns a Promise that resolves to true if successful.
disconnect(): Disconnects from the WebSocket server. Returns a Promise.
sendAudio(audioData): Sends audio data to the server. Accepts Blob, File, ArrayBuffer, or base64 string. Returns a Promise that resolves to true if successful.
isConnected(): Returns whether the session is currently connected.
getStatus(): Returns the current session status.

Example - Using createVoiceChatSession with Audio File

import { ZeebeeClient } from 'zeebee-ai-client';
import fs from 'fs';  // For Node.js environments

// Initialize the client
const client = new ZeebeeClient({
  apiKey: 'your-api-key'
});

// Example with pre-recorded audio file
async function audioFileVoiceChat() {
  // Define callback handlers
  const callbacks = {
    onTranscript: (text) => {
      console.log(`🎤 You said: ${text}`);
    },
    onResponse: (text, conversationId) => {
      console.log(`🤖 AI response: ${text}`);
      
      // Store conversation ID for continuity if needed
      if (conversationId) {
        console.log(`Conversation ID: ${conversationId}`);
        // Save this ID if you want to continue the conversation later
      }
    },
    onAudio: (audioBlob) => {
      console.log(`🔊 Received audio response (${audioBlob.size} bytes)`);
      
      // In Node.js, you could save the audio to a file
      // In browser, you could play it with new Audio(URL.createObjectURL(audioBlob))
      
      // Example of saving in Node.js (uncomment if needed):
      // const buffer = await audioBlob.arrayBuffer();
      // fs.writeFileSync('ai-response.mp3', Buffer.from(buffer));
    },
    onError: (error) => {
      console.error(`❌ Error: ${error.message}`);
    },
    onStatus: (status) => {
      const statusSymbols = {
        "connecting": "🔄",
        "connected": "🟢",
        "ready": "✅",
        "processing": "⏳",
        "disconnected": "🔴",
        "reconnecting": "🔁"
      };
      const symbol = statusSymbols[status] || "ℹ️";
      console.log(`${symbol} Status: ${status}`);
    }
  };

  // Create a session with our callbacks
  const session = client.createVoiceChatSession({
    model: "gpt-4o",
    onTranscript: callbacks.onTranscript,
    onResponse: callbacks.onResponse,
    onAudio: callbacks.onAudio,
    onError: callbacks.onError,
    onStatus: callbacks.onStatus
  });

  try {
    // Connect to the server
    console.log("Connecting to voice chat server...");
    const connected = await session.connect();
    
    if (!connected) {
      console.error("Failed to connect to voice chat server");
      return;
    }
    
    console.log("Connected! Ready to send audio");
    
    await sleep(1000); // Optional delay for readiness

    // For Node.js: Read audio file from disk
    const audioBuffer = fs.readFileSync('path/to/audio-file.wav');
    const audioBlob = new Blob([audioBuffer]);
    
    // Send the audio file
    const success = await session.sendAudio(audioBlob);
    
    if (success) {
      console.log("Audio sent successfully, waiting for response...");
    } else {
      console.error("Failed to send audio");
      await session.disconnect();
    }
    
    // The session will remain active, listening for responses
    // You can disconnect when you're done:
    // await session.disconnect();
    
    return session;
  } catch (error) {
    console.error("Error in voice chat session:", error);
    await session.disconnect();
  }
}
async function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

Note: This example focuses on the core SDK functionality without browser-specific APIs. In a browser environment, you would typically get audio from an input element or media recorder. In Node.js, you would read from the filesystem. Adapt the example to your specific environment.

Advanced Features

ZeebeeAI SDK offers several advanced features including Agent Orchestration, Autonomous Routing, and Dynamic Layout Engine.

Dynamic Layout Engine

The Dynamic Layout Engine allows applications to intelligently generate appropriate layouts for content based on message complexity, detected intents, and context.

LayoutController Class

client.layouts

Controller for dynamic layout generation operations.

Methods:

generateLayout(message)
Generate a dynamic layout based on message complexity.

Returns Promise<Object>: Layout configuration.

LayoutType

LayoutType

Constants for all supported layout types when requesting or specifying layout preferences.

Constants:

TEXT_HIGHLIGHT: Simple text layout with highlights
CARD_LIST: List layout with cards
STACKED_CARDS: Stack of cards
COMPARISON_VIEW: Split view for comparisons
CODE_DISPLAY: Layout optimized for code display
DATA_VISUALIZATION: Layout for charts and graphs
STORY_BLOCK: Document and story layout
TABLE_LAYOUT: Dashboard with tabular data
CAROUSEL_GALLERY: Media gallery with carousel
HERO_ALERT: Timeline with alerts
SIMPLE: Default simple layout

Example

import { ZeebeeClient, LayoutType } from 'zeebee-ai-client';

const client = new ZeebeeClient({
  apiKey: 'your-api-key'
});

// Generate a dynamic layout
async function generateDynamicLayout(userMessage) {
  try {
    // Generate a layout based on the message
    const layoutResult = await client.layouts.generateLayout(
      userMessage
    );
    
    console.log(`Generated layout template: ${layoutResult.layout.template}`);
    console.log(`Layout type: ${layoutResult.layout.type}`);
    console.log(`Number of components: ${layoutResult.layout.components.length}`);
  } catch (error) {
    console.error("Layout generation error:", error);
  }
}

Agent Orchestration

The Agent Orchestration feature allows you to create, configure, and execute specialized AI agents designed for specific tasks, and connect them into pipelines for multi-step workflows.

AgentController Class

client.agents

Controller for creating and managing specialized AI agents.

Methods:

createAgent(params)
Create a new agent with the specified configuration.

Returns Promise<Object>: Created agent details including its ID.
getAgent(agentId)
Get details about a specific agent.

Returns Promise<Object>: Agent details.
updateAgent(agentId, updateData)
Update an existing agent's configuration.

Returns Promise<Object>: Updated agent details.
deleteAgent(agentId)
Delete an agent.

Returns Promise<Object>: Deletion confirmation.
executeAgent(agentId, inputData)
Execute an agent with the provided input data.

Returns Promise<Object>: Agent execution result.
getAgentTypes()
Get all available agent types.

Returns Promise<Object>: List of available agent types.
getAgents()
Get all agents available to the user.

Returns Promise<Object>: List of available agents.

PipelineController Class

client.pipelines

Controller for creating and managing pipelines of connected agents.

Methods:

createPipeline(params)
Create a new pipeline of connected agents.

Returns Promise<Object>: Created pipeline details including its ID.
getPipeline(pipelineId)
Get details about a specific pipeline.

Returns Promise<Object>: Pipeline details.
getPipelines()
Get all pipelines available to the current user.

Returns Promise<Object>: List of available pipelines.
updatePipeline(pipelineId, updateData)
Update an existing pipeline.

Returns Promise<Object>: Updated pipeline details.
deletePipeline(pipelineId)
Delete a pipeline.

Returns Promise<Object>: Deletion confirmation.
executePipeline(pipelineId, inputData, conversationId)
Execute a pipeline with the provided input data.

Returns Promise<Object>: Pipeline execution result.
getPipelineExecutions(pipelineId)
Get all executions of a pipeline.

Returns Promise<Object>: List of pipeline executions.
getExecution(executionId)
Get detailed information about a specific pipeline execution.

Returns Promise<Object>: Detailed execution information.
executePipelineStreaming(pipelineId, inputData, conversationId)
Execute a pipeline and stream the results in real-time.

Returns ReadableStream: Stream of execution results.

AgentTypes

AgentTypes

Constants for available agent types in the Zeebee AI platform.

Constants:

RETRIEVAL: Agent for retrieving information from knowledge bases
SUMMARIZATION: Agent for summarizing long-form content
REASONING: Agent for performing logical reasoning and analysis
GENERATION: Agent for generating creative content
WEB: Agent for interacting with web resources
STRUCTURE: Agent for processing and transforming structured data

Example

import { ZeebeeClient, AgentTypes } from 'zeebee-ai-client';

const client = new ZeebeeClient({
  apiKey: 'your-api-key'
});

// Create a specialized research agent
async function createAndUseAgents() {
  // Create a research agent
  const agent = await client.agents.createAgent({
    name: "Research Agent",
    agentType: AgentTypes.RETRIEVAL,
    description: "A specialized assistant for research tasks",
    configuration: {
      description: "Retrieves and analyzes research information",
      systemPrompt: "You are a specialized research assistant. Provide detailed, accurate information with sources."
    },
    modelId: "gpt-4o"
  });
  
  console.log(`Created agent with ID: ${agent.agent_id}`);

  // Create a pipeline with multiple agents
  // First, create a summarization agent
  const summarizeAgent = await client.agents.createAgent({
    name: "Summarize Agent",
    agentType: AgentTypes.SUMMARIZATION,
    configuration: {
      systemPrompt: "You are a summarization expert. Create concise, accurate summaries of complex information."
    },
    modelId: "gpt-4o"
  });
  
  // Create a pipeline connecting the agents
  const pipeline = await client.pipelines.createPipeline({
    name: "Research and Summarize",
    description: "Pipeline that researches a topic and summarizes the findings",
    stages: [
      {
        agent_id: agent.agent_id,
        name: "Research Stage",
        input_mapping: {"query": "$.input.research_topic"},
        output_mapping: {"research_results": "$.output.result"}
      },
      {
        agent_id: summarizeAgent.agent_id,
        name: "Summarize Stage",
        input_mapping: {"text": "$.stages.Research Stage.research_results"},
        output_mapping: {"summary": "$.output.result"}
      }
    ]
  });
  
  // Execute the pipeline
  const pipelineResult = await client.pipelines.executePipeline(
    pipeline.pipeline_id,
    { research_topic: "Recent breakthroughs in quantum computing" }
  );
  
  console.log("Pipeline result:", pipelineResult.output);
}

Autonomous Routing

The Autonomous Routing feature intelligently routes user messages to the appropriate agent, pipeline, or language model based on message content analysis.

RoutingController Class

client.routing

Controller for autonomous routing operations.

Methods:

routeMessage(message)
Route a user message to the appropriate agent, pipeline, or model.

Returns Promise<Object>: Routing result.

IntentCategory

IntentCategory

Constants for available intent categories in the Zeebee AI routing system.

Constants:

INFORMATION_RETRIEVAL: Information seeking intents
CONTENT_CREATION: Content generation intents
CONTENT_SUMMARIZATION: Content summarization intents
CODE_GENERATION: Code-related intents for generating code
CODE_EXPLANATION: Code-related intents for explaining code
DATA_ANALYSIS: Analysis intents for data
SENTIMENT_ANALYSIS: Analysis intents for sentiment
TRANSLATION: Specialized intents for translation
PERSONAL_ASSISTANCE: Specialized intents for personal assistance
CUSTOMER_SUPPORT: Specialized intents for customer support
SYSTEM_INSTRUCTION: System intents
GENERAL_QUERY: Fallback intent
UNKNOWN: Unknown intent

Example

import { ZeebeeClient, IntentCategory } from 'zeebee-ai-client';

const client = new ZeebeeClient({
  apiKey: 'your-api-key'
});

// Route a message to the appropriate destination
async function routeUserMessage(userMessage) {
  try {
    // Get routing recommendation
    const routingResult = await client.routing.routeMessage(userMessage);
    
    console.log(`Routing to: ${routingResult.route_to} (${routingResult.route_type})`);
    console.log(`Confidence: ${routingResult.confidence}`);
    console.log(`Intent: ${routingResult.intent.category}`);
    
    // Use the routing result to direct the request
    let result;
    if (routingResult.route_type === 'agent') {
      // Route to an agent
      result = await client.agents.executeAgent(
        routingResult.route_to,
        { input: userMessage }
      );
    } else if (routingResult.route_type === 'pipeline') {
      // Route to a pipeline
      result = await client.pipelines.executePipeline(
        routingResult.route_to,
        { input: userMessage }
      );
    } else {
      // Regular chat with specified model
      result = await client.chat({
        message: userMessage,
        model: routingResult.route_to || 'gpt-4o'
      });
    }
    
    return result;
  } catch (error) {
    console.error("Routing error:", error);
    
    // Fallback to default model
    return await client.chat({
      message: userMessage,
      model: 'gpt-4o'
    });
  }
}

Conclusion

This SDK provides a comprehensive set of tools for integrating ZeebeeAI's capabilities into your JavaScript applications. For detailed examples and advanced use cases, see the

Need help?

If you encounter any issues or have questions about implementation, please refer to our FAQ or contact our support team.

Getting Started

API References

SDK

JavaScript SDK

Installation

Client Initialization

AI Chat

Function Signature

Parameters:

Returns:

Basic Example

Voice Chat

Function Signature

Parameters:

Returns:

Alternative Method - createVoiceChatSession

Parameters:

Returns:

Example - Using createVoiceChatSession with Audio File

Advanced Features

Dynamic Layout Engine

LayoutController Class

Methods:

LayoutType

Constants:

Example

Agent Orchestration

AgentController Class

Methods:

PipelineController Class

Methods:

AgentTypes

Constants:

Example

Autonomous Routing

RoutingController Class

Methods:

IntentCategory

Constants:

Example

Conclusion

Need help?