CyborgProvider Component

The CyborgProvider is the main entry point for integrating the Chat SDK into your React application. It wraps your app and manages all chat functionality automatically, including rendering the chat interface.

Overview

The CyborgProvider manages:

• Chat message state and history
• Loading and error states
• API communication with the backend
• Conversation persistence across page reloads
• Context and tool registries from components
• Automatic UI rendering

No additional components need to be added to your app - the chat interface appears automatically once the provider is set up.

Basic Usage

import { CyborgProvider } from '@cyborg-sdk/react';

function App() {
  return (
    <CyborgProvider config={{ publishableKey: 'cpk_live_xxx' }}>
      {/* Your app content */}
      <YourApp />
    </CyborgProvider>
  );
}

export default App;

Configuration

The CyborgProvider accepts a config prop with the following options:

Property	Type	Required	Default	Description
publishableKey	string	Yes	-	Your Cyborg publishable key (cpk_*)
apiUrl	string	No	https://api.cyborgsdk.dev/api/v1	Custom API endpoint
debug	boolean	No	false	Enable debug logging
zIndex	number	No	2147483647	Z-index for chat widget
maxToolResultSizeKb	number	No	100	Max tool result size in KB
initialContext	CyborgContext	No	-	Base context always present
globalInstructions	string	No	-	Global AI behavior instructions
uniqueIdentifier	string	No	-	User ID for conversation history
theme	'auto' | 'light' | 'dark'	No	'auto'	Theme mode
suggestedPrompts	string[]	No	-	Default suggested prompts

Configuration Examples

Basic Setup

<CyborgProvider config={{ publishableKey: 'cpk_live_xxx' }}>
  {/* ... */}
</CyborgProvider>

Custom API Endpoint

<CyborgProvider
  config={{
    publishableKey: 'cpk_live_xxx',
    apiUrl: 'https://api.example.com/v1'
  }}
>
  {/* ... */}
</CyborgProvider>

With User ID for Conversation History

<CyborgProvider
  config={{
    publishableKey: 'cpk_live_xxx',
    uniqueIdentifier: user.id,  // Enables conversation history
    theme: 'auto'
  }}
>
  {/* ... */}
</CyborgProvider>

Full Configuration

<CyborgProvider
  config={{
    publishableKey: process.env.CYBORG_PUBLISHABLE_KEY,
    apiUrl: 'https://api.cyborgsdk.dev/api/v1',
    debug: process.env.NODE_ENV === 'development',
    zIndex: 9999,
    theme: 'dark',
    uniqueIdentifier: user.id,
    globalInstructions: 'You are a helpful product assistant. Be concise and friendly.',
    initialContext: {
      appName: 'MyApp',
      version: '1.0.0'
    },
    suggestedPrompts: [
      'How do I get started?',
      'What features are available?',
      'Contact support'
    ]
  }}
>
  {/* ... */}
</CyborgProvider>

children (required)

Your application's React components and content.

<CyborgProvider config={{ publishableKey: 'cpk_live_xxx' }}>
  <MyApp />
</CyborgProvider>

Features

Automatic Chat Interface

The provider automatically renders a floating chat widget in the bottom-right corner of your screen. No additional setup required.

<CyborgProvider config={{ publishableKey: 'cpk_live_xxx' }}>
  {/* Chat widget appears automatically */}
  <Dashboard />
</CyborgProvider>

Conversation History

When uniqueIdentifier is set, conversations are saved server-side. Users can list and load previous conversations.

<CyborgProvider config={{
  publishableKey: 'cpk_live_xxx',
  uniqueIdentifier: user.id  // Your user's unique ID
}}>
  <App />
</CyborgProvider>

Streaming Responses

Messages are streamed from the server using Server-Sent Events (SSE) for a smooth, real-time chat experience.

Tool Execution

Tools registered via useCyborg are executed locally with automatic timeout handling and size limits.

Example: Complete Application Setup

import React from 'react';
import { CyborgProvider } from '@cyborg-sdk/react';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Dashboard from './pages/Dashboard';
import Products from './pages/Products';
import Settings from './pages/Settings';

function App() {
  const publishableKey = process.env.REACT_APP_CYBORG_PUBLISHABLE_KEY;
  const user = useAuth(); // Your auth hook

  if (!publishableKey) {
    throw new Error('REACT_APP_CYBORG_PUBLISHABLE_KEY environment variable is required');
  }

  return (
    <CyborgProvider
      config={{
        publishableKey,
        uniqueIdentifier: user?.id,
        debug: process.env.NODE_ENV === 'development',
        globalInstructions: 'You are a helpful assistant for our e-commerce platform.',
        suggestedPrompts: [
          'How do I place an order?',
          'Where is my shipment?',
          'Contact support'
        ]
      }}
    >
      <Router>
        <Routes>
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/products" element={<Products />} />
          <Route path="/settings" element={<Settings />} />
        </Routes>
      </Router>
    </CyborgProvider>
  );
}

export default App;

Best Practices

1. Store Publishable Key Securely

Never hardcode your publishable key. Use environment variables instead:

// .env.local
REACT_APP_CYBORG_PUBLISHABLE_KEY=cpk_live_your_key_here

const publishableKey = process.env.REACT_APP_CYBORG_PUBLISHABLE_KEY || '';

<CyborgProvider config={{ publishableKey }}>
  {/* ... */}
</CyborgProvider>

2. Place at Top Level

Put the CyborgProvider as high as possible in your component tree to ensure all components have access to chat functionality:

function App() {
  return (
    <CyborgProvider config={{ publishableKey: 'cpk_live_xxx' }}>
      <Header />
      <Navigation />
      <MainContent />
      <Footer />
    </CyborgProvider>
  );
}

3. Enable Conversation History for Authenticated Users

Set uniqueIdentifier when users are logged in:

const config = {
  publishableKey: process.env.REACT_APP_CYBORG_PUBLISHABLE_KEY,
  ...(user && { uniqueIdentifier: user.id })
};

<CyborgProvider config={config}>
  {/* ... */}
</CyborgProvider>

4. Error Handling

The provider handles errors gracefully. Access errors through the useChat hook if needed:

import { useChat } from '@cyborg-sdk/react';

function MyComponent() {
  const { error } = useChat();

  if (error) {
    return <div>Chat Error: {error.message}</div>;
  }

  return <div>Chat loaded successfully</div>;
}

Accessing Chat State

While the CyborgProvider manages state internally, you can access and manipulate it using the hooks:

• useChat: Access chat state, messages, and actions
• useCyborg: Register context, instructions, tools, and suggested prompts

import { useChat, useCyborg } from '@cyborg-sdk/react';

function ChatStatus() {
  const { messages, isLoading, error } = useChat();

  return (
    <div>
      <p>Messages: {messages.length}</p>
      <p>Loading: {isLoading ? 'Yes' : 'No'}</p>
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

See the useChat Hook and useCyborg Hook documentation for details.