Chat Provider

The Provider is handed over to useXChat, which is responsible for grouping request parameters and collecting chunk messages. request during construction must be manual: true, otherwise request must be manual is thrown.

createOpenAIChatProvider

This is the entry point of 1.x useXAgent({ baseURL, model, dangerouslyApiKey | key }) in 2.10. React 2.10 deleted useXAgent and directly used new OpenAIChatProvider. Vue retains the default shape to prevent the caller from handwriting the header.

import { createOpenAIChatProvider, useXChat } from 'ant-design-x-vue';

const provider = createOpenAIChatProvider({
  baseURL: 'https://api.openai.com/v1/chat/completions',
  model: 'gpt-4o-mini',
  dangerouslyApiKey: 'YOUR_KEY',
});

const { onRequest, messages, isRequesting, abort } = useXChat({
  provider,
  requestPlaceholder: { role: 'assistant', content: '' },
});

The naked token is written as Bearer <token>. Values ​​already starting with Bearer, Basic or Tbox- are unchanged. key is equivalent to dangerouslyApiKey. The optional fetch can be used to replace it with a mock or proxy, the documentation examples use it to avoid putting real keys in the page.

Built-in providers

Class	Behavior
DefaultChatProvider	Almost unchanged requests and responses. transformMessage directly treats chunk as message
OpenAIChatProvider	Parse the choices[].delta.content / message.content of Chat Completions, and end when encountering [DONE]
DeepSeekChatProvider	Same as OpenAI, and additionally reads reasoning_content

Inherit AbstractChatProvider when customizing the protocol and implement:

• transformParams(requestParams, options)
• transformLocalMessage(requestParams)
• transformMessage({ originMessage, chunk, chunks, status, responseHeaders })

The React Toolbox example is connected in this way. There is no Node version of the Tbox SDK in the browser documentation, see Toolbox Playground.

Local presets and examples

All documentation examples use a mock fetch and do not include real keys.

OpenAI preset

OpenAI preset

Add a mock fetch to createOpenAIChatProvider. Typing a sentence will stream the response back via OpenAI SSE.

<script setup lang="tsx">
defineOptions({ name: 'AXSdkPresetV2' });

import { Bubble, Sender } from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { useMockChat } from '../_shared/use-mock-chat';

const chat = useMockChat();

defineRender(() => (
  <Flex vertical gap={12} style={{ height: '420px' }}>
    <div style={{ flex: 1, minHeight: 0 }}>
      <Bubble.List
        style={{ height: '280px' }}
        items={chat.bubbles.value}
        roles={{
          user: { placement: 'end' },
          ai: {
            placement: 'start',
            contentRender: (content: string) => <XMarkdown content={content} />,
          },
        }}
      />
    </div>
    <Sender
      value={chat.input.value}
      loading={chat.isRequesting.value}
      placeholder="Ask the local mock"
      onUpdate:value={(value: string) => { chat.input.value = value; }}
      onSubmit={() => chat.send()}
      onCancel={() => chat.abort()}
    />
  </Flex>
));
</script>

Hide source

DefaultChatProvider

DefaultChatProvider

Customize JSON fetch with almost no change to the request and response format.

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatCustomRequestV2' });

import { computed, ref } from 'vue';
import { Bubble, Sender, DefaultChatProvider, useXChat, XRequest } from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';

interface ChatInput {
  query: string;
}

const sleep = () => new Promise((resolve) => setTimeout(resolve, 1000));

const content = ref('');
const provider = new DefaultChatProvider<string, ChatInput, string>({
  request: XRequest('https://mock.local/chat', {
    manual: true,
    fetch: async (_url, options: any) => {
      await sleep();
      const params = options?.params as ChatInput | undefined;
      return new Response(JSON.stringify([`Mock success return. You said: ${params?.query}`]), {
        headers: { 'Content-Type': 'application/json' },
      });
    },
  }),
});

const { onRequest, messages, isRequesting } = useXChat({
  provider,
  requestPlaceholder: 'Waiting...',
  requestFallback: 'Mock failed return. Please try again later.',
});

const items = computed(() =>
  messages.value.map(({ id, message, status }) => ({
    key: id,
    loading: status === 'loading',
    role: status === 'local' ? 'local' : 'ai',
    content: message,
  })),
);

defineRender(() => (
  <Flex vertical gap="middle">
    <Bubble.List
      style={{ height: 320 }}
      items={items.value}
      roles={{
        ai: { placement: 'start' },
        local: {
          placement: 'end',
          contentRender: (msg: ChatInput | string) =>
            typeof msg === 'string' ? msg : (msg as ChatInput)?.query,
        },
      }}
    />
    <Sender
      loading={isRequesting.value}
      value={content.value}
      onUpdate:value={(v: string) => { content.value = v; }}
      onSubmit={(nextContent: string) => {
        onRequest({ query: nextContent });
        content.value = '';
      }}
    />
  </Flex>
));
</script>

Hide source

OpenAIChatProvider

OpenAIChatProvider

The same local pipeline as above, shown with bubbles and Sender.

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatModelV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  createOpenAIChatProvider,
  useXChat,
  type XModelMessage,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = createOpenAIChatProvider<XModelMessage>({
  baseURL: 'https://mock.local/v1/chat/completions',
  model: 'mock-gpt',
  key: 'docs-preview',
  fetch: createMockOpenAIFetch(),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => <XMarkdown content={content} />,
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Ask the local OpenAI mock"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

Hide source

DeepSeekChatProvider

DeepSeekChatProvider

Additionally read reasoning_content, the Think component displays the reasoning process (locally mocked).

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXChatDeepSeekV2' });

import { computed, ref } from 'vue';
import {
  Bubble,
  Sender,
  Think,
  DeepSeekChatProvider,
  useXChat,
  XRequest,
  type XModelMessage,
  type XModelParams,
} from 'ant-design-x-vue';
import { Flex } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import { createMockDeepSeekFetch } from '../../_shared/mock-chat';

const input = ref('');
const provider = new DeepSeekChatProvider<XModelMessage, XModelParams>({
  request: XRequest('https://mock.local/v1/chat/completions', {
    manual: true,
    fetch: createMockDeepSeekFetch() as never,
    params: { stream: true, model: 'mock-deepseek' },
  }),
});

const { onRequest, messages, isRequesting, abort } = useXChat<XModelMessage>({
  provider,
  requestPlaceholder: { role: 'assistant', content: '' },
  requestFallback: { role: 'assistant', content: 'Mock request failed.' },
});

const items = computed(() =>
  messages.value.map((info) => ({
    key: info.id,
    role: info.message?.role === 'user' ? 'user' : 'ai',
    content: typeof info.message?.content === 'string' ? info.message.content : '',
    loading: info.status === 'loading' && !info.message?.content,
  })),
);

defineRender(() => (
  <Flex vertical gap={12} style={{ height: 420 }}>
    <Bubble.List
      style={{ height: 300 }}
      items={items.value}
      roles={{
        user: { placement: 'end' },
        ai: {
          placement: 'start',
          contentRender: (content: string) => (
            <XMarkdown content={content} components={{ think: Think }} />
          ),
        },
      }}
    />
    <Sender
      value={input.value}
      loading={isRequesting.value}
      placeholder="Ask the local DeepSeek mock"
      onUpdate:value={(v: string) => { input.value = v; }}
      onSubmit={() => {
        const query = input.value.trim();
        if (!query) return;
        input.value = '';
        onRequest({ messages: [{ role: 'user', content: query }], stream: true });
      }}
      onCancel={() => abort()}
    />
  </Flex>
));
</script>

Hide source