convo-ai-sdk

This SDK provides a client for interacting with the Convo AI chat service, enabling real-time conversational AI experiences in your applications.

Installation

To install dependencies:

bun install

Usage

Initialization

First, import the ChatClient and initialize it with your ClientOptions. You can provide either an apiKey for production or a testAgentId for development.

import { ChatClient } from './src/index'; // Adjust path as needed

const chatClient = new ChatClient({
  apiKey: 'YOUR_API_KEY', // Or testAgentId: 'YOUR_TEST_AGENT_ID'
  identifier: 'user-123', // Optional: A unique identifier for the user
  dynamicVariables: {
    userName: 'John Doe',
    // ... other dynamic variables
  }
});

Connecting to the Chat Service

Connect to the chat service. If you have an existing sessionToken, you can pass it to connect to resume a conversation.

await chatClient.connect();
// Or to resume a session:
// await chatClient.connect('YOUR_SESSION_TOKEN');

Sending Messages

Send messages to the chat service using the sendMessage method.

await chatClient.sendMessage('Hello, how are you?');

Handling Events

The ChatClient emits various events that you can listen to:

• statusChange: Notifies when the connection status changes (disconnected, connecting, connected, error).
• message: Emitted for every new message (user, assistant, system, tool).
• messageStart: When a new assistant message starts streaming.
• messageData: For streaming chunks of assistant message content.
• messageDone: When an assistant message has finished streaming.
• toolCall: When the assistant requests a tool to be called.
• thought: When the assistant provides a thought process.
• historyLoaded: When conversation history is loaded.
• configLoaded: When chat configuration is loaded.
• reset: When the chat is reset.

chatClient.on('statusChange', (status) => {
  console.log('Connection status:', status);
});

chatClient.on('message', (message) => {
  console.log('New message:', message);
});

chatClient.on('messageData', (chunk) => {
  process.stdout.write(chunk); // For streaming output
});

chatClient.on('toolCall', (toolCall) => {
  console.log('Tool call requested:', toolCall);
  // Implement logic to execute the tool and send the result
  // chatClient.sendToolResult(toolCall.id, toolCall.name, 'Tool execution result');
});

Sending Tool Results

If the AI requests a tool call, you can execute the tool and send its result back to the chat service using sendToolResult.

// Example of handling a tool call
chatClient.on('toolCall', async (toolCall) => {
  console.log('Tool call requested:', toolCall);
  // Simulate tool execution
  const toolResult = `Executed tool ${toolCall.name} with args ${JSON.stringify(toolCall.args)}`;
  await chatClient.sendToolResult(toolCall.id, toolCall.name, toolResult);
});

Disconnecting and Resetting

chatClient.disconnect();
chatClient.resetChat(); // Disconnects, clears messages, and reconnects

Building the SDK

To build the TypeScript source files into JavaScript:

bun run build

This project was created using bun init in bun v1.2.16. Bun is a fast all-in-one JavaScript runtime.