Components

Provider and context components for React.

CopilotProvider

Root provider that enables AI chat functionality. Connect to your backend API that handles LLM configuration.

Note: LLM settings (model, temperature, etc.) are configured on your server using @yourgpt/llm-sdk. The frontend only specifies the runtime URL.

import { CopilotProvider } from '@yourgpt/copilot-sdk/react';

function App() {
  return (
    <CopilotProvider
      runtimeUrl="/api/chat"
      systemPrompt="You are a helpful assistant."
      threadId="user-123-thread"
      initialMessages={[]}
      onMessagesChange={(messages) => console.log(messages)}
      debug={false}
    >
      {children}
    </CopilotProvider>
  );
}

Props

Prop	Type	Required	Description
`runtimeUrl`	`string`	Yes	Your API endpoint URL
`systemPrompt`	`string`	No	System prompt sent with each request (reactive - changes auto-apply)
`threadId`	`string`	No	Thread ID for conversation persistence
`initialMessages`	`Message[]`	No	Initial messages to populate the chat
`onMessagesChange`	`(messages: Message[]) => void`	No	Callback when messages change
`onError`	`(error: Error) => void`	No	Callback when an error occurs
`streaming`	`boolean`	No	Enable/disable streaming (default: true)
`debug`	`boolean`	No	Enable debug logging

Dynamic System Prompt

The systemPrompt prop is reactive - changes are automatically applied to the chat. You can also update it programmatically:

import { useCopilot } from '@yourgpt/copilot-sdk/react';

function MyComponent() {
  const { setSystemPrompt } = useCopilot();

  const switchToSalesMode = () => {
    setSystemPrompt('You are a sales assistant. Help users find products.');
  };

  return <button onClick={switchToSalesMode}>Sales Mode</button>;
}

Usage Patterns

Basic Setup

<CopilotProvider runtimeUrl="/api/chat">
  <CopilotChat />
</CopilotProvider>

With Tools

<CopilotProvider runtimeUrl="/api/chat">
  <MyTools />
  <CopilotChat />
</CopilotProvider>

function MyTools() {
  useTools({ ... });
  return null;
}

With Context

<CopilotProvider runtimeUrl="/api/chat">
  <MyContext />
  <CopilotChat />
</CopilotProvider>

function MyContext() {
  useAIContext({ key: 'app-state', data: state });
  return null;
}

Multiple Threads

function ChatApp() {
  const [threadId, setThreadId] = useState('thread-1');

  return (
    <CopilotProvider
      key={threadId}  // Remount on thread change
      runtimeUrl="/api/chat"
      threadId={threadId}
    >
      <ThreadSwitcher onSelect={setThreadId} />
      <CopilotChat />
    </CopilotProvider>
  );
}

Persistence

<CopilotProvider
  runtimeUrl="/api/chat"
  threadId="user-123"
  onMessagesChange={(messages) => {
    localStorage.setItem('chat-history', JSON.stringify(messages));
  }}
  initialMessages={JSON.parse(localStorage.getItem('chat-history') || '[]')}
>
  <CopilotChat />
</CopilotProvider>

Components

On this page