@camunda/copilot-chat

React component library for embedding Camunda Copilot chat interface into web applications.

Installation

npm install @camunda/copilot-chat

Peer Dependencies:

npm install react react-dom @carbon/react @carbon/icons-react

Quick Start

import { CopilotChat, useChatStore } from '@camunda/copilot-chat';
import '@camunda/copilot-chat/style.css';

function App() {
  const handleSendMessage = async (message: string) => {
    const { addAssistantMessage, appendToMessage, updateMessageStatus } = useChatStore.getState();
    const messageId = `msg-${Date.now()}`;
    addAssistantMessage(messageId);
    appendToMessage(messageId, 'Hello!');
    updateMessageStatus(messageId, 'complete'); // 'pending' | 'streaming' | 'complete' | 'error'
  };

  return <CopilotChat onSendMessage={handleSendMessage} workareaSelector="body" />;
}

With Agent Adapter (Recommended)

For full agent orchestration with tool execution:

import { useMemo } from 'react';
import { CopilotChat, useAgentAdapter } from '@camunda/copilot-chat';
import '@camunda/copilot-chat/style.css';

function App() {
  const transport = useMemo(
    () => ({
      subscribe: (id, onEvent) => {
        /* Subscribe to events */
      },
      unsubscribe: (id) => {
        /* Cleanup */
      },
      sendMessage: async (payload) => {
        /* POST to backend */
      },
      sendToolResult: async (payload) => {
        /* POST tool result */
      },
    }),
    []
  );

  const { sendMessage, stopGeneration, resetConversation } = useAgentAdapter({
    transport,
    frontendTools: [{ name: 'my_tool', description: '...', parametersSchema: '{}' }],
    onToolInvoke: async (toolName, args) => {
      /* Return result */
    },
  });

  return <CopilotChat onSendMessage={sendMessage} onStopGeneration={stopGeneration} onResetConversation={resetConversation} />;
}

Props

| Prop | Type | Required | Description | | ----------------------- | ------------------------------------ | -------- | ---------------------------------------- | | onSendMessage | (message: string) => Promise<void> | Yes | Called when user sends a message | | onStopGeneration | () => void | No | Called when user clicks stop button | | onResetConversation | () => void | No | Called when user resets the conversation | | workareaSelector | string | No | CSS selector for the main content area | | emptyStateTitle | string | No | Title shown when chat is empty | | emptyStateDescription | string | No | Description shown when chat is empty |

Documentation

See the docs folder for detailed documentation:

• Architecture Overview
• Integration Guide
• Writing Adapters

License

Camunda License 1.0 - See LICENSE file for details.