Genesys Agent Client

Summary

The Genesys Agent Client (@gnsx/genesys.agent.client) is a TypeScript/JavaScript library for integrating AI-powered development agents into web applications and browser-based tools. It provides a WebSocket-based client for real-time communication with Genesys Agent Server instances.

Key Features

• Real-Time Communication: WebSocket-based connection for instant bidirectional communication with agent servers
• Session Management: Automatic session creation, connection, and lifecycle management
• Event-Driven Architecture: Comprehensive event system for handling agent messages, tool calls, and state changes
• Auto-Reconnection: Built-in automatic reconnection with exponential backoff and configurable retry limits
• Full TypeScript Support: Complete type definitions for all APIs, events, and messages
• Browser & Node.js Compatible: Works in both browser and Node.js environments
• Lightweight: Minimal dependencies, optimized for web applications

Installation

Prerequisites

• Node.js: Version 18 or higher (for development)
• Browser: Modern browser with WebSocket support (for runtime)
• Package Manager: npm, yarn, or pnpm

Installation

Install the client library using your preferred package manager:

npm:

npm install @gnsx/genesys.agent.client

pnpm:

pnpm add @gnsx/genesys.agent.client

yarn:

yarn add @gnsx/genesys.agent.client

Usage

Basic Example

import { GenesysAgentClient, ClientEventType, AgentEventType } from '@gnsx/genesys.agent.client';

const client = new GenesysAgentClient({ autoReconnect: true });

// Connect to server
await client.connect({
  serverAddress: 'http://localhost:3000',
  specPath: 'coder.yaml'
});

// Listen for agent responses
client.on(ClientEventType.SERVER_MESSAGE, (message) => {
  if (message.type === 'agentEvent') {
    switch (message.event.type) {
      case AgentEventType.AGENT_MESSAGE:
        console.log('Agent:', message.event.data.message);
        break;
      case AgentEventType.STREAM_CHUNK:
        console.log('Chunk:', message.event.data.chunk);
        break;
      case AgentEventType.TOOL_CALL:
        console.log('Tool:', message.event.data.toolName);
        break;
    }
  }
});

// Send messages
client.sendInput('Write a hello world function');

// Disconnect when done
client.disconnect();

Configuration Options

const client = new GenesysAgentClient({
  autoReconnect: true,              // Enable automatic reconnection (default: true)
  maxReconnectAttempts: 5,          // Max reconnection attempts (default: 5)
  reconnectInterval: 1000,          // Initial interval in ms, uses exponential backoff (default: 1000)
  debug: false                      // Enable debug logging (default: false)
});

await client.connect({
  serverAddress: 'http://localhost:3000',  // Agent server HTTP address
  specPath: 'coder.yaml'                   // Agent specification file path
});

Error Handling

try {
  await client.connect(config);
} catch (error) {
  console.error('Connection failed:', error);
}

client.on(ClientEventType.DISCONNECTED, (reason) => {
  console.log('Disconnected:', reason);
});

Event Types

The client emits events for:

• SERVER_MESSAGE - All messages from the server (agent responses, tool calls, errors, etc.)
• STATE_CHANGE - Connection state changes (connecting, connected, reconnecting, disconnected)
• DISCONNECTED - Connection closed
• CONTROL_MESSAGE - Status messages (e.g., reconnection attempts)