Responses API
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, 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.
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 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:
"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 <AgentInterface llm={llm} componentLibrary={chatLibrary} />;
}Your /api/chat route should forward the OpenUI Cloud response stream without changing its event shape. See Adapters and message 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:
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.
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 |
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 for the execution model.
Generate slides and reports
Add artifactTool() to generate editable slides or reports inside the agent stream:
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 contains the complete client setup.
Follow-up requests in the same stored conversation edit the existing artifact automatically. Use Chat Completions for artifacts when you need standalone generation or explicitly managed edits outside an agent stream.