React Hooks

The @baleybots/react package provides React hooks for building chat interfaces and using Baleybots processors 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 processor locally in the browser
• Server mode — connects to a backend API via apiUrl and chatId

Client mode

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

const ResponseSchema = z.object({
  response: z.string(),
});

function ChatComponent() {
  const { segments, sendStreaming, isStreaming } = useChat({
    model: 'openai|gpt-4.1-mini',
    systemPrompt: 'Answer concisely and accurately',
    responseSchema: ResponseSchema, // converted to Output.object() internally
  });

  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>Response:</b> {segment.content}</div>;
        }
        return null;
      })}
    </div>
  );
}

Server mode

When apiUrl is set, useChat connects to a backend instead of running 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
pendingApprovals	PendingApproval[]	Gated tools awaiting approval (derived from segments)
respondToToolApprovals	(responses: ToolApprovalResponse[]) => void	Approve/reject one or more pending tool calls in a single resume

Options

Option	Type	Description
model	string | ModelConfig	LLM model to use
systemPrompt	string	System prompt for the processor
tools	Record<string, ToolDefinition>	Tools available to the processor
responseSchema	ZodSchema | JSON Schema	Structured response schema (maps to Output.object() on the underlying Baleybot)
maxToolIterations	number	Tool loop step cap (maps to stopWhen: stepCountIs(n); default 50)
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)
shouldAskApproval	(toolName: string) => boolean	Auto-approve/deny without prompting; remaining approvals still require respondToToolApprovals
onApprovalRequest	(pending: PendingApproval) => void	Fired when a new approval request appears

useBaleybot

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

The hook accepts outputSchema (Zod or JSON Schema) and converts it to Output.object() when creating the underlying processor.

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

function SentimentAnalyzer() {
  const { process, result, isProcessing } = useBaleybot({
    name: 'sentiment',
    analysisGoal: '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>
  );
}

For direct Baleybot.create() usage outside React, prefer the output config with Output.object() — see Structured Outputs.

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.