Event Source | AIUI | Rokid

In AIUI, EventSource is suitable for communication patterns where the server continuously pushes incremental content to the frontend in a one-way stream.

Event Source

In AIUI, EventSource is suitable for communication patterns where the server continuously pushes incremental content to the frontend in a one-way stream.

If you already have a server interface that needs to continuously output a text stream, status stream, or task progress, prefer EventSource instead of switching to WebSocket just for streaming output.

Event Source Example

Web

const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  console.log('Received incremental content:', event.data);
};

eventSource.onerror = () => {
  console.error('Event Source connection error');
  eventSource.close();
};

wx

const eventSource = wx.createEventSource({
  url: '/api/agent/stream',
});

eventSource.onMessage(({ data }) => {
  console.log('Incremental content received:', data);
});

eventSource.onError((error) => {
  console.error('Event Source connection error', error);
  eventSource.close();
});

When to Use Event Source

  • The server continuously pushes text deltas
  • Task execution progress needs to be displayed
  • Only one-way server-to-client pushing is needed, without continuous reverse messages from the client
  • You want to keep an HTTP-like integration model while still getting a streaming experience

Event Source Recommendations

  • When the server is only responsible for continuous pushing, prefer EventSource.
  • Design each pushed message as an independently consumable fragment, such as text deltas, phase states, or progress updates.
  • Clearly distinguish UI states such as "connected", "streaming", "completed", and "interrupted".
  • Close the instance promptly after the connection ends to avoid continuing to occupy resources after page switches.

When Not to Use Event Source

  • When you only need one complete result
  • When you are only calling ordinary APIs
  • When the client needs to keep sending real-time messages to the server

If you only need one request and one response, use HTTPS. If you need bidirectional real-time communication, use WebSocket instead.

Read Next

  • HTTPS: Learn how to handle ordinary request-response scenarios.
  • WebSocket: Learn how to design and manage bidirectional real-time long connections.
  • WeChat Mini Program Compatible APIs: See the wx APIs supported by AIUI.

API Reference

new EventSource(url)

Creates a Web-standard SSE client that connects to the required url with a GET request.

EventSource Events and Methods

  • onopen: Called when the connection opens.
  • onmessage: Called for default message events; data contains the payload.
  • onerror: Called when a connection error occurs.
  • close(): Closes the connection.

wx APIs

wx.createEventSource(options)

ParameterTypeRequiredDescription
options.urlstringYesSSE service URL.
options.methodstringNoHTTP method. Defaults to GET.
options.headerobjectNoRequest headers.
options.data / options.bodystring | object | ArrayBufferNoRequest body.

Returns: EventSourceTask.

EventSourceTask

  • onOpen(callback): Observes the connection-open event.
  • onMessage(callback): Observes messages with { data, event, id }.
  • onError(callback): Observes errors with { errMsg }.
  • close(): Closes the connection.

All methods return undefined.