A2UI | AIUI | Rokid

Use a2ui to turn structured instructions generated by an AI agent into a visible interface. It is useful when the agent decides the UI at runtime, such as generating a re…

A2UI

Use a2ui to turn structured instructions generated by an AI agent into a visible interface. It is useful when the agent decides the UI at runtime, such as generating a result card, list, or chart for a user's request.

If the interface structure is fixed, regular components such as view and text are simpler.

Display an Initial Interface

Give the component a unique id, then pass A2UI instructions through commands. The component processes commands only once, during its initial render.

<a2ui id="answer" commands="{{initialCommands}}"></a2ui>
export default {
  data: {
    initialCommands: JSON.stringify([
      {
        version: 'v0.9',
        createSurface: { surfaceId: 'main' }
      },
      {
        version: 'v0.9',
        updateComponents: {
          surfaceId: 'main',
          components: [
            { id: 'title', component: 'Text', text: 'Today: sunny' }
          ]
        }
      }
    ])
  }
};

commands accepts a string, so use JSON.stringify() to convert the command array to JSON text.

Update the Displayed Interface

When a new AI result arrives, create a context using the component's id, then call write():

const context = a2ui.createA2UIContext('answer');

if (context) {
  context.write(JSON.stringify([
    {
      version: 'v0.9',
      updateComponents: {
        surfaceId: 'main',
        components: [
          { id: 'title', component: 'Text', text: 'Today: cloudy' }
        ]
      }
    }
  ]));
}

createA2UIContext() returns null when the id cannot be found, so check the result before using it.

Receive AI Output in Chunks

If the AI response arrives progressively, create a writer and pass each string chunk to it. Always call close() at the end so the component can finish processing the remaining content.

const context = a2ui.createA2UIContext('answer');

if (context) {
  const writer = context.startStream();
  writer.writeChunk('{"version":"v0.9","createSurface":');
  writer.writeChunk('{"surfaceId":"stream-result"}}');
  writer.close();
}

Call context.clear() when the generated interface should be removed.

Properties

PropertyTypeDefaultDescription
idString-Component identifier used by a2ui.createA2UIContext(). Required for dynamic updates.
commandsString-A2UI JSON instructions processed once during the initial render.
default-chart-animateBooleantrueWhether charts created by A2UI animate by default when the instruction does not specify animation. defaultChartAnimate is also accepted.

JavaScript Methods

MethodDescription
a2ui.createA2UIContext(id)Returns the context for a component id, or null when it cannot be found.
context.write(data)Updates the interface using a complete JSON string.
context.startStream()Starts a chunked update and returns a writer.
writer.writeChunk(chunk)Writes one string chunk.
writer.close()Finishes the current chunked update.
context.clear()Clears the generated interface.

a2ui does not provide agent-id, session-id, or bindmessage. Manage the agent session and incoming messages in the page or an Agent Worker, then pass the resulting A2UI instructions to this component.

Tint and Fit Generated Images

A2UI Image / image props map to the native Image attributes below:

A2UI propNative attributeBehavior
tintColortint-colorColor string or data binding; explicit tint-color wins when both spellings occur.
fit: 'contain'mode="aspectFit"Shows the entire image at its original aspect ratio.
fit: 'cover'mode="aspectFill"Fills the region, cropping as needed.
fit: 'fill'mode="scaleToFill"Stretches to fill the region.
modemodeExplicit mode takes precedence over fit.

See Image for alpha multiplication and SVG theme tint. Updates preserve same-type image components and reuse template items by position, avoiding unnecessary image reloads and preserving playback. Changing the component type recreates it.