How it works

Overview

Generative UI puts model output directly in front of users, and raw model output is not reliable enough for that. OpenUI Cloud sits between the application and the model. It can act as a compatible model gateway or assemble and validate renderable OpenUI Lang for generative UI.

OpenUI Cloud exposes four API surfaces, summarized in the API overview:

• Responses API: The recommended generation endpoint for new agent applications. It accepts a conversation turn and streams validated UI as OpenUI Lang, with persistent conversations, hosted tools, and slide and report generation in the same API.
• Chat Completions (Embed): A drop-in endpoint for applications that already use the OpenAI Chat Completions message format. It supports plain text passthrough, self-hosted or managed generative UI, and application-run function tools.
• Chat Completions (Artifacts): A standalone endpoint for generating and explicitly editing slide and report programs.
• Conversations API: Provides read and write access to stored conversation threads and items. The browser calls it directly using short-lived frontend tokens.

The generation APIs integrate with AgentInterface through their matching stream adapters, while the Conversations API and artifact storage endpoints supply thread history and stored artifacts. Applications with their own UI consume the same OpenUI Lang stream with the open-source renderer.

Rendering stays in the browser: responses render client-side with the application's component library, exactly as in open-source OpenUI.

The application consists of product code, AgentInterface or a custom UI, and a backend route that holds the API key. OpenUI Cloud runs model routing, managed output validation, artifact generation, and storage.

Responses request lifecycle

1. The user sends a message. AgentInterface posts it to the application backend.
2. The backend makes one Responses API call for the new turn. The call names the model to use and references the server-side conversation, so the backend sends only the new message. Cloud supplies the earlier turns.
3. Cloud routes the request to that model. If the model or provider is unavailable, the request reroutes to a fallback.
4. Model output is validated and corrected before it leaves Cloud.
5. The response streams back through the backend to the browser, and the interface renders progressively as it arrives.
6. The turn's messages, actions, and outputs persist to the conversation. Actions include user interactions with generated components, such as button clicks and form submissions.

Chat Completions request lifecycle

Chat Completions uses the application's existing messages array. The application sends the relevant conversation history, OpenUI Cloud routes the request to the selected provider model, and the endpoint returns either text or OpenUI Lang in the standard Chat Completions response shape.

Plain passthrough requests receive no injected generative UI prompt. For managed generative UI, a server helper places an OpenUI configuration sentinel in the system message so Cloud can assemble the prompt and validate the generated program. Function tools are returned to the application for execution; hosted search and MCP tools remain on the Responses API.

Standalone slides and reports use Chat Completions for artifacts. The application sends artifact metadata with a prompt and receives a raw OpenUI Lang artifact program. Editing sends the current program back as an assistant message with is_edit: true.

Output validation

Each managed generative UI and artifact response is checked against the component library it was generated for. By default, that is OpenUI Cloud's pre-tested, responsive, and accessible component library. An application can instead register its own component library, including its component schema, generated prompt, and custom components. Invalid output, including malformed structures, unknown components, and unrenderable content, is corrected in the streaming path before it reaches the client. Differences between model providers and versions are normalized at the same stage, so rendered behavior stays consistent when the underlying model changes.

Plain text passthrough and self-hosted generative UI prompts do not use managed validation; the application owns validation in those modes.

Artifact generation

With the Responses API, a request declares which artifact types are allowed and the model produces them inside the same stream as the conversation. Slides and reports are stored and versioned automatically, and follow-up turns can edit them.

With Chat Completions, the dedicated artifact endpoint returns a raw OpenUI Lang program. The application supplies the current program explicitly when requesting an edit. Both APIs use the same managed presentation and report viewers. Slides can be exported to PowerPoint, and reports can be exported to PDF.

Conversation persistence

Responses API conversations can be stored server-side. Each turn's messages, actions, and outputs attach to a conversation thread, and generation calls reference the thread instead of resending its history. The application backend stores no chat history and runs no database. On load, AgentInterface reads threads from the Conversations API and artifacts from the storage plane.

Chat Completions applications own their message history and resend the relevant messages on each turn. Choose the Responses API when Cloud-managed conversation persistence is required.

Authentication

Two credentials with different scopes:

• API key: Authorizes generation calls and frontend-token minting. It is held by the application backend and is never sent to the browser.
• Frontend tokens: Short-lived tokens that the application backend requests from Cloud and returns to the browser. The browser uses them to read conversations and artifacts without the backend proxying each read. Tokens expire within minutes, and AgentInterface requests a fresh token from the backend before expiry.