The Open Standard for Generative UI
docs(cli): document backend framework selection (#965)
ABcda504b5e1a8
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdxindex 604424d16..454627902 100644--- a/docs/content/docs/api-reference/cli.mdx+++ b/docs/content/docs/api-reference/cli.mdx@@ -53,21 +53,22 @@ openui create [options]**Options**-| Flag | Description |-| --------------------------- | ---------------------------------------------------------------- |-| `-n, --name <string>` | Project name (interactive default: `openui-agent`) |-| `-t, --template <template>` | AI backend: `openui-cloud` (recommended) or `openui-self-hosted` |-| `--api-key <key>` | OpenUI Cloud API key; skips sign-in for the Cloud setup |-| `--auth <method>` | Cloud auth method: `oauth` or `skip`; `manual` is deprecated |-| `--skill` | Install the OpenUI agent skill for AI coding assistants |-| `--no-skill` | Skip installing the OpenUI agent skill |-| `--no-install` | Scaffold without running dependency installation |-| `-i, --immediate` | Start the development server after installing dependencies |-| `--no-immediate` | Install dependencies without starting the development server |-| `--no-interactive` | Fail instead of prompting for missing input |-| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |--When run interactively (default), the CLI prompts for any missing options, installs dependencies with the detected package manager, starts the development server, and opens its local URL in the default browser. There is no separate start-server prompt; pass `--no-immediate` to install and exit instead. For most prototypes and evaluations, start with **OpenUI Cloud, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.+| Flag | Description |+| --------------------------------- | ---------------------------------------------------------------- |+| `-n, --name <string>` | Project name (interactive default: `openui-agent`) |+| `-t, --template <template>` | AI backend: `openui-cloud` (recommended) or `openui-self-hosted` |+| `--backend-framework <framework>` | Backend integration: `default`, `langgraph`, or `vercel-ai-sdk` |+| `--api-key <key>` | OpenUI Cloud API key; skips sign-in for the Cloud setup |+| `--auth <method>` | Cloud auth method: `oauth` or `skip`; `manual` is deprecated |+| `--skill` | Install the OpenUI agent skill for AI coding assistants |+| `--no-skill` | Skip installing the OpenUI agent skill |+| `--no-install` | Scaffold without running dependency installation |+| `-i, --immediate` | Start the development server after installing dependencies |+| `--no-immediate` | Install dependencies without starting the development server |+| `--no-interactive` | Fail instead of prompting for missing input |+| `--agent-name <name>` | Declare the invoking coding-agent slug (default: `unknown`) |++When run interactively (default), the CLI prompts for any missing options, including the backend framework, then asks whether to start the development server after installing dependencies with the detected package manager. The start prompt defaults to yes; answering no preserves the existing install-and-exit behavior and prints the `cd` and dev commands. For most prototypes and evaluations, start with **OpenUI Cloud, the recommended default**: hosted models, managed conversation history and streaming, built-in tools, and ready-to-use reports and presentations without operating the model, storage, or artifact infrastructure. Choose **self-hosted** when owning the OpenAI-compatible provider, AI route, and persistence is a requirement.In non-interactive mode, dependencies are installed without starting the long-running development server. Pass `--immediate` to install, start, and open the app, or `--no-install` to scaffold only.@@ -75,7 +76,7 @@ In non-interactive mode, dependencies are installed without starting the long-ru**What it does**-1. Resolves the project name and AI setup+1. Resolves the project name, AI setup, and backend framework2. Copies the selected Next.js template into `<name>/`3. Rewrites `workspace:*` dependency versions to `latest`4. Writes the relevant `.env` values, including Thesys sign-in/API-key setup for OpenUI Cloud@@ -83,7 +84,25 @@ In non-interactive mode, dependencies are installed without starting the long-ru6. Auto-detects your package manager (npm, pnpm, yarn, bun)7. Installs dependencies unless skipped, then optionally starts the development server in the generated directory-The generated project includes a `generate:prompt` script that runs `openui generate` as part of `dev` and `build`.+**Backend frameworks**++| Value | OpenUI Cloud route | Self-hosted route |+| --------------- | -------------------------------------------- | ---------------------------------------- |+| `default` | Direct OpenAI SDK Responses proxy | Direct OpenAI SDK Chat Completions proxy |+| `langgraph` | LangGraph Agent Server + Cloud provider | LangGraph Agent Server + your provider |+| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Cloud provider | Vercel AI SDK `streamText()` route |++The CLI applies the selected framework's final route/page files, dependencies, and deployment configuration over the base template. Both Vercel AI SDK variants are standard Next.js deployments with `streamText()`, `toUIMessageStreamResponse()`, and `vercelAIAdapter()`. Both LangGraph variants separate the Agent Server described by `langgraph.json` from the Next.js frontend/proxy. The proxy uses `@openuidev/langchain`, and the browser consumes its AG-UI stream with `agUIAdapter()`.++For both Cloud variants, the framework owns orchestration and application tool execution. OpenUI Cloud is attached as the Responses model provider and conversation store. Reports, presentations, web search, image search, and configured MCP tools remain provider-executed Cloud tools. For either LangGraph template, `pnpm dev` starts the local Agent Server and Next.js together. Deploy the Next.js frontend to Vercel and point `LANGGRAPH_API_URL` at wherever the Agent Server runs.++All four framework routes include a `get_weather` example backed by Open-Meteo. Ask “What’s the weather in Berlin?” to verify the selected framework’s native multi-step tool loop.++**Conversation storage**++Every OpenUI Cloud variant uses OpenUI Cloud as its only durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token. The `threadId` sent to `/api/chat` is the Cloud conversation id, and each backend appends model turns to it with `conversation: threadId` and `store: true`. The Vercel AI SDK route does not create a second store. The Cloud LangGraph relay creates and deletes a temporary Agent Server thread for each run; configure a separate LangGraph checkpointer only when graph state, interrupts, or resumable runs must persist independently.++The self-hosted variants do not configure durable storage. `AgentInterface` keeps messages in memory for the current page session and sends that history to `/api/chat`; refreshing the page loses it. The self-hosted LangGraph relay also creates and deletes a temporary Agent Server thread for each run. Pass a storage implementation to `AgentInterface` and back it with your own database when persistence is required; add a LangGraph checkpointer only for graph-specific durable state.**Agent skill**@@ -102,6 +121,12 @@ pnpx @openuidev/cli@latest create --name my-app --template openui-cloudpnpx @openuidev/cli@latest create --name my-app --template openui-self-hostedpnpx @openuidev/cli@latest create --name my-app --template openui-cloud --immediate+# Select a backend framework explicitly+pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph+pnpx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk+pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph+pnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk+# Non-interactivepnpx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip@@ -118,6 +143,12 @@ bunx @openuidev/cli@latest createbunx @openuidev/cli@latest create --name my-app --template openui-cloudbunx @openuidev/cli@latest create --name my-app --template openui-self-hosted+# Select a backend framework explicitly+bunx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph+bunx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk+bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph+bunx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk+# Non-interactivebunx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip@@ -134,6 +165,12 @@ yarn dlx @openuidev/cli@latest createyarn dlx @openuidev/cli@latest create --name my-app --template openui-cloudyarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted+# Select a backend framework explicitly+yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph+yarn dlx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk+yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph+yarn dlx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk+# Non-interactiveyarn dlx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skip@@ -150,6 +187,12 @@ npx @openuidev/cli@latest createnpx @openuidev/cli@latest create --name my-app --template openui-cloudnpx @openuidev/cli@latest create --name my-app --template openui-self-hosted+# Select a backend framework explicitly+npx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework langgraph+npx @openuidev/cli@latest create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk+npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework langgraph+npx @openuidev/cli@latest create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdk+# Non-interactivenpx @openuidev/cli@latest create --no-interactive --name my-app --template openui-cloud --auth skipdiff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.mdindex 2ac1e9aac..773c3fbb9 100644--- a/packages/openui-cli/README.md+++ b/packages/openui-cli/README.md@@ -12,6 +12,7 @@ It currently supports two workflows:- scaffolding a new OpenUI app from one of two templates:- **OpenUI Cloud (recommended)** — hosted models with managed conversations, streaming, built-in tools, and ready-to-use report and presentation artifacts- **Self-hosted** — bring an OpenAI-compatible model key and own the AI route and persistence+- keeping the default minimal SDK route or adding a LangGraph or Vercel AI SDK backend to either template- generating a system prompt or JSON Schema from a `createLibrary()` export## Install@@ -39,6 +40,15 @@ npx @openuidev/cli@latest create --template openui-cloudnpx @openuidev/cli@latest create --template openui-self-hosted```+Choose a backend framework directly (the default is `default`, the template's minimal SDK route):++```bash+npx @openuidev/cli@latest create --template openui-cloud --backend-framework langgraph+npx @openuidev/cli@latest create --template openui-cloud --backend-framework vercel-ai-sdk+npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework langgraph+npx @openuidev/cli@latest create --template openui-self-hosted --backend-framework vercel-ai-sdk+```+Generate a prompt from a library file:```bash@@ -65,10 +75,11 @@ Options:- `-n, --name <string>`: Project name (interactive default: `openui-agent`)- `-t, --template <template>`: AI backend — `openui-cloud` (managed) or `openui-self-hosted` (bring your provider)+- `--backend-framework <framework>`: API route implementation — `default`, `langgraph`, or `vercel-ai-sdk`- `--skill`: Install the OpenUI agent skill for AI coding assistants- `--no-skill`: Skip installing the OpenUI agent skill- `--no-install`: Scaffold without running the package install-- `-i, --immediate`: Start the development server after installing dependencies+- `-i, --immediate`: Start the development server after installing dependencies; the CLI refuses to start when the template's required API key is unavailable- `--no-immediate`: Install dependencies without starting the development server- `--no-interactive`: Fail instead of prompting for missing required input- `--api-key <key>`: (cloud template) OpenUI Cloud API key; skips sign-in@@ -81,6 +92,7 @@ What it does:- prompts for the project name, defaulting to `openui-agent`, if you do not pass `--name`- uses the `openui-cloud` template when you do not pass `--template` (interactive runs no longer ask; `--template openui-self-hosted` still works)+- prompts for a backend framework after the template; non-interactive usage defaults to `default`- copies the bundled template into a new directory- rewrites monorepo-local dependencies (`workspace:`, `file:`, `catalog:`) in the generated `package.json` to `latest`- installs dependencies automatically using the detected package manager (unless `--no-install`)@@ -94,6 +106,28 @@ What it does:- **OpenUI Cloud (recommended default)** — start here for prototypes and evaluations. You get hosted models, managed conversation history and streaming, built-in tools, and ready-to-use report and presentation artifacts without operating the model, storage, or artifact infrastructure.- **Self-hosted** — choose this when owning the OpenAI-compatible provider integration, AI route, and persistence is a requirement. It is not offered as an interactive choice; request it with `--template openui-self-hosted`.+#### Backend frameworks++| Value | OpenUI Cloud route | Self-hosted route |+| --------------- | -------------------------------------------- | ---------------------------------------- |+| `default` | Direct OpenAI SDK Responses proxy | Direct OpenAI SDK Chat Completions proxy |+| `langgraph` | LangGraph Agent Server + Cloud provider | LangGraph Agent Server + your provider |+| `vercel-ai-sdk` | Vercel AI SDK Next.js agent + Cloud provider | Vercel AI SDK `streamText()` route |++The default implementation is part of each base template. For LangGraph or Vercel AI SDK, the CLI applies a framework-specific set of files plus a manifest for its dependencies, scripts, removals, and onboarding text. Both Vercel AI SDK variants are standard Next.js deployments whose `streamText()` result returns `toUIMessageStreamResponse()` for `vercelAIAdapter()`. Both LangGraph variants separate the Agent Server described by `langgraph.json` from the Next.js frontend/proxy. The proxy uses `@openuidev/langchain`, and the browser consumes its AG-UI stream with `agUIAdapter()`.++In both Cloud framework variants, the selected framework owns the agent orchestration and application tool loop. OpenUI Cloud is attached as the Responses model provider and conversation store. Reports, presentations, web search, image search, and configured MCP tools remain provider-executed Cloud tools, while application tools such as `get_weather` execute inside LangGraph or the Vercel AI SDK. Choosing a Cloud framework does not configure a user-owned model provider; choose `openui-self-hosted` for that.++For either generated LangGraph app, `pnpm dev` starts both Next.js and the local Agent Server. Deploy the Next.js frontend to Vercel, then point `LANGGRAPH_API_URL` at wherever the Agent Server runs. The Cloud graph needs `THESYS_API_KEY`; the self-hosted graph needs the selected provider credentials such as `OPENAI_API_KEY`.++Every Cloud route includes `get_weather` as its example app-owned function tool. The LangGraph and Vercel AI SDK variants define and execute that tool through the selected framework while leaving Cloud-owned tools unchanged. The two self-hosted framework routes include the same weather example and run it through their native multi-step tool loops, making the selected backend directly testable after scaffolding.++#### Conversation storage++Every OpenUI Cloud variant uses OpenUI Cloud as its only durable conversation and artifact store. The browser connects directly through `useOpenuiCloudStorage()` with a short-lived frontend token, and `/api/chat` appends each turn to the same Cloud conversation with `conversation: threadId` and `store: true`. Vercel does not add a second store. The Cloud LangGraph relay creates a temporary Agent Server thread for each run and deletes it afterward; that thread is not the chat-history store. Configure a LangGraph checkpointer separately only when the graph itself needs durable state, interrupts, or resumable runs.++The self-hosted variants do not configure durable storage. `AgentInterface` keeps the conversation in memory for the current page session and sends that history to `/api/chat`; refreshing the page loses it. The self-hosted LangGraph relay also creates and deletes a temporary Agent Server thread for each run. Pass a storage implementation to `AgentInterface` and back it with your own database when persistence is required; add a LangGraph checkpointer only for graph-specific durable state.+#### Template-specific `.env`- **OpenUI Cloud** — obtains an OpenUI Cloud API key and writes `THESYS_API_KEY` plus `DEMO_USER_ID=demo-user` to `.env`. The key is resolved by, in order:@@ -109,7 +143,12 @@ Examples:```bashopenui create+openui create --name my-app --template openui-self-hosted+openui create --name my-app --template openui-self-hosted --backend-framework langgraph+openui create --name my-app --template openui-self-hosted --backend-framework vercel-ai-sdkopenui create --name my-app --template openui-cloud --auth oauth+openui create --name my-app --template openui-cloud --backend-framework langgraph --auth oauth+openui create --name my-app --template openui-cloud --backend-framework vercel-ai-sdk --auth oauthopenui create --name my-app --template openui-cloud --api-key tk_your_keyopenui create --name my-app --template openui-self-hostedopenui create --name my-app --template openui-cloud --immediatediff --git a/packages/openui-cli/src/templates/openui-cloud/README.md b/packages/openui-cli/src/templates/openui-cloud/README.mdindex ac74b4a57..2d9f4ac89 100644--- a/packages/openui-cli/src/templates/openui-cloud/README.md+++ b/packages/openui-cli/src/templates/openui-cloud/README.md@@ -2,11 +2,8 @@ This is an [OpenUI](https://openui.com) Cloud project bootstrapped with [`openui## Setup-```bash-cp .env.example .env.local # fill THESYS_API_KEY and point the base URLs at your API-```--Required env: `THESYS_API_KEY`, `DEMO_USER_ID`.+The CLI writes `.env` for you. If you cloned the generated project elsewhere,+create `.env` with `THESYS_API_KEY`, `DEMO_USER_ID`, and `APP_ID`.## Getting Started@@ -19,7 +16,37 @@ pnpm devOpen [http://localhost:3000](http://localhost:3000) with your browser to see the result.You can start editing the page by modifying `src/app/api/chat/route.ts` and improving your agent-by adding system prompts or tools.+by adding system prompts or tools. A LangGraph scaffold puts the Agent Server implementation in+`src/agent/agent.ts` instead.++## Framework deployments++The Vercel AI SDK scaffold is a standard Next.js app: `streamText()` owns the+agent loop and UIMessage stream, so the whole project can be deployed to Vercel.++The LangGraph scaffold contains two deployables. `pnpm dev` runs Next.js and the+local Agent Server together. Deploy the Next.js frontend to Vercel, then point+`LANGGRAPH_API_URL` at wherever the Agent Server runs. That Agent Server needs+`THESYS_API_KEY` because the graph uses OpenUI Cloud as its model provider.++In both variants, your framework executes application tools. OpenUI Cloud+provides managed conversation storage and executes its provider tools: reports,+presentations, web search, image search, and configured MCP servers.++## Conversation storage++OpenUI Cloud is the only durable conversation and artifact store in every Cloud+variant. The browser connects directly through `useOpenuiCloudStorage()` with a+short-lived token from `/api/frontend-token`. The `threadId` sent to `/api/chat`+is the Cloud conversation id, and the route appends each model turn to it with+`conversation: threadId` and `store: true`.+Browser `localStorage` holds only the selected model, not conversation messages.++The Vercel AI SDK route does not create a second store. The LangGraph relay uses+a temporary Agent Server thread for each run and deletes it afterward, so+LangGraph is not the persistent chat-history store. Add a LangGraph+checkpointer separately only if the graph needs durable state, interrupts, or+resumable runs.## Switching Modelsdiff --git a/packages/openui-cli/src/templates/openui-self-hosted/README.md b/packages/openui-cli/src/templates/openui-self-hosted/README.mdindex 5daef3995..eb031dbb9 100644--- a/packages/openui-cli/src/templates/openui-self-hosted/README.md+++ b/packages/openui-cli/src/templates/openui-self-hosted/README.md@@ -21,7 +21,32 @@ pnpm devOpen [http://localhost:3000](http://localhost:3000) with your browser to see the result.You can start editing the page by modifying `src/app/api/chat/route.ts` and improving your agent-by adding system prompts or tools.+by adding system prompts or tools. A LangGraph scaffold puts the standalone Agent+Server implementation in `src/agent/agent.ts` instead.++If you selected LangGraph or the Vercel AI SDK, the generated route includes a `get_weather`+example. Ask “What’s the weather in Berlin?” to exercise its native tool loop.++## Framework deployments++The Vercel AI SDK scaffold runs its backend inside the Next.js API route, so the+frontend and backend can be deployed together as one Next.js project.++The LangGraph scaffold makes the backend independently deployable. `pnpm dev`+starts the local Agent Server and Next.js together. Deploy the Next.js frontend+to Vercel, then point `LANGGRAPH_API_URL` at wherever the Agent Server runs.+Configure `OPENAI_API_KEY`, `OPENAI_MODEL`, and optional `OPENAI_BASE_URL` on+the Agent Server.++## Conversation storage++This starter does not configure durable conversation storage. `AgentInterface`+keeps messages in memory for the current page session and sends that history to+`/api/chat`; refreshing the page loses it. The LangGraph relay creates and+deletes a temporary Agent Server thread for each run, so it does not provide+chat persistence by itself. To persist conversations, pass a storage+implementation to `AgentInterface` and back it with your own database. Add a+LangGraph checkpointer separately only for graph-specific durable state.## Learn More