diff --git a/docs/content/docs/openui-cloud/api/artifacts.mdx b/docs/content/docs/openui-cloud/api/artifacts.mdx new file mode 100644 index 000000000..29e61b031 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/artifacts.mdx @@ -0,0 +1,76 @@ +--- +title: Chat Completions (Artifacts) +description: "Generate and edit standalone OpenUI Cloud presentations and reports with a Chat Completions-compatible endpoint." +--- + +The Artifact Chat Completions API generates a standalone slide deck or report as an OpenUI Lang program. Use it when the artifact lifecycle is separate from an agent's Responses stream. + +**Endpoint:** `POST https://api.thesys.dev/v1/artifact/chat/completions` + +Use the `artifactClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration. + +## Generate an artifact + +Every request includes `metadata.thesys` as a JSON string with your artifact `id` and a `c1_artifact_type` of `"slides"` or `"report"`. + +```ts +const artifact = await artifactClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [{ role: "user", content: "Create a three-slide deck on Q4 results." }], + metadata: { + thesys: JSON.stringify({ + id: "art_1", + c1_artifact_type: "slides", + }), + }, +}); + +const program = artifact.choices[0].message.content; +``` + +The response content is a raw OpenUI Lang program rooted at `SlideShow` or `ReportView`. OpenUI Cloud validates and repairs it before returning it. Set `stream: true` to receive the program progressively. + +## Render an artifact + +Render the returned program with the matching managed viewer: + +```tsx +import { Presentation, Report } from "@openuidev/thesys"; +import "@openuidev/thesys/styles.css"; + +export function Artifact({ kind, program }: { kind: "slides" | "report"; program: string }) { + return kind === "slides" ? ( + + ) : ( + + ); +} +``` + +Pass `isStreaming` while accumulating a streamed program. + +## Edit an artifact + +Send the current OpenUI Lang program as an assistant message, describe the change in the next user message, and set `is_edit: true`. + +```ts +const edited = await artifactClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { role: "assistant", content: previousProgram }, + { role: "user", content: "Make slide 2 about European revenue." }, + ], + metadata: { + thesys: JSON.stringify({ + id: "art_1", + c1_artifact_type: "slides", + is_edit: true, + }), + }, + stream: true, +}); +``` + +The response is a patch-mode OpenUI Lang program merged against the assistant-message base. + +Use the [Responses API](/docs/openui-cloud/api/responses#generate-slides-and-reports) instead when artifacts should be stored, opened, and edited as part of a persistent agent conversation. diff --git a/docs/content/docs/openui-cloud/api/chat-completions.mdx b/docs/content/docs/openui-cloud/api/chat-completions.mdx new file mode 100644 index 000000000..82648e619 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/chat-completions.mdx @@ -0,0 +1,129 @@ +--- +title: Chat Completions (Embed) +description: "Use the OpenAI-compatible embed endpoint for text, managed or self-hosted generative UI, and function tools." +--- + +The Embed Chat Completions API is a drop-in endpoint for applications that already use `chat.completions.create()`. It preserves the standard message format and supports text or OpenUI Lang responses. + +**Endpoint:** `POST https://api.thesys.dev/v1/embed/chat/completions` + +Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration. + +## Make a managed UI request + +Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library. + +```ts title="server.ts" +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const completion = await embedClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { role: "system", content: generateSystemPrompt() }, + { role: "user", content: "Compare quarterly revenue by region." }, + ], +}); + +console.log(completion.choices[0].message.content); +``` + +The returned message content is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and custom component workflow. + +## Stream and render responses + +Set `stream: true` on the server. In the browser, pair the Chat Completions stream adapter with the OpenAI message format: + +```tsx title="cloud-chat.tsx" +"use client"; + +import { AgentInterface, fetchLLM, openAIAdapter, openAIMessageFormat } from "@openuidev/react-ui"; +import { chatLibrary } from "@openuidev/thesys"; +import "@openuidev/thesys/styles.css"; + +const llm = fetchLLM({ + url: "/api/chat", + streamAdapter: openAIAdapter(), + messageFormat: openAIMessageFormat, +}); + +export function Chat() { + return ; +} +``` + +Use `openAIAdapter()` when your route preserves the raw `data:` SSE response. If it returns the OpenAI SDK stream through `.toReadableStream()` instead, use `openAIReadableStreamAdapter()`. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats) for the exact pairings. + +## Manage conversation history + +Chat Completions is message-based. Keep the conversation in your application and include the system message plus the relevant `user`, `assistant`, and `tool` messages on every turn. + +The [Conversations API](/docs/openui-cloud/api/conversations) integrates with Responses, not Embed Chat Completions. Choose Responses when you want Cloud-managed persistent history. + +## Use function tools + +Embed Chat Completions accepts `function` tools only and does not execute them. Run the standard loop in your application: + +1. Send the messages and function declarations. +2. Read `tool_calls` from the assistant message. +3. Execute each function in your application. +4. Append the assistant tool-call message and each `role: "tool"` result. +5. Repeat until the model returns a final response. + +Hosted `web_search`, `image_search`, remote MCP, and artifacts-as-tool are available on the [Responses API](/docs/openui-cloud/api/responses#use-tools). For standalone slides or reports, use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts). + +## Use other generation modes + +### Plain text passthrough + +Use a `{provider}/{model}` model ID without the managed `generateSystemPrompt()` sentinel. OpenUI Cloud forwards your messages and system prompt without injecting a generative UI prompt or component schema. + +```ts +const completion = await embedClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { role: "system", content: "You are a concise product analyst." }, + { role: "user", content: "Summarize the risks in this launch plan." }, + ], +}); + +console.log(completion.choices[0].message.content); +``` + +OpenAI, Anthropic, and Google model IDs route to those providers. Unknown providers route through OpenRouter. + +### Self-hosted generative UI + +Compile the complete system prompt in your application from a generated OpenUI library spec. The endpoint forwards that prompt verbatim; the model returns OpenUI Lang for your client-side renderer. + +```ts +import { generateSystemPrompt } from "@openuidev/lang-core"; +import library from "./generated/library.spec.json"; + +const completion = await embedClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + library, + promptOptions, + }), + }, + ...messages, + ], + stream: true, +}); +``` + +In this mode, prompt assembly, output validation, and rendering are owned by your application. + +### Request-level provider key + +For a request-level self-hosted key flow, encrypt the provider key with `POST /encryption/encrypt`, then include this object in the request body: + +```ts +byok: { + provider, + encryptedApiKey, +} +``` diff --git a/docs/content/docs/openui-cloud/api/conversations.mdx b/docs/content/docs/openui-cloud/api/conversations.mdx new file mode 100644 index 000000000..ca11c1465 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/conversations.mdx @@ -0,0 +1,93 @@ +--- +title: Conversations API +description: "Create persistent OpenUI Cloud conversations, inspect their items, and connect them to Responses and Agent Interface." +--- + +The Conversations API stores persistent threads and their items. Responses can read and append to a conversation, while `AgentInterface` uses the same API to list threads and reload messages. + +**Base URL:** `https://api.thesys.dev/v1` + +Use the `conversationClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication and the shared OpenAI SDK clients. + + + Conversations integrate with the Responses API. Embed Chat Completions applications own and resend + their own `messages` history. + + +## Create a conversation + +Create the conversation before the first stored response: + +```ts +const conversation = await conversationClient.conversations.create({ + metadata: { workspace: "acme" }, +}); +``` + +Then send only the new turn to Responses and set `store: true`: + +```ts +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const response = await embedClient.responses.create({ + model: "openai/gpt-5", + conversation: conversation.id, + input: "Compare quarterly revenue by region.", + instructions: generateSystemPrompt(), + store: true, + stream: true, +}); +``` + +Every later response with the same `conversation` ID can use the stored context without resending the full history. + +## Read conversation items + +List the messages, tool calls, and tool outputs stored in a conversation: + +```ts +const page = await conversationClient.conversations.items.list(conversation.id, { + order: "asc", + limit: 100, +}); + +for (const item of page.data) { + console.log(item.type, item.id); +} +``` + +The OpenAI SDK also exposes `retrieve`, `update`, and `delete` for conversations, and create, retrieve, list, and delete operations for conversation items. + +## Endpoint summary + +| Method | Path | Purpose | +| ------------------------- | ----------------------------------------------------- | ------------------------------------------- | +| `GET` / `POST` | `/v1/conversations` | List or create conversations. | +| `GET` / `POST` / `DELETE` | `/v1/conversations/{conversation_id}` | Retrieve, update, or delete a conversation. | +| `GET` / `POST` | `/v1/conversations/{conversation_id}/items` | List or add conversation items. | +| `GET` / `DELETE` | `/v1/conversations/{conversation_id}/items/{item_id}` | Retrieve or delete one item. | + +Server-side requests authenticate with the API key described in the [API overview](/docs/openui-cloud/api/overview#authenticate). + +## Connect Agent Interface + +In the browser, use `useOpenuiCloudStorage()` instead of calling the raw endpoints. It lists conversations, loads their items, and persists artifact state for `AgentInterface`. + +```tsx +import { AgentInterface } from "@openuidev/react-ui"; +import { useOpenuiCloudStorage } from "@openuidev/thesys"; + +export function Chat() { + const storage = useOpenuiCloudStorage({ + token: "/api/frontend-token", + apiBaseUrl: "https://api.thesys.dev", + features: { artifact: true }, + }); + + return ; +} +``` + +The `/api/frontend-token` server route mints a short-lived token with `POST /v1/frontend-tokens`, binding it to your authenticated `user_id` and optional `app_id`. The browser sends that token as `x-thesys-frontend-token`; the server API key never leaves your backend. + +Use the current [frontend-token route](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/app/api/frontend-token/route.ts) and [Cloud storage setup](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/components/cloud-chat.tsx) as complete references. diff --git a/docs/content/docs/openui-cloud/api/overview.mdx b/docs/content/docs/openui-cloud/api/overview.mdx new file mode 100644 index 000000000..655ee4ae5 --- /dev/null +++ b/docs/content/docs/openui-cloud/api/overview.mdx @@ -0,0 +1,71 @@ +--- +title: API Overview +description: "Choose an OpenUI Cloud API and configure the shared authentication, clients, models, and persistence behavior." +--- + +OpenUI Cloud exposes four related API surfaces. Choose the generation shape and state model that fit your application, then use the focused API guide for implementation details. + +## Choose an API + +| API | Endpoint | Use it for | +| ------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | +| [Responses](/docs/openui-cloud/api/responses) | `POST /v1/embed/responses` | New agent applications, hosted tools, persistent conversations, and artifacts inside the agent stream. | +| [Chat Completions (Embed)](/docs/openui-cloud/api/chat-completions) | `POST /v1/embed/chat/completions` | Existing Chat Completions applications, plain text, managed or self-hosted generative UI, and app-run function tools. | +| [Chat Completions (Artifacts)](/docs/openui-cloud/api/artifacts) | `POST /v1/artifact/chat/completions` | Standalone slide or report generation and explicit program-based edits. | +| [Conversations](/docs/openui-cloud/api/conversations) | `/v1/conversations` | Persistent Responses threads, items, and the storage plane used by `AgentInterface`. | + +Responses is the recommended starting point for new agent applications. The two Chat Completions endpoints let existing integrations keep their message format, while Conversations provides persistent state for Responses. + +## Authenticate + +Create an API key in the [Thesys console](https://console.thesys.dev/keys) and configure `THESYS_API_KEY` on your server. Server-side requests use: + +```http +Authorization: Bearer $THESYS_API_KEY +``` + +Never expose this key to browser code. Browser access to conversations and artifacts uses a scoped, short-lived frontend token instead; see the [Conversations API](/docs/openui-cloud/api/conversations#connect-agent-interface). + +## Configure the clients + +The generation endpoints and core Conversations operations are compatible with the stock OpenAI SDK. Use a client for each base URL your application needs: + +```ts title="lib/openui-cloud.ts" +import OpenAI from "openai"; + +const common = { apiKey: process.env.THESYS_API_KEY }; + +export const embedClient = new OpenAI({ + ...common, + baseURL: "https://api.thesys.dev/v1/embed", +}); + +export const artifactClient = new OpenAI({ + ...common, + baseURL: "https://api.thesys.dev/v1/artifact", +}); + +export const conversationClient = new OpenAI({ + ...common, + baseURL: "https://api.thesys.dev/v1", +}); +``` + +The Embed and Artifact generation endpoints support streaming and non-streaming requests. + +## Choose a state model + +| Flow | Where history lives | +| ----------------------------------------------- | ------------------------------------------------------------------- | +| Responses with `conversation` and `store: true` | OpenUI Cloud stores the persistent conversation and response items. | +| Responses with `previous_response_id` | OpenUI Cloud chains stored responses without a named conversation. | +| Responses with full `input` history | Your application stores and resends history. | +| Embed Chat Completions | Your application stores and resends the `messages` array. | +| Artifact Chat Completions | Each edit request includes the current artifact program explicitly. | + +## Shared configuration + +- Use `{provider}/{model}` model IDs across generation endpoints. See [Models and BYOK](/docs/openui-cloud/models-and-byok) for supported models and provider credentials. +- Use the built-in chat library or provide your own components. See [Component Library](/docs/openui-cloud/build/component-library). +- Keep generation behind a server route and match the browser adapter to the selected response protocol. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats). +- For the relationship between generation, storage, and rendering, see [How it works](/docs/openui-cloud/how-it-works). diff --git a/docs/content/docs/openui-cloud/api/responses.mdx b/docs/content/docs/openui-cloud/api/responses.mdx new file mode 100644 index 000000000..6cfa9025b --- /dev/null +++ b/docs/content/docs/openui-cloud/api/responses.mdx @@ -0,0 +1,148 @@ +--- +title: Responses API +description: "Generate managed UI with persistent conversations, hosted tools, and artifacts in the agent stream." +--- + +The Responses API is the recommended generation endpoint for new OpenUI Cloud agent applications. + +**Endpoint:** `POST https://api.thesys.dev/v1/embed/responses` + +Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview), which covers authentication, base URLs, models, and shared configuration. + +## Make a request + +Use the server helper to have OpenUI Cloud assemble the system prompt for its built-in component library. + +```ts title="server.ts" +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const response = await embedClient.responses.create({ + model: "openai/gpt-5", + input: "Compare quarterly revenue by region.", + instructions: generateSystemPrompt(), +}); + +console.log(response.output_text); +``` + +The returned `output_text` is an OpenUI Lang program. See [Component Library](/docs/openui-cloud/build/component-library) for the built-in client library and custom component workflow. + +## Stream and render responses + +Set `stream: true` on the server. In the browser, pair the Responses stream adapter with the conversation message format: + +```tsx title="cloud-chat.tsx" +"use client"; + +import { + AgentInterface, + fetchLLM, + openAIConversationMessageFormat, + openAIResponsesAdapter, +} from "@openuidev/react-ui"; +import { chatLibrary } from "@openuidev/thesys"; +import "@openuidev/thesys/styles.css"; + +const llm = fetchLLM({ + url: "/api/chat", + streamAdapter: openAIResponsesAdapter(), + messageFormat: openAIConversationMessageFormat, +}); + +export function Chat() { + return ; +} +``` + +Your `/api/chat` route should forward the OpenUI Cloud response stream without changing its event shape. See [Adapters and message formats](/docs/agent/reference/adapters-and-formats) for lower-level transport details. + +## Manage conversation history + +The Responses API supports three history patterns: + +| Pattern | Use it when | +| -------------------------------- | --------------------------------------------------------------------------------- | +| Send the full history in `input` | Your application owns all message storage. | +| Set `previous_response_id` | You want to chain turns without a named conversation. Use `store: true`. | +| Set `conversation` | You want a persistent thread managed by the Conversations API. Use `store: true`. | + +Chain a follow-up to an earlier response: + +```ts +const first = await embedClient.responses.create({ + model: "openai/gpt-5", + input: "Compare quarterly revenue by region.", + instructions: generateSystemPrompt(), + store: true, +}); + +const followUp = await embedClient.responses.create({ + model: "openai/gpt-5", + input: "Focus on Europe and explain the change.", + instructions: generateSystemPrompt(), + previous_response_id: first.id, + store: true, +}); +``` + +For persistent named threads, see the [Conversations API](/docs/openui-cloud/api/conversations). + +## Use tools + +OpenUI Cloud runs hosted tools inside the platform. App-owned function tools still run on your server. + +| Capability | Tool declaration | Runs on | +| -------------------- | --------------------------------------------------- | ------------ | +| Slides and reports | `artifactTool({ artifacts: ["slides", "report"] })` | OpenUI Cloud | +| Web search | `{ type: "web_search" }` | OpenUI Cloud | +| Image search | `{ type: "image_search" }` | OpenUI Cloud | +| Remote MCP server | `{ type: "mcp", server_label, server_url }` | OpenUI Cloud | +| Application function | `{ type: "function", name, parameters }` | Your server | + +```ts +import type { Tool } from "openai/resources/responses/responses"; + +const response = await embedClient.responses.create({ + model: "openai/gpt-5", + input: "Research the market and summarize the most important changes.", + instructions: generateSystemPrompt(), + tools: [ + { type: "web_search" }, + { type: "image_search" } as unknown as Tool, + { + type: "mcp", + server_label: "deepwiki", + server_url: "https://mcp.deepwiki.com/mcp", + } as unknown as Tool, + ], + stream: true, + store: true, +}); +``` + +The casts are needed because image search and MCP are OpenUI Cloud extensions to the stock OpenAI tool union. + +For a `function` tool, execute each returned `function_call` on your server and continue with a `function_call_output`. The OpenUI Cloud scaffold includes a complete tool loop; see [Tools](/docs/agent/core-concepts/tools) for the execution model. + +## Generate slides and reports + +Add `artifactTool()` to generate editable slides or reports inside the agent stream: + +```ts +import { artifactTool, generateSystemPrompt } from "@openuidev/thesys-server"; +import type { Tool } from "openai/resources/responses/responses"; + +const response = await embedClient.responses.create({ + model: "openai/gpt-5", + conversation: threadId, + input: "Create a three-slide deck on Q4 results.", + instructions: generateSystemPrompt(), + tools: [artifactTool({ artifacts: ["slides", "report"] }) as unknown as Tool], + store: true, + stream: true, +}); +``` + +Artifacts are stored separately from chat messages. Register `presentationArtifactRenderer`, `reportArtifactRenderer`, and `useOpenuiCloudStorage()` with `AgentInterface` to render and persist them. The [OpenUI Cloud scaffold](https://github.com/thesysdev/openui/blob/main/packages/openui-cli/src/templates/openui-cloud/src/components/cloud-chat.tsx) contains the complete client setup. + +Follow-up requests in the same stored conversation edit the existing artifact automatically. Use [Chat Completions for artifacts](/docs/openui-cloud/api/artifacts) when you need standalone generation or explicitly managed edits outside an agent stream. diff --git a/docs/content/docs/openui-cloud/build/component-library.mdx b/docs/content/docs/openui-cloud/build/component-library.mdx new file mode 100644 index 000000000..376cfa548 --- /dev/null +++ b/docs/content/docs/openui-cloud/build/component-library.mdx @@ -0,0 +1,168 @@ +--- +title: Component Library +description: Use OpenUI Cloud with its built-in chat library, or bring your own components. +--- + +## Using the built-in library + +Out of the box, OpenUI Cloud ships a general-purpose chat library with text, headers, tables, charts, forms, tabs, buttons, and more. + +Use it with `AgentInterface` on the client: + +```tsx +import { chatLibrary } from "@openuidev/thesys"; + +; +``` + +On the backend, `generateSystemPrompt()` uses the built-in library by default. Use the `embedClient` from the [API overview](/docs/openui-cloud/api/overview); the placement of the generated instructions depends on the API: + + + + +```ts +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const response = await embedClient.responses.create({ + model: "openai/gpt-5", + input: "Show revenue by region as an interactive dashboard.", + instructions: generateSystemPrompt({ + instructions: "Optional instructions for the model.", + }), +}); +``` + + + + +```ts +import { generateSystemPrompt } from "@openuidev/thesys-server"; + +const completion = await embedClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + instructions: "Optional instructions for the model.", + }), + }, + { role: "user", content: "Show revenue by region as an interactive dashboard." }, + ], +}); +``` + + + + +OpenUI Cloud takes care of everything in between: the system prompt, output validation, and automatic repair all target the built-in library. + +## Using your own library + +Use your own library when the domain calls for components the generic set cannot express or when the application follows its own design system. + +**Define the library.** Create one [`defineComponent`](/docs/openui-lang/defining-components) per component in the frontend where your React components live. Prop schemas and descriptions are what the model sees; `id` is an optional free-form revision tag. + +```tsx title="src/lib/chat-library.tsx" +import { Metric, Panel } from "@/components"; +import { createLibrary, defineComponent } from "@openuidev/react-lang"; +import { z } from "zod/v4"; + +const MetricDef = defineComponent({ + name: "Metric", + description: "A single KPI stat with an optional trend arrow.", + props: z.object({ + label: z.string(), + value: z.string(), + trend: z.enum(["up", "down"]).optional(), + }), + component: ({ props }) => , +}); + +const PanelDef = defineComponent({ + name: "Panel", + description: "Top-level container. Children stack vertically.", + props: z.object({ children: z.array(MetricDef.ref) }), + component: ({ props, renderNode }) => {renderNode(props.children)}, +}); + +export const myLibrary = createLibrary({ + id: "acme-chat@1", + root: "Panel", + components: [PanelDef, MetricDef], +}); +``` + +**Generate the spec handover file.** [`openui generate`](/docs/api-reference/cli#openui-generate) turns the library module into a self-contained JSON file for the backend: + +```bash tab="pnpm" tab-group="pkg" +pnpx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +```bash tab="bun" tab-group="pkg" +bunx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +```bash tab="yarn" tab-group="pkg" +yarn dlx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +```bash tab="npm" tab-group="pkg" +npx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json +``` + +**Declare it in the backend call.** Import the generated JSON and pass it as `library`. + + + + +```diff ++ import librarySpec from "./generated/library-spec.json"; + + const response = await embedClient.responses.create({ + model: "openai/gpt-5", + input, + instructions: generateSystemPrompt({ + instructions: "Optional instructions for the model.", ++ library: librarySpec, ++ promptOptions: { preamble: "You build dashboards for Acme operators." }, + }), + }); +``` + + + + +```diff ++ import librarySpec from "./generated/library-spec.json"; + + const completion = await embedClient.chat.completions.create({ + model: "openai/gpt-5", + messages: [ + { + role: "system", + content: generateSystemPrompt({ + instructions: "Optional instructions for the model.", ++ library: librarySpec, ++ promptOptions: { preamble: "You build dashboards for Acme operators." }, + }), + }, + ...messages, + ], + }); +``` + + + + +`promptOptions` is valid only alongside `library`. Use `preamble`, `additionalRules`, and `examples` to tune the generated prompt. + +**Swap the client library:** + +```diff +- import { chatLibrary } from "@openuidev/thesys"; ++ import { myLibrary } from "@/lib/chat-library"; + +- ; ++ ; +``` diff --git a/docs/content/docs/openui-cloud/get-started.mdx b/docs/content/docs/openui-cloud/get-started.mdx index a3441cf12..0467047f6 100644 --- a/docs/content/docs/openui-cloud/get-started.mdx +++ b/docs/content/docs/openui-cloud/get-started.mdx @@ -61,6 +61,7 @@ Open [http://localhost:3000](http://localhost:3000) and send a message. Ask for ## What the scaffold includes - A working chat interface where responses render as interactive components. +- A server route connected to the [Responses API](/docs/openui-cloud/api/responses). - Slides and reports enabled out of the box. - Conversation history and artifact storage, with no database to set up. - A codebase ready to be shaped into a product. diff --git a/docs/content/docs/openui-cloud/how-it-works.mdx b/docs/content/docs/openui-cloud/how-it-works.mdx index 3da44c83f..c874c7149 100644 --- a/docs/content/docs/openui-cloud/how-it-works.mdx +++ b/docs/content/docs/openui-cloud/how-it-works.mdx @@ -5,18 +5,21 @@ description: "Learn how OpenUI Cloud handles model access, automatic fallbacks, ## 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: generation requests go through it, and what comes back is validated, renderable UI. +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 two API surfaces: +OpenUI Cloud exposes four API surfaces, summarized in the [API overview](/docs/openui-cloud/api/overview): -- **Responses API:** The generation endpoint is compatible with the OpenAI Responses API, so existing OpenAI SDKs work against it. It accepts a conversation turn and streams validated UI as **OpenUI Lang**, the same open-source format rendered by OpenUI component libraries. Managed model access, automatic fallbacks, output validation, and slide and report generation happen behind this endpoint. -- **Persistence API:** Provides read and write access to stored conversations, slides, and reports. The browser calls it directly using short-lived session tokens. +- **[Responses API](/docs/openui-cloud/api/responses):** 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)](/docs/openui-cloud/api/chat-completions):** 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)](/docs/openui-cloud/api/artifacts):** A standalone endpoint for generating and explicitly editing slide and report programs. +- **[Conversations API](/docs/openui-cloud/api/conversations):** Provides read and write access to stored conversation threads and items. The browser calls it directly using short-lived frontend tokens. -Both integrate with AgentInterface, OpenUI's chat surface: streaming, generative UI rendering, artifact panels, and thread history connect without additional wiring. Applications with their own UI consume the same OpenUI Lang stream with the open-source renderer. +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. - A[AgentInterface] @@ -24,7 +27,9 @@ flowchart LR end subgraph Cloud[OpenUI Cloud] R[Responses API] - PA[Persistence API] + C["Chat Completions (Embed)"] + AR["Chat Completions (Artifacts)"] + PA[Conversations API] M["Model routing and fallbacks"] V["Output validation and correction"] G[Artifact generation] @@ -32,17 +37,25 @@ flowchart LR end A --> B B --> R - A -->|session token| PA + B --> C + B --> AR + A -->|frontend token| PA R --> M R --> V R --> G R --> S + C --> M + C -. managed GenUI .-> V + AR --> M + AR --> V + AR --> G PA --> S -`} /> +`} +/> -The application consists of product code, AgentInterface, and a backend route that holds the API key. OpenUI Cloud runs model routing, validation, artifact generation, and storage. +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. -## Request lifecycle +## Responses request lifecycle >App: Stream of renderable UI App-->>Browser: Stream relayed, interface renders progressively Note over Cloud: Turn persisted to the conversation + `} /> 1. The user sends a message. AgentInterface posts it to the application backend. @@ -68,24 +82,38 @@ sequenceDiagram 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](/docs/openui-cloud/api/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 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. +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 -Slides and reports are generated through 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 both support manual editing in their viewers. Slides can be exported to PowerPoint, and reports can be exported to PDF. +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 -Conversations are 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 and artifacts from the Persistence API. +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 session-token minting. It is held by the application backend and is never sent to the browser. -- **Session 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 from the Persistence API without the backend proxying each read. Tokens expire within minutes, and AgentInterface requests a fresh token from the backend before expiry. +- **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. >App: Session token request + Browser->>App: Frontend token request App->>Cloud: Mint request, authorized with the API key - Cloud-->>App: Short-lived session token - App-->>Browser: Session token + Cloud-->>App: Short-lived frontend token + App-->>Browser: Frontend token Browser->>Cloud: Reads conversations and artifacts + `} /> diff --git a/docs/content/docs/openui-cloud/index.mdx b/docs/content/docs/openui-cloud/index.mdx index 36ba04de2..e14d28cc7 100644 --- a/docs/content/docs/openui-cloud/index.mdx +++ b/docs/content/docs/openui-cloud/index.mdx @@ -68,6 +68,15 @@ Requests are automatically routed to a fallback when the selected model or provi +## Choose an API + + + + Compare the Responses, Embed Chat Completions, Artifact Chat Completions, and Conversations + APIs, then open the focused guide for the surface you need. + + + ## Generative UI for agents Agents can respond with interfaces that match the task instead of returning only text. They can present a form to collect information, visualize data with a chart, or organize a detailed response with tabs and accordions. diff --git a/docs/content/docs/openui-cloud/meta.json b/docs/content/docs/openui-cloud/meta.json index 6715342fe..89042e5e9 100644 --- a/docs/content/docs/openui-cloud/meta.json +++ b/docs/content/docs/openui-cloud/meta.json @@ -5,8 +5,15 @@ "index", "get-started", "how-it-works", + "---APIs---", + "api/overview", + "api/responses", + "api/chat-completions", + "api/artifacts", + "api/conversations", "models-and-byok", "---Features---", + "build/component-library", "build/chat", "build/slides", "build/reports", diff --git a/docs/content/docs/openui-cloud/models-and-byok.mdx b/docs/content/docs/openui-cloud/models-and-byok.mdx index 96c299240..3db5e981d 100644 --- a/docs/content/docs/openui-cloud/models-and-byok.mdx +++ b/docs/content/docs/openui-cloud/models-and-byok.mdx @@ -1,6 +1,6 @@ --- title: Models and BYOK -description: "Configure provider keys, choose supported models, and call OpenUI Cloud with the Responses API." +description: "Configure provider keys and choose supported models for OpenUI Cloud generation APIs." --- import { CopyableModelId } from "@/components/copyable-model-id";