XRequest

XRequest(baseURL, options) returns an instance with run, abort and manual. baseURL must be a non-empty string.

When handed to the Provider, manual must be true. Callbacks are written in options.callbacks: onUpdate, onSuccess, onError. run(params) merges these parameters with options.params and sends them out.

Responses are routed by content-type: text/event-stream goes to SSE, application/json goes to JSON. Other types throw unsupported content-type. You can also pass timeout, streamTimeout, middlewares, transformStream, custom separators, failure retries, and a custom fetch. SSE retries include the latest event id in Last-Event-ID.

Basic usage

Request Log

Chunks0

Last -

Basic usage

The button triggers a request. fetch is replaced with local SSE, and the page does not access the external network.

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

import { computed, ref } from 'vue';
import { LoadingOutlined, TagsOutlined } from '@ant-design/icons-vue';
import { Button, Descriptions, Flex } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const BASE_URL = 'https://mock.local';
const PATH = '/get-user-info';

const status = ref<ThoughtChainItemType['status']>();
const lines = ref<Record<string, string>[]>([]);
const busy = ref(false);

function request() {
  busy.value = true;
  status.value = 'loading';
  lines.value = [];
  XRequest(BASE_URL + PATH, {
    fetch: createMockOpenAIFetch(() => 'Hello from XRequest basic.'),
    params: { stream: true, messages: [{ role: 'user', content: 'ping' }] },
    callbacks: {
      onSuccess: () => {
        status.value = 'success';
        busy.value = false;
      },
      onError: () => {
        status.value = 'error';
        busy.value = false;
      },
      onUpdate: (msg) => {
        lines.value = [...lines.value, msg as Record<string, string>];
      },
    },
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Request Log',
    status: status.value,
    icon: status.value === 'loading' ? <LoadingOutlined /> : <TagsOutlined />,
    content: (
      <Descriptions column={1} size="small">
        <Descriptions.Item label="Chunks">{String(lines.value.length)}</Descriptions.Item>
        <Descriptions.Item label="Last">
          <pre style={{ margin: 0, whiteSpace: 'pre-wrap' }}>
            {lines.value.length ? JSON.stringify(lines.value[lines.value.length - 1]) : '-'}
          </pre>
        </Descriptions.Item>
      </Descriptions>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={16} align="flex-start">
    <Button type="primary" disabled={busy.value} onClick={request}>
      Request - {BASE_URL}{PATH}
    </Button>
    <ThoughtChain items={items.value} />
  </Flex>
));
</script>

Hide source

Custom input

Request Log

-

Custom input

Attach custom fields such as agentId in params, still using the local mock.

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

import { computed, ref } from 'vue';
import { LoadingOutlined, TagsOutlined } from '@ant-design/icons-vue';
import { Button, Flex } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const BASE_URL = 'https://mock.local';
const PATH = '/chat';

const status = ref<ThoughtChainItemType['status']>();
const lines = ref<unknown[]>([]);
const busy = ref(false);

function request() {
  busy.value = true;
  status.value = 'loading';
  lines.value = [];
  XRequest(BASE_URL + PATH, {
    fetch: createMockOpenAIFetch(() => 'Custom params mock reply.'),
    params: {
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: 'hello, who are u?' }],
      stream: true,
      agentId: 111,
    },
    callbacks: {
      onSuccess: () => {
        status.value = 'success';
        busy.value = false;
      },
      onError: () => {
        status.value = 'error';
        busy.value = false;
      },
      onUpdate: (msg) => {
        lines.value = [...lines.value, msg];
      },
    },
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Request Log',
    status: status.value,
    icon: status.value === 'loading' ? <LoadingOutlined /> : <TagsOutlined />,
    content: (
      <pre style={{ margin: 0, whiteSpace: 'pre-wrap', overflow: 'auto' }}>
        {lines.value.map((line) => JSON.stringify(line)).join('\n') || '-'}
      </pre>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={16} align="flex-start">
    <Button type="primary" disabled={busy.value} onClick={request}>
      Request with custom params
    </Button>
    <ThoughtChain items={items.value} />
  </Flex>
));
</script>

Hide source

Custom transformer

Custom transformer

transformStream + NDJSON mock sends the original chunks directly into onUpdate.

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

import { computed, ref } from 'vue';
import { TagsOutlined } from '@ant-design/icons-vue';
import { Button, Flex } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';
import { createMockNdjsonFetch } from '../../_shared/mock-chat';

const BASE_URL = 'https://mock.local';
const PATH = '/chat';
const ND_JSON_SEPARATOR = '\n';

const ndJsonData = `{data:{"id":"0","choices":[{"index":0,"delta":{"content":"Hello","role":"assistant"}}],"created":1733129200,"model":"gpt-4o"}}
{data:{"id":"1","choices":[{"index":1,"delta":{"content":"world!","role":"assistant"}}],"created":1733129300,"model":"gpt-4o"}}
{data:{"id":"2","choices":[{"index":2,"delta":{"content":"I","role":"assistant"}}],"created":1733129400,"model":"gpt-4o"}}
{data:{"id":"3","choices":[{"index":3,"delta":{"content":"am","role":"assistant"}}],"created":1733129500,"model":"gpt-4o"}}
{data:{"id":"4","choices":[{"index":4,"delta":{"content":"Ant Design X!","role":"assistant"}}],"created":1733129600,"model":"gpt-4o"}}`;

const status = ref<ThoughtChainItemType['status']>();
const lines = ref<string[]>([]);
const busy = ref(false);

function request() {
  busy.value = true;
  status.value = 'loading';
  lines.value = [];
  XRequest(BASE_URL + PATH, {
    params: {
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: 'hello, who are u?' }],
      stream: true,
      agentId: 111,
    },
    callbacks: {
      onSuccess: () => {
        status.value = 'success';
        busy.value = false;
      },
      onError: () => {
        status.value = 'error';
        busy.value = false;
      },
      onUpdate: (msg) => {
        lines.value = [...lines.value, String(msg)];
      },
    },
    transformStream: new TransformStream<string, string>({
      transform(chunk, controller) {
        controller.enqueue(chunk);
      },
    }),
    fetch: createMockNdjsonFetch(ndJsonData.split(ND_JSON_SEPARATOR)),
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Mock Custom Protocol - Log',
    status: status.value,
    icon: <TagsOutlined />,
    content: (
      <pre style={{ overflow: 'auto', margin: 0 }}>
        <code>{lines.value.join(ND_JSON_SEPARATOR)}</code>
      </pre>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={16} align="flex-start">
    <Button type="primary" disabled={busy.value} onClick={request}>
      Request - {BASE_URL}{PATH}
    </Button>
    <ThoughtChain items={status.value ? items.value : []} />
  </Flex>
));
</script>

Hide source

Model integration

hello, who are u?

Model Request Log

idle

-

Model integration

Manual mode with an input box. A mock OpenAI SSE stream can be aborted.

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

import { computed, ref } from 'vue';
import { LoadingOutlined, TagsOutlined } from '@ant-design/icons-vue';
import { Button, Flex, Input } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const MODEL = 'mock-gpt';
const questionText = ref('hello, who are u?');
const status = ref('');
const thoughtChainStatus = ref<ThoughtChainItemType['status']>();
const lines = ref<unknown[]>([]);
const requestHandler = XRequest('https://mock.local/v1/chat/completions', {
  manual: true,
  fetch: createMockOpenAIFetch((text) => `Mock model reply for: ${text || questionText.value}`),
  params: { model: MODEL, stream: true },
  callbacks: {
    onSuccess: () => {
      status.value = 'success';
      thoughtChainStatus.value = 'success';
    },
    onError: (error) => {
      status.value = error.message;
      thoughtChainStatus.value = 'error';
    },
    onUpdate: (msg) => {
      lines.value = [...lines.value, msg];
    },
  },
});

function request() {
  status.value = 'pending';
  thoughtChainStatus.value = 'loading';
  lines.value = [];
  requestHandler.run({
    messages: [{ role: 'user', content: questionText.value }],
    stream: true,
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Model Request Log',
    status: thoughtChainStatus.value,
    icon: status.value === 'pending' ? <LoadingOutlined /> : <TagsOutlined />,
    description: status.value || 'idle',
    content: (
      <pre style={{ margin: 0, whiteSpace: 'pre-wrap', overflow: 'auto', maxHeight: 180 }}>
        {lines.value.map((line) => JSON.stringify(line)).join('\n') || '-'}
      </pre>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={12} align="flex-start" style={{ width: '100%' }}>
    <Input.TextArea
      value={questionText.value}
      autoSize={{ minRows: 2, maxRows: 4 }}
      onUpdate:value={(v: string) => { questionText.value = v; }}
      style={{ width: '100%' }}
    />
    <Flex gap={8}>
      <Button type="primary" disabled={status.value === 'pending'} onClick={request}>
        Run model request
      </Button>
      <Button onClick={() => requestHandler.abort()}>Abort</Button>
    </Flex>
    <ThoughtChain items={items.value} />
  </Flex>
));
</script>

Hide source

Timeout

Request Log

request -

Status-

timeout2000ms (mock arrives at 3000ms)

Timeout

timeout: 2000, the mock returns in 3000ms, triggering TimeoutError.

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

import { computed, ref } from 'vue';
import { LoadingOutlined, TagsOutlined } from '@ant-design/icons-vue';
import { Button, Descriptions, Flex } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';

const BASE_URL = 'https://mock.local';
const PATH = '/chat';

async function mockFetch() {
  return new Promise<Response>((resolve) => {
    setTimeout(() => {
      resolve(
        new Response('{ "data": "Hi" }', {
          status: 200,
          headers: { 'Content-Type': 'application/json' },
        }),
      );
    }, 3000);
  });
}

const status = ref('');
const thoughtChainStatus = ref<ThoughtChainItemType['status']>();

function request() {
  status.value = 'pending';
  thoughtChainStatus.value = 'loading';
  XRequest(BASE_URL + PATH, {
    timeout: 2000,
    fetch: mockFetch,
    callbacks: {
      onSuccess: () => {
        status.value = 'success';
        thoughtChainStatus.value = 'success';
      },
      onError: (error) => {
        status.value = error.message === 'TimeoutError' ? 'TimeoutError' : error.message;
        thoughtChainStatus.value = 'error';
      },
    },
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Request Log',
    status: thoughtChainStatus.value,
    icon: status.value === 'pending' ? <LoadingOutlined /> : <TagsOutlined />,
    description: `request ${status.value || '-'}`,
    content: (
      <Descriptions column={1} size="small">
        <Descriptions.Item label="Status">{status.value || '-'}</Descriptions.Item>
        <Descriptions.Item label="timeout">2000ms (mock arrives at 3000ms)</Descriptions.Item>
      </Descriptions>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={16} align="flex-start">
    <Button type="primary" disabled={status.value === 'pending'} onClick={request}>
      Request - {BASE_URL}{PATH}
    </Button>
    <ThoughtChain items={items.value} />
  </Flex>
));
</script>

Hide source

API

XRequestFunction

type XRequestFunction<Input = AnyObject, Output = SSEOutput> = (
  baseURL: string,
  options?: XRequestOptions<Input, Output>,
) => XRequestClass<Input, Output>;

Prop	Description	Type	Default	Version
baseURL	API address	string	-	-
options	Request configuration	XRequestOptions<Input, Output>	-	-

XRequestOptions

Prop	Description	Type	Default	Version
callbacks	Request callbacks	XRequestCallbacks<Output>	-	-
params	Request parameters	Input	-	-
headers	Additional request headers	Record<string, string>	-	-
timeout	Request timeout (milliseconds)	number	-	-
streamTimeout	Stream data timeout (milliseconds)	number	-	-
fetch	Custom fetch	(baseURL, options) => Promise<Response>	-	-
middlewares	Pre- and post-request middleware	XFetchMiddlewares<Input, Output>	-	-
transformStream	Stream processor	XStreamOptions<Output>['transformStream']	((baseURL: string, responseHeaders: Headers) => XStreamOptions<Output>['transformStream'])	-
streamSeparator	Stream event separator; ignored when transformStream is set	string	\n\n	2.2.0
partSeparator	Field separator inside one event; ignored when transformStream is set	string	\n	2.2.0
kvSeparator	Separator between field names and values; ignored when transformStream is set	string	:	2.2.0
manual	Whether to send the request manually; if true, run must be called	boolean	false	-
retryInterval	Retry interval after a failure, in milliseconds; disabled when omitted	number	-	-
retryTimes	Maximum retry count	number	-	-

XRequestCallbacks

Prop	Description	Type	Default	Version
onSuccess	Success callback; receives the assembled message when used with a Chat Provider	(chunks: Output[], responseHeaders: Headers, message?: MessageInfo<ChatMessage>) => void	-	-
onError	Error callback; return a number to override the retry interval for this failure. With a Chat Provider it also receives the fallback message	(error: Error, errorInfo?: any, responseHeaders?: Headers, fallbackMsg?: MessageInfo<ChatMessage>) => number | void	-	-
onUpdate	Chunk update callback; receives the assembled message when used with a Chat Provider	(chunk: Output, responseHeaders: Headers, message?: MessageInfo<ChatMessage>) => void	-	-

XRequestClass

Prop	Description	Type	Default	Version
abort	Cancel request	() => void	-	-
run	Manually execute request (effective when manual=true)	(params?: Input) => void	-	-
isRequesting	Whether the request is in progress	boolean	-	-
manual	Whether it is manual mode	boolean	-	-

setXRequestGlobalOptions

type setXRequestGlobalOptions<Input, Output> = (
  options: XRequestGlobalOptions<Input, Output>,
) => void;

XRequestGlobalOptions

type XRequestGlobalOptions<Input, Output> = Pick<
  XRequestOptions<Input, Output>,
  'headers' | 'timeout' | 'streamTimeout' | 'middlewares' | 'fetch' | 'transformStream' | 'manual'
>;

XFetchMiddlewares

interface XFetchMiddlewares<Input, Output> {
  onRequest?: (
    ...args: [Parameters<typeof fetch>[0], XRequestOptions<Input, Output>]
  ) => Promise<[Parameters<typeof fetch>[0], XRequestOptions<Input, Output>]>;
  onResponse?: (response: Response) => Promise<Response>;
}

The new XRequest({ baseURL, model, dangerouslyApiKey }).create in 1.x is now called XRequestLegacy, documentation at XRequest Request.