React Hooks

The @baleybots/react package provides React hooks for building chat interfaces and using Baleybots agents in React applications.

Installation

npm install @baleybots/react @baleybots/core

useChat

useChat is the primary hook for building chat interfaces. It supports two modes:

• Client mode (default) -- runs the agent locally in the browser
• Server mode -- connects to a backend API via apiUrl and chatId

Client mode

import { useChat } from '@baleybots/react';

function ChatComponent() {
  const { segments, sendStreaming, isStreaming } = useChat({
    model: 'openai|gpt-4.1-mini',
    systemPrompt: 'You are a helpful assistant',
  });

  const handleSend = async (text: string) => {
    await sendStreaming(text);
  };

  return (
    <div>
      {segments.map((segment) => {
        if (segment.type === 'user') {
          return <div key={segment.id}><b>You:</b> {segment.content}</div>;
        }
        if (segment.type === 'text') {
          return <div key={segment.id}><b>Assistant:</b> {segment.content}</div>;
        }
        return null;
      })}
    </div>
  );
}

Server mode

When apiUrl is set, useChat connects to a backend instead of running the agent locally. Use chatId to persist conversations.

import { useChat } from '@baleybots/react';

function ChatComponent() {
  const { segments, sendStreaming, isStreaming } = useChat({
    apiUrl: 'https://your-api.com/chat',
    chatId: 'conversation-123',
  });

  // Same rendering code as client mode
}

Return values

The hook returns:

Property	Type	Description
segments	StreamSegment[]	All segments in the conversation
isLoading	boolean	Whether a request is in progress
isStreaming	boolean	Whether a response is currently streaming
error	Error | null	Last error, if any
send	(text: string) => Promise	Send a message (no streaming)
sendStreaming	(text: string) => Promise	Send a message with streaming
clearHistory	() => Promise<void>	Clear the conversation
stopStreaming	() => void	Abort the current stream

Options

Option	Type	Description
model	string | ModelConfig	LLM model to use
systemPrompt	string	System prompt for the assistant
tools	Record<string, ToolDefinition>	Tools available to the assistant
outputSchema	ZodSchema	Schema for structured responses
apiUrl	string	Backend URL (activates server mode)
chatId	string	Conversation ID (server mode)
storage	HistoryStorage	Custom history storage backend
proxyUrl	string	Proxy URL for API requests
fetch	typeof fetch	Custom fetch (e.g., for React Native)

useBaleybot

useBaleybot wraps a Baleybot agent for direct use in React. It manages the agent lifecycle and provides a simple interface.

import { useBaleybot } from '@baleybots/react';
import { z } from 'zod';

function SentimentAnalyzer() {
  const { process, result, isProcessing } = useBaleybot({
    name: 'sentiment',
    goal: 'Analyze the sentiment of text',
    outputSchema: z.object({
      sentiment: z.enum(['positive', 'negative', 'neutral']),
      confidence: z.number(),
    }),
  });

  return (
    <div>
      <button onClick={() => process('I love this product!')}>
        Analyze
      </button>
      {result && <p>Sentiment: {result.sentiment} ({result.confidence})</p>}
    </div>
  );
}

Deprecated: useGroupChat

useGroupChat is deprecated. Use useChat with apiUrl and chatId instead:

// Before (deprecated)
import { useGroupChat } from '@baleybots/react';
const { messages } = useGroupChat({ apiUrl: '...', chatId: '...' });

// After
import { useChat } from '@baleybots/react';
const { segments } = useChat({ apiUrl: '...', chatId: '...' });

See the Unified useChat Hook migration guide for details.