@agentscope-ai/chat

Alibaba Cloud Spark Chat

Note: @agentscope-ai/design and @agentscope-ai/chat are actively progressing towards open source, with completion expected by the end of 2025. Currently, you can access our projects through npm.

A free, open-source React chat framework based on Alibaba Cloud Spark Design, designed for building excellent LLM conversation experiences.

Features

• Built on Alibaba Cloud Bailian best practices: Incorporates our team's extensive experience and real-world business solutions, enabling rapid development of excellent LLM conversation experiences.
• Out-of-the-box model integration capabilities: Easily integrate with model inference services that comply with OpenAI standards.
• Ultimate extensibility: Present model outputs through customizable card components, supporting diverse output display formats.
• Full TypeScript coverage: Developed with TypeScript, providing complete type support to enhance development experience and reliability.
• Use Modern CSS-in-JS: Implements a contemporary CSS-in-JS styling solution with automatic on-demand loading, minimizing dependencies on developer's build configuration.

Quick Start

Method 1: Using CLI Tool (Recommended)

The quickest way is to use our CLI tool:

# Option 1: Install globally (recommended)
npm install -g @agentscope-ai/chat
agentscope-runtime-webui -p 3000

# Option 2: Use npx (no installation required)
npx @agentscope-ai/chat agentscope-runtime-webui -p 3000

# Option 3: Local development (npm link first)
npm link
agentscope-runtime-webui -p 3000

Common Command Examples:

# Start with default configuration (port 3000)
agentscope-runtime-webui

# Specify port
agentscope-runtime-webui --port 8080

# Specify backend API URL
agentscope-runtime-webui --url http://api.example.com

# Specify authentication token
agentscope-runtime-webui --token your-auth-token

# Combine options
agentscope-runtime-webui -p 8080 -u http://api.example.com -t your-token

CLI Options:

Option	Short	Description	Default
--port	-p	Specify server port	3000
--url	-u	Specify backend API URL	-
--token	-t	Specify authentication token	-

Method 2: Integrate into Project

Installation

# Install dependencies
npm install antd --save
npm install @agentscope-ai/design --save
npm install @agentscope-ai/chat --save

Note: If you are an Alibaba internal developer, please use:

tnpm install @ali/agentscope-ai-chat @ali/agentscope-ai-design --save

Basic Usage

import { ConfigProvider, carbonTheme } from '@agentscope-ai/design';
import { ChatAnywhere, ChatAnywhereRef, uuid } from '@agentscope-ai/chat';
import { useRef, useCallback } from 'react';

export default function App() {
  const ref = useRef<ChatAnywhereRef>();

  const onSubmit = useCallback(async (data) => {
    // Add user message
    ref.current.updateMessage({
      id: uuid(),
      role: 'user',
      content: data.query,
    });

    // Add assistant reply
    ref.current.updateMessage({
      id: uuid(),
      role: 'assistant',
      content: 'This is the assistant reply content',
    });
  }, []);

  return (
    <ConfigProvider {...carbonTheme}>
      <ChatAnywhere ref={ref} onInput={{ onSubmit }} onStop={() => {}} />
    </ConfigProvider>
  );
}

Core Components

ChatAnywhere

An out-of-the-box chat container that eliminates the need to manage message state, enabling rapid development of LLM conversation experiences.

import { ChatAnywhere, ChatAnywhereRef } from '@agentscope-ai/chat';

// Use ref to control message updates
const ref = useRef<ChatAnywhereRef>();
ref.current.updateMessage(message);

Bubble

Message bubble component supporting various message type displays.

import { Bubble, DefaultCards } from '@agentscope-ai/chat';

<Bubble message={message} customCards={DefaultCards} />;

Sender

Message sending component supporting multiple input modes.

import { Sender } from '@agentscope-ai/chat';

<Sender onSubmit={handleSubmit} loading={loading} />;

Markdown

Markdown rendering component supporting mathematical formulas, code highlighting, and more.

import { Markdown } from '@agentscope-ai/chat';

<Markdown content={markdownContent} />;

Mermaid

Flowchart rendering component.

import { Mermaid } from '@agentscope-ai/chat';

<Mermaid code={mermaidCode} />;

Advanced Features

Custom Cards

Display special content through custom card components:

import { CustomCardsProvider } from '@agentscope-ai/chat';

const CustomCard = function(props: { data }) {
  return <div>Custom Card</div>;
}

<CustomCardsProvider cards={{ CustomCard }}>
  <ChatAnywhere />
</CustomCardsProvider>;

Streaming Response

Support streaming data updates:

import { Stream } from '@agentscope-ai/chat';

const response = await fetch('/api/chat');
for await (const chunk of Stream({ readableStream: response.body })) {
  // ...
  // const answer = {...}
  // ref.current.updateMessage(answer);
}

Compatible Environments

• Modern browsers
• Electron
• Tauri

Edge	Firefox	Chrome	Safari	Opera	Electron
last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions	last 2 versions

Documentation

• Overview
• ChatAnywhere Usage Guide
• Bailian Agent Integration
• Custom Cards
• Vite Integration
• Umi Integration

Related Links

• Alibaba Cloud Spark Design
• Alibaba Cloud Bailian
• React
• Ant Design

Contributing

We welcome Issue submissions and Pull Requests!

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.