Raison Client

A realtime client library for communicating with Raison agents via WebSocket.

Installation

npm install raison-client

Usage

import RaisonClient from 'raison-client'

// Initialize the client
const client = new RaisonClient({
  apiUrl: 'https://api.raison.ist',
  apiKey: 'your-api-key'
})

// Get an agent by name
const agent = await client.getAgent({ name: 'my-agent' })

// Get an agent by name with a specific tag
const agentWithTag = await client.getAgent({
  name: 'my-agent',
  tag: 'production'
})

// List all agents
const allAgents = await client.listAgents()

// List agents with a specific tag
const productionAgents = await client.listAgents({ tag: 'production' })

// Render a prompt with variables
const prompt = agent.renderPrompt({
  userName: 'John',
  context: 'some context'
})

API

new RaisonClient(config)

Creates a new client instance and establishes a WebSocket connection.

Parameters:

• config.apiUrl (string): The Raison API URL
• config.apiKey (string): Your API key
• config.onConnectionStateChange (function, optional): Callback fired when connection state changes
• config.onError (function, optional): Callback fired when connection errors occur
• config.connectionOptions (object, optional): Additional Socket.IO connection options

Returns: RaisonClient

client.getAgent(params)

Retrieves an agent by name. First checks local cache, then fetches from server if not found.

Parameters:

• params.name (string): The agent's name
• params.tag (string, optional): Filter by tag (e.g., 'production', 'staging')

Returns: Promise<Agent>

Throws: NotFoundError if agent is not found

client.listAgents(params?)

Retrieves all agents from the server and caches them locally.

Parameters:

• params.tag (string, optional): Filter agents by tag

Returns: Promise<Agent[]>

Throws: NotFoundError if request fails

agent.renderPrompt(variables)

Renders the agent's system prompt with Handlebars variables.

Parameters:

• variables (object): Variables to interpolate in the template

Returns: string

client.disconnect()

Closes the WebSocket connection.

Types

Agent

interface Agent {
  _id: ObjectId
  name: string
  systemPrompt: string | null
  renderPrompt: (variables: Record<string, unknown>) => string
}

GetAgentParams

type GetAgentParams = {
  name: string
  tag?: string
}

ListAgentsParams

type ListAgentsParams = {
  tag?: string
}

ConnectionState

enum ConnectionState {
  CONNECTING = 'connecting',
  CONNECTED = 'connected',
  DISCONNECTED = 'disconnected',
  ERROR = 'error'
}

SocketResponse<T>

type SocketResponse<T> =
  | { status: 'ok'; data: T }
  | { status: 'error'; message: string }

Events

The client automatically listens for real-time agent updates from the server:

• agent.changed: Updates or creates an agent in the local cache
• agent.deleted: Removes an agent from the local cache

Error Handling

The library provides custom error types:

• ConfigError: Thrown when invalid configuration is provided
• NotFoundError: Thrown when an agent is not found

import { ConfigError, NotFoundError } from 'raison-client'

try {
  const agent = await client.getAgent({ name: 'non-existent' })
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Agent not found:', error.message)
  }
}

License

MIT