@dopomogai/chatbot

A powerful, reusable React component for building rich, interactive chat experiences with AI agents from the Dopomogai platform.

This package provides a complete chat UI and logic, designed to be integrated into internal applications, administrative dashboards, and proof-of-concept AI apps. It moves beyond a simple embeddable widget by offering deep integration with your application's data, authentication, and frontend logic via a robust tool-rendering system.

Features

• Two-Pane Interface: A clean layout featuring a list of past conversations and an active chat window.
• Full Conversation Management: Start new chats, switch between existing conversations, and persist chat history.
• Dynamic Context Injection: Pass real-time data from your application (e.g., user info, current page) to the agent's first prompt for more personalized interactions.
• Frontend Tool Rendering: A powerful system to render custom React components in response to an agent's tool call, allowing you to build forms, confirmation dialogs, data visualizations, and more, directly within the chat.
• Real-time Streaming: Messages, including "thinking" steps and tool calls, are streamed in real-time using Server-Sent Events (SSE).
• Built with @dopomogai/ui: Leverages the Dopomogai Neobrutalist design system for a consistent look and feel.
• TypeScript-First: Fully typed for a superior and safer development experience.

Installation

This package is designed to work within the Dopomogai monorepo and relies on other internal packages.

# From the monorepo root
pnpm install

Usage

The <Chatbot /> component is the main entry point. You provide it with an agentId, a toolRegistry, and optional initialContext.

1. Create Your Tool Components

First, define the custom React components that your agent can call. Each tool component receives args from the agent and onSubmit/onCancel callbacks.

// src/features/chat/MyToolComponents.tsx

import React from 'react';
import { Button, TextField } from '@dopomogai/ui';
import type { ToolProps } from '@dopomogai/chatbot';

// A tool that renders a form to book a demo
export const BookDemoTool: React.FC<ToolProps> = ({ args, onSubmit, onCancel }) => {
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // The object passed to onSubmit is sent back to the agent
    onSubmit({ name, email, timeSlot: args.suggested_slot });
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <h3 className="font-bold text-lg">Book a Demo for {args.suggested_slot}</h3>
      <TextField
        label="Full Name"
        value={name}
        onChange={(e) => setName(e.target.value)}
        required
      />
      <TextField
        label="Email Address"
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        required
      />
      <div className="flex gap-3 pt-2">
        <Button variant="primary" text="Confirm Booking" type="submit" />
        <Button variant="secondary" onClick={onCancel} text="Cancel" type="button" />
      </div>
    </form>
  );
};

2. Create a Tool Registry

The tool registry maps the string names your agent uses (e.g., "book_demo_form") to your React components.

// src/features/chat/MyToolComponents.tsx
import { createToolRegistry } from '@dopomogai/chatbot';

export const myAppToolRegistry = createToolRegistry({
  'book_demo_form': BookDemoTool,
  // Add other tools here
  // 'confirm_purchase': ConfirmationToolComponent,
});

3. Render the Chatbot Component

In your application, import the <Chatbot /> component and provide it with the necessary props.

// src/pages/AgentDashboardPage.tsx

import { Chatbot } from '@domopogai/chatbot';
import { myAppToolRegistry } from '../features/chat/MyToolComponents';
import { useUser } from '@dopomogai/supabase-client/react'; // Example of getting app data

export function AgentDashboardPage() {
  const agentId = "agent_7a4b1c9e-6f8d-4e2a-9b1c-0d3e5f7a2b1d"; // The ID of the agent to chat with
  const user = useUser();

  // Gather any relevant, real-time context from your application
  const dynamicContext = {
    user_email: user?.email,
    user_id: user?.id,
    current_url_path: window.location.pathname,
  };

  return (
    <div className="p-8">
      <h1 className="text-3xl font-bold mb-6">Agent Interaction</h1>
      <div className="w-full max-w-5xl mx-auto">
        <Chatbot
          agentId={agentId}
          toolRegistry={myAppToolRegistry}
          initialContext={dynamicContext}
        />
      </div>
    </div>
  );
}

Component API

<Chatbot /> Props

| Prop | Type | Required | Description | | ---------------- | --------------------------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | agentId | string | Yes | The unique identifier (UUID) of the Dopomogai agent to interact with. | | toolRegistry | ToolRegistry | Yes | An object created by createToolRegistry that maps tool names (strings) to your React components. This is how the chatbot knows what to render when the agent calls a frontend tool. | | initialContext | Record<string, any> | No | An object containing dynamic data to be injected into the agent's prompt on the first message of a new conversation. Useful for providing user details, session information, or page context. This context is ignored for subsequent messages or in existing conversations. | | className | string | No | An optional CSS class name to apply to the root container of the chatbot, allowing for custom styling and layout adjustments. | | style | React.CSSProperties | No | An optional inline style object to apply to the root container. |

ToolProps

Every component you register in the toolRegistry will receive a single props object with the following shape:

| Prop | Type | Description | | ---------- | --------------------- | ------------------------------------------------------------------------------------------------------- | | args | any | The arguments object sent by the agent for this specific tool call. | | onSubmit | (result: any) => void | A callback function to submit the tool's result. The result is serialized and sent back to the agent. | | onCancel | () => void | A callback function to cancel the tool interaction and inform the agent. |

How It Works

The <Chatbot /> component is powered by the useChatManager hook, which orchestrates all state and API communication.

1. Authentication: The component relies on an active session being managed by @dopomogai/supabase-client. It assumes a user is already logged in.
2. Initialization: On mount, it fetches the list of past conversations for the given agentId using the authenticated user's credentials.
3. Chat Session (WAT): When a message is sent or a conversation history is viewed, the hook first calls agentTestChatService.initSession() to get a temporary, secure Web Access Token (WAT).
4. Streaming: This WAT is then used to establish a Server-Sent Events (SSE) connection to the /stream endpoint. The hook listens for typed events (message_start, tool_call_start, message_chunk, etc.) and updates the React state accordingly.
5. Tool Rendering: When a tool_call_start event is received for a tool that exists in your toolRegistry, the ToolRenderer component displays your custom React component, passing it the required args and callbacks. When you call onSubmit, the result is sent back through the same streaming channel to the agent, allowing the conversation to continue.