X Chat Provider

🎯 Skill Positioning

This skill focuses on solving one problem: How to quickly adapt your streaming interface to Ant Design X's Chat Provider.

Not involved: useXChat usage tutorial (that's another skill).

Table of Contents

• 📦 Technology Stack Overview
• 🚀 Quick Start
• Built-in Provider
• When to Use Custom Provider
• 📋 Four Steps to Implement Custom Provider
• 🔑 Core Types and Exports
• ⚙️ XRequest Advanced Configuration
• callbacks
• retryInterval Retry
• transformStream Custom Stream
• 🔧 Common Scenario Adaptation
• ⚠️ Important Reminders
• ⚡ Quick Checklist
• 🚨 Development Rules
• 🔗 Reference Resources

📦 Technology Stack Overview

// ✅ Correct import examples
import { Bubble } from '@ant-design/x';
import { AbstractChatProvider, OpenAIChatProvider } from '@ant-design/x-sdk';
import XRequest from '@ant-design/x-sdk';

🚀 Quick Start

🎯 Provider Selection Decision Tree

graph TD
    A[Start] --> B{Use standard OpenAI/DeepSeek API?}
    B -->|Yes| C[Use built-in Provider]
    B -->|No| D{Raw data format as message?}
    D -->|Yes| E[Use DefaultChatProvider]
    D -->|No| F[Custom Provider]
    C --> G[OpenAIChatProvider / DeepSeekChatProvider]
    E --> H[Pass-through, no conversion needed]
    F --> I[Four-step custom Provider]

🏭 Built-in Provider Overview

⚠️ Export names are OpenAIChatProvider / DeepSeekChatProvider / DefaultChatProvider, watch spelling

DefaultChatProvider Use Case

DefaultChatProvider passes through raw response data without any conversion. Suitable for:

• The interface response format is already what you want to display
• You want full control over Bubble.List's contentRender to render messages

import { DefaultChatProvider, XRequest } from '@ant-design/x-sdk';

interface ChatInput {
  query: string;
  stream?: boolean;
}

interface ChatOutput {
  choices: Array<{ message: { content: string; role: string } }>;
}

// DefaultChatProvider generic: <ChatMessage, Input, Output>
// ChatMessage is your Output type (passed through directly)
const provider = new DefaultChatProvider<ChatOutput | ChatInput, ChatInput, ChatOutput>({
  request: XRequest('https://your-api.com/chat', {
    manual: true,
    params: { stream: false },
  }),
});

// Render using contentRender in Bubble.List's role config
// role={{ assistant: { contentRender(content) { return content?.choices?.[0]?.message?.content } } }}

⚠️ When using DefaultChatProvider, ChatMessage is typically your Output type or a union type; rendering requires contentRender

📋 Four Steps to Implement Custom Provider

Step 1: Analyze Interface Format ⏱️ 2 minutes

Step 2: Create Provider Class ⏱️ 5 minutes

// MyChatProvider.ts
import { AbstractChatProvider } from '@ant-design/x-sdk';
import type { TransformMessage } from '@ant-design/x-sdk';
import type { XRequestOptions } from '@ant-design/x-sdk';

interface MyInput {
  query: string;
  model?: string;
  stream?: boolean;
}

interface MyOutput {
  content: string;
  finish_reason?: string;
}

interface MyMessage {
  content: string;
  role: 'user' | 'assistant';
}

export class MyChatProvider extends AbstractChatProvider<MyMessage, MyInput, MyOutput> {
  // Parameter conversion: merge onRequest params + XRequest default params
  // options comes from XRequest(url, options), can access options.params etc.
  transformParams(
    requestParams: Partial<MyInput>,
    options: XRequestOptions<MyInput, MyOutput, MyMessage>,
  ): MyInput {
    return {
      ...(options?.params || {}),
      query: requestParams.query || '',
      model: 'gpt-3.5-turbo',
      stream: true,
    };
  }

  // Local message: convert onRequest params to the user-side display message (can return array)
  transformLocalMessage(requestParams: Partial<MyInput>): MyMessage {
    return {
      content: requestParams.query || '',
      role: 'user',
    };
  }

  // Response conversion:
  // info.originMessage: previous content of this message (for stream accumulation)
  // info.chunk: current streaming chunk
  // info.chunks: all received chunks (used in onSuccess)
  // info.status: current status
  // ⚠️ Return only MyMessage type; do NOT add a status field
  transformMessage(info: TransformMessage<MyMessage, MyOutput>): MyMessage {
    const { originMessage, chunk } = info;

    if (!chunk?.content || chunk.content === '[DONE]') {
      return { ...(originMessage || { content: '', role: 'assistant' }) };
    }

    return {
      content: `${originMessage?.content || ''}${chunk.content}`,
      role: 'assistant',
    };
  }
}

Step 3: Verify ⏱️ 1 minute

Step 4: Use Provider ⏱️ 1 minute

import { MyChatProvider } from './MyChatProvider';
import XRequest from '@ant-design/x-sdk';

// ⚠️ Must pass manual: true, otherwise AbstractChatProvider constructor will throw
const provider = new MyChatProvider({
  request: XRequest('https://your-api.com/chat', {
    manual: true,
    headers: {
      Authorization: 'Bearer your-token',
      'Content-Type': 'application/json',
    },
    params: {
      model: 'gpt-3.5-turbo',
      stream: true,
    },
  }),
});

export { provider };

🔑 Core Types and Exports

Key types exported from @ant-design/x-sdk:

import type {
  // OpenAI standard message format
  XModelMessage, // { role: string; content: string | { text: string; type: string } }
  XModelParams, // Full OpenAI request params type (model, messages, stream, temperature, etc.)
  XModelResponse, // Full OpenAI response type (choices, usage, etc.)

  // SSE stream field types
  SSEFields, // 'data' | 'event' | 'id' | 'retry'
  SSEOutput, // Partial<Record<SSEFields, any>>

  // Provider related
  TransformMessage, // { originMessage, chunk, chunks, status, responseHeaders }

  // XRequest related
  XRequestOptions, // Full request config
  XRequestCallbacks, // { onUpdate, onSuccess, onError }

  // Message related
  MessageInfo, // { id, message, status, extraInfo }
} from '@ant-design/x-sdk';

XModelMessage Structure (OpenAI message format)

// XModelMessage is the standard OpenAI message format
// Used for OpenAIChatProvider / DeepSeekChatProvider ChatMessage generic
const userMessage: XModelMessage = { role: 'user', content: 'Hello' };
const systemMessage: XModelMessage = { role: 'system', content: 'You are an assistant' };
const developerMessage: XModelMessage = { role: 'developer', content: 'System prompt' };

SSEOutput and SSEFields

// SSEOutput is the type for raw SSE stream data
// { data?: string; event?: string; id?: string; retry?: number }
// DeepSeekChatProvider uses Partial<Record<SSEFields, XModelResponse>>

import { DeepSeekChatProvider, XRequest } from '@ant-design/x-sdk';
import type { SSEFields, XModelParams, XModelResponse } from '@ant-design/x-sdk';

const provider = new DeepSeekChatProvider({
  request: XRequest<XModelParams, Partial<Record<SSEFields, XModelResponse>>>(
    'https://api.deepseek.com/v1/chat/completions',
    {
      manual: true,
      params: { model: 'deepseek-chat', stream: true },
    },
  ),
});

⚙️ XRequest Advanced Configuration

callbacks

callbacks allows monitoring request events at the Provider level. The third parameter in callbacks is the MessageInfo processed by transformMessage:

const provider = new OpenAIChatProvider({
  request: XRequest<XModelParams, XModelResponse, XModelMessage>(BASE_URL, {
    manual: true,
    callbacks: {
      // onUpdate: triggered on each streaming chunk arrival
      // chunk: current chunk; responseHeaders: response headers; message: current MessageInfo
      onUpdate: (chunk, responseHeaders, message) => {
        console.log('Stream update:', message?.message?.content);
      },
      // onSuccess: triggered when all chunks are received
      // chunks: all chunks array; message: final MessageInfo
      onSuccess: (chunks, responseHeaders, message) => {
        console.log('Request complete:', message?.message?.content);
        // Good place for analytics, logging, etc.
      },
      // onError: triggered on request failure (including AbortError)
      // error: error object; errorInfo: extra error info; message: MessageInfo at failure
      onError: (error, errorInfo, responseHeaders, message) => {
        console.error('Request failed:', error.message);
      },
    },
    params: { model: 'gpt-4o', stream: true },
  }),
});

⚠️ callbacks and useXChat's requestFallback do not conflict — both execute. callbacks is better for logging/reporting; requestFallback controls UI display.

retryInterval Retry

const request = XRequest('https://your-api.com/chat', {
  manual: true,
  // Retry interval after failure (ms)
  retryInterval: 3000,
  // Max retry count (unlimited if not set)
  retryTimes: 3,
  // onError can also return a number to dynamically set retry interval
  callbacks: {
    onError: (error) => {
      if (error.name === 'AbortError') return; // Don't retry on user cancel
      return 5000; // Return number = retry after 5s (higher priority than retryInterval)
    },
  },
});

transformStream Custom Stream

Use when the server returns a non-standard SSE stream format:

const request = XRequest('https://your-api.com/chat', {
  manual: true,
  // Fixed TransformStream
  transformStream: new TransformStream({
    transform(chunk, controller) {
      controller.enqueue(JSON.parse(chunk));
    },
  }),
  // Or decide dynamically based on URL and response headers
  transformStream: (baseURL, responseHeaders) => {
    if (responseHeaders.get('x-stream-type') === 'ndjson') {
      return new TransformStream({
        /* ... */
      });
    }
    return undefined; // Use default SSE parsing
  },
});

🔧 Common Scenario Adaptation

📖 Complete Examples: EXAMPLES.md

⚠️ Important Reminders

🚨 Mandatory Rule: Never write a request method!

// ❌ Serious error
class MyProvider extends AbstractChatProvider {
  async request(params: any) {
    /* Forbidden! */
  }
}

// ✅ Only correct approach: implement only the three conversion methods
class MyProvider extends AbstractChatProvider {
  transformParams(params, options) {
    /* ... */
  }
  transformLocalMessage(params) {
    /* ... */
  }
  transformMessage(info) {
    /* ... */
  }
}

⚠️ transformMessage must not return status

// ❌ Wrong
transformMessage(info) {
  return { content: '...', status: 'error' }; // ❌ status is managed by the framework
}

// ✅ Correct
transformMessage(info) {
  return { content: '...' }; // ✅
}

⚠️ Provider instantiation notes

// ✅ In React components, use useState to ensure only created once
const [provider] = React.useState(
  new MyChatProvider({
    request: XRequest(URL, { manual: true }),
  }),
);

// ❌ Don't create directly in render function (creates new instance on every render)
// const provider = new MyChatProvider(...); // inside component body causes issues

⚡ Quick Checklist

Before creating Provider:

• [ ] Have interface docs and response format
• [ ] Confirmed whether custom is needed (or if built-in Provider suffices)
• [ ] Defined Input, Output, ChatMessage types

After completion:

• [ ] Only implemented the three required methods
• [ ] transformParams includes second parameter options
• [ ] transformMessage return value has no status field
• [ ] XRequest configured with manual: true
• [ ] Absolutely no request method implemented
• [ ] Provider wrapped with useState in React component
• [ ] Type check passes (tsc --noEmit)

🚨 Development Rules

• If the user does not explicitly need test cases, do not add test files
• After completion, must check types: Run tsc --noEmit to ensure no type errors
• Keep code clean: Remove all unused variables and imports

🔗 Reference Resources

📚 Core Reference Documentation

• EXAMPLES.md - Practical example code

🌐 SDK Official Documentation

• useXChat Official Documentation
• XRequest Official Documentation
• Chat Provider Official Documentation

💻 Example Code

• custom-provider-width-ui.tsx
• openai-callback.tsx

x-chat-provider Practical Examples

Scenario 1: OpenAI / DeepSeek Built-in Provider

import { OpenAIChatProvider, DeepSeekChatProvider, XRequest } from '@ant-design/x-sdk';
import type { XModelParams, XModelResponse, SSEFields } from '@ant-design/x-sdk';

// OpenAI format
const openaiProvider = new OpenAIChatProvider({
  request: XRequest<XModelParams, XModelResponse>('https://api.openai.com/v1/chat/completions', {
    manual: true,
    headers: { Authorization: 'Bearer your-api-key' },
    params: { model: 'gpt-4o', stream: true },
  }),
});

// DeepSeek format (note Output type is Partial<Record<SSEFields, XModelResponse>>)
const deepseekProvider = new DeepSeekChatProvider({
  request: XRequest<XModelParams, Partial<Record<SSEFields, XModelResponse>>>(
    'https://api.deepseek.com/v1/chat/completions',
    {
      manual: true,
      headers: { Authorization: 'Bearer your-api-key' },
      params: { model: 'deepseek-chat', stream: true },
    },
  ),
});

Scenario 2: DefaultChatProvider (Pass-through raw data)

Suitable for cases where no format conversion is needed and rendering is handled in Bubble.List's contentRender:

import { DefaultChatProvider, useXChat, XRequest } from '@ant-design/x-sdk';
import { Bubble, Sender } from '@ant-design/x';
import type { BubbleListProps } from '@ant-design/x';
import React from 'react';

interface ChatInput {
  query: string;
  role: 'user';
  stream?: boolean;
}

interface ChatOutput {
  choices: Array<{ message: { content: string; role: string } }>;
}

// ChatMessage is a union type of ChatOutput | ChatInput
const provider = new DefaultChatProvider<ChatOutput | ChatInput, ChatInput, ChatOutput>({
  request: XRequest('https://api.x.ant.design/api/default_chat_provider_stream', {
    manual: true,
  }),
});

// contentRender decides how to render based on message type
const role: BubbleListProps['role'] = {
  assistant: {
    placement: 'start',
    contentRender(content: ChatOutput) {
      return content?.choices?.[0]?.message?.content;
    },
  },
  user: {
    placement: 'end',
    contentRender(content: ChatInput) {
      return content?.query;
    },
  },
};

const App = () => {
  const { messages, onRequest, isRequesting, abort } = useXChat({
    provider,
    requestPlaceholder: {
      choices: [{ message: { content: 'Loading...', role: 'assistant' } }],
    },
    requestFallback: {
      choices: [{ message: { content: 'Request failed, please retry', role: 'assistant' } }],
    },
  });

  return (
    <>
      <Bubble.List
        role={role}
        items={messages.map(({ id, message, status }) => ({
          key: id,
          loading: status === 'loading',
          role: (message as ChatInput).role || (message as ChatOutput)?.choices?.[0]?.message?.role,
          content: message,
        }))}
      />
      <Sender
        loading={isRequesting}
        onCancel={abort}
        onSubmit={(val) => onRequest({ query: val, role: 'user', stream: false })}
      />
    </>
  );
};

Scenario 3: Custom Provider (Private API)

import { AbstractChatProvider, XRequest } from '@ant-design/x-sdk';
import type { TransformMessage, XRequestOptions } from '@ant-design/x-sdk';

interface MyInput {
  query: string;
  context?: string;
  model?: string;
  stream?: boolean;
}

interface MyOutput {
  content: string;
  finish_reason?: string;
}

interface MyMessage {
  content: string;
  role: 'user' | 'assistant';
}

export class MyChatProvider extends AbstractChatProvider<MyMessage, MyInput, MyOutput> {
  transformParams(
    requestParams: Partial<MyInput>,
    options: XRequestOptions<MyInput, MyOutput, MyMessage>,
  ): MyInput {
    return {
      ...(options?.params || {}),
      query: requestParams.query || '',
      context: requestParams.context,
      model: 'gpt-3.5-turbo',
      stream: true,
    };
  }

  transformLocalMessage(requestParams: Partial<MyInput>): MyMessage {
    return {
      content: requestParams.query || '',
      role: 'user',
    };
  }

  transformMessage(info: TransformMessage<MyMessage, MyOutput>): MyMessage {
    const { originMessage, chunk } = info;

    if (!chunk?.content || chunk.content === '[DONE]') {
      return { ...(originMessage || { content: '', role: 'assistant' }) };
    }

    return {
      content: `${originMessage?.content || ''}${chunk.content}`,
      role: 'assistant',
    };
  }
}

export const provider = new MyChatProvider({
  request: XRequest<MyInput, MyOutput, MyMessage>('https://your-api.com/chat', {
    manual: true,
    headers: {
      Authorization: 'Bearer your-token',
      'Content-Type': 'application/json',
    },
    params: {
      model: 'gpt-3.5-turbo',
      stream: true,
    },
  }),
});

Scenario 4: Provider with callbacks (Logging / Reporting)

import { OpenAIChatProvider, XRequest } from '@ant-design/x-sdk';
import type { XModelParams, XModelResponse, XModelMessage } from '@ant-design/x-sdk';

const provider = new OpenAIChatProvider({
  request: XRequest<XModelParams, XModelResponse, XModelMessage>(BASE_URL, {
    manual: true,
    callbacks: {
      // Triggered on each streaming update; message is the current MessageInfo (with transformMessage result)
      onUpdate: (chunk, responseHeaders, message) => {
        console.log('Stream update content length:', message?.message?.content?.length);
      },
      // Triggered when all chunks are complete; good for token counting / reporting
      onSuccess: (chunks, responseHeaders, message) => {
        const finalContent = message?.message?.content;
        analytics.track('chat_complete', { length: finalContent?.length });
      },
      // Triggered on request failure (including user abort)
      onError: (error, errorInfo, responseHeaders, message) => {
        if (error.name !== 'AbortError') {
          errorLogger.report(error);
        }
      },
    },
    params: { model: 'gpt-4o', stream: true },
  }),
});

Scenario 5: Provider with Auto-retry

import { OpenAIChatProvider, XRequest } from '@ant-design/x-sdk';

const provider = new OpenAIChatProvider({
  request: XRequest(BASE_URL, {
    manual: true,
    retryInterval: 3000, // Retry 3 seconds after failure
    retryTimes: 3, // Max 3 retries
    callbacks: {
      onError: (error) => {
        // Don't retry on user abort; return number to override retryInterval
        if (error.name === 'AbortError') return;
        return 5000; // Dynamic retry interval of 5 seconds
      },
    },
    params: { model: 'gpt-4o', stream: true },
  }),
});

Scenario 6: Multi-field Response (with Attachments)

import { AbstractChatProvider } from '@ant-design/x-sdk';
import type { TransformMessage, XRequestOptions } from '@ant-design/x-sdk';

interface MyOutput {
  content: string;
  attachments?: Array<{ name: string; url: string; type: string }>;
}

interface MyMessage {
  content: string;
  role: 'user' | 'assistant';
  attachments?: Array<{ name: string; url: string; type: string }>;
}

class AttachmentProvider extends AbstractChatProvider<MyMessage, { query: string }, MyOutput> {
  transformParams(params: Partial<{ query: string }>, options: XRequestOptions<any, any, any>) {
    return { ...(options?.params || {}), query: params.query || '' };
  }

  transformLocalMessage(params: Partial<{ query: string }>): MyMessage {
    return { content: params.query || '', role: 'user' };
  }

  transformMessage(info: TransformMessage<MyMessage, MyOutput>): MyMessage {
    const { originMessage, chunk } = info;

    if (!chunk || chunk.content === '[DONE]') {
      return { ...(originMessage || { content: '', role: 'assistant' }) };
    }

    try {
      const data = typeof chunk === 'string' ? JSON.parse(chunk) : chunk;
      const existingAttachments = originMessage?.attachments || [];
      const newAttachments = data.attachments || [];

      // Merge attachments, avoid duplicates
      const mergedAttachments = [...existingAttachments];
      newAttachments.forEach((a: any) => {
        if (!mergedAttachments.some((e) => e.url === a.url)) {
          mergedAttachments.push(a);
        }
      });

      return {
        content: `${originMessage?.content || ''}${data.content || ''}`,
        role: 'assistant',
        attachments: mergedAttachments,
      };
    } catch {
      return {
        content: `${originMessage?.content || ''}`,
        role: 'assistant',
        attachments: originMessage?.attachments || [],
      };
    }
  }
}

Scenario 7: Multi-conversation Provider Factory (with useXConversations)

import { OpenAIChatProvider, XRequest } from '@ant-design/x-sdk';
import type { XModelParams, XModelResponse } from '@ant-design/x-sdk';

// Each conversation gets its own Provider instance to avoid state mixing
const providerCache = new Map<string, OpenAIChatProvider>();

export function getProvider(conversationKey: string): OpenAIChatProvider {
  if (!providerCache.has(conversationKey)) {
    providerCache.set(
      conversationKey,
      new OpenAIChatProvider({
        request: XRequest<XModelParams, XModelResponse>(BASE_URL, {
          manual: true,
          params: { model: 'gpt-4o', stream: true },
        }),
      }),
    );
  }
  return providerCache.get(conversationKey)!;
}

// Usage in component:
// provider={getProvider(activeConversationKey)}
// conversationKey={activeConversationKey}