Skip to content

The Open Standard for Generative UI

feat(cookbooks): store threads in Gateway conversations and run tools with runTools() (#1258)

Visharad Kashyap600ee4e724dd
diff --git a/.prettierrc.json b/.prettierrc.json
index f94891b0a..3f961cf09 100644
--- a/.prettierrc.json
+++ b/.prettierrc.json
@@ -4,5 +4,13 @@
"singleQuote": false,
"printWidth": 100,
"tabWidth": 2,
- "plugins": ["prettier-plugin-organize-imports"]
-}
\ No newline at end of file
+ "plugins": ["prettier-plugin-organize-imports"],
+ "overrides": [
+ {
+ "files": "docs/content/docs/cookbooks/*.mdx",
+ "options": {
+ "embeddedLanguageFormatting": "off"
+ }
+ }
+ ]
+}
diff --git a/docs/components/cookbook-analytics-architecture.tsx b/docs/components/cookbook-analytics-architecture.tsx
index 520656ac4..a91ce5f01 100644
--- a/docs/components/cookbook-analytics-architecture.tsx
+++ b/docs/components/cookbook-analytics-architecture.tsx
@@ -1,4 +1,4 @@
-import { Database, MessagesSquare, Server, Sparkles, type LucideIcon } from "lucide-react";
+import { Database, History, MessagesSquare, Server, Sparkles, type LucideIcon } from "lucide-react";
type Box = {
x: number;
@@ -53,6 +53,16 @@ const boxes: Box[] = [
lines: ["Read-only queries"],
footer: "F1 lap times · SQLite",
},
+ {
+ x: 350,
+ y: 314,
+ width: 230,
+ height: 146,
+ icon: History,
+ title: "Conversations",
+ lines: ["Keeps each thread"],
+ footer: "OpenUI Gateway",
+ },
];
// One request and one reply between each pair of boxes, read left to right.
@@ -125,6 +135,20 @@ function BoxNode({ box }: { box: Box }) {
);
}
+// An elbow connector; `both` puts an arrowhead at each end.
+function Connector({ d, both = false }: { d: string; both?: boolean }) {
+ return (
+ <path
+ d={d}
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.6}
+ markerStart={both ? "url(#analytics-architecture-arrow)" : undefined}
+ markerEnd="url(#analytics-architecture-arrow)"
+ />
+ );
+}
+
function Arrow({ x1, y1, x2, y2 }: { x1: number; y1: number; x2: number; y2: number }) {
return (
<line
@@ -155,7 +179,8 @@ export function CookbookAnalyticsArchitecture() {
A chat interface, such as Agent Interface, sends the question to OpenUI Gateway, which
runs the model. The model makes a tool call to your server, which runs a read-only query
against your data and returns the tool result. Gateway then streams the answer back to the
- chat interface.
+ chat interface. Your server saves each turn to the thread's Gateway conversation, and the
+ chat interface lists and reopens threads from there.
</desc>
<defs>
<marker
@@ -205,6 +230,16 @@ export function CookbookAnalyticsArchitecture() {
Rows
</text>
+ {/* The chat interface lists and reopens threads; your server saves each turn. */}
+ <Connector d="M115 228 V387 H344" both />
+ <text x={127} y={312} className={label}>
+ Threads
+ </text>
+ <Connector d="M706 206 H645 V387 H586" />
+ <text x={633} y={312} textAnchor="end" className={label}>
+ Turns
+ </text>
+
{boxes.map((box) => (
<BoxNode key={box.title} box={box} />
))}
diff --git a/docs/components/cookbook-booking-diagram.tsx b/docs/components/cookbook-booking-diagram.tsx
index 42a966238..671822b60 100644
--- a/docs/components/cookbook-booking-diagram.tsx
+++ b/docs/components/cookbook-booking-diagram.tsx
@@ -57,7 +57,8 @@ export function CookbookBookingDiagram() {
MCP server, which returns live prices from booking sites, and the model shows the stays as
cards with photos. The guest picks one and sees a summary with a Continue button that
opens the booking site, where they book and pay. The model writes every screen; the search
- and the booking happen outside the chat.
+ and the booking happen outside the chat. Your server also saves each turn to the thread's
+ Gateway conversation, so the thread reopens later with its messages.
</desc>
<defs>
<marker
@@ -82,7 +83,7 @@ export function CookbookBookingDiagram() {
</defs>
<text x={10} y={22} className={caption}>
- 1. In the chat
+ In the chat
</text>
{screens.map((screen, index) => (
<g key={screen.title}>
@@ -190,7 +191,7 @@ export function CookbookBookingDiagram() {
{/* Who does what. */}
<text x={10} y={278} className={caption}>
- 2. Outside the chat
+ Outside the chat
</text>
<text x={10} y={302} className={note}>
The model writes every screen from your components.
@@ -224,6 +225,16 @@ export function CookbookBookingDiagram() {
<text x={x(3) + 102} y={305} textAnchor="middle" className={note}>
The guest books and pays
</text>
+
+ {/* Your server saves each turn to the thread's Gateway conversation. */}
+ <Arrow d={`M${x(2) - 4} 290 H${x(1) + 165} V344`} id={id} />
+ <rect x={x(1)} y={350} width={205} height={50} rx={12} strokeWidth={1.6} className={box} />
+ <text x={x(1) + 102} y={371} textAnchor="middle" className={label}>
+ Conversation
+ </text>
+ <text x={x(1) + 102} y={390} textAnchor="middle" className={note}>
+ Keeps each turn in Gateway
+ </text>
</svg>
</figure>
);
diff --git a/docs/components/cookbook-comparison-diagram.tsx b/docs/components/cookbook-comparison-diagram.tsx
index cbb63f337..6d2255864 100644
--- a/docs/components/cookbook-comparison-diagram.tsx
+++ b/docs/components/cookbook-comparison-diagram.tsx
@@ -12,6 +12,13 @@ const pipeline = [
{ title: "Database", detail: "Local SQLite file" },
];
+// After each answer: the thread is kept in a Gateway conversation.
+const thread = [
+ { title: "Turn", detail: "Question and answer" },
+ { title: "Conversation", detail: "Saved in Gateway" },
+ { title: "Thread", detail: "Reopens later" },
+];
+
const companies = ["NVIDIA", "AMD", "Intel"];
const criteria = [
{ name: "Revenue", pages: ["Page 37", "Page 50", "Page 27"], y: 222 },
@@ -42,7 +49,7 @@ export function CookbookComparisonDiagram() {
return (
<figure className="not-prose my-6 overflow-x-auto">
<svg
- viewBox="0 0 930 392"
+ viewBox="0 0 930 490"
role="img"
aria-labelledby={`${id}-title ${id}-description`}
className="h-auto w-full min-w-[640px] text-fd-foreground"
@@ -54,7 +61,8 @@ export function CookbookComparisonDiagram() {
meaning, and saved in a local database. Then, for each question, such as comparing revenue
and R&D spending, the model picks what to compare, the best-matching page in each report
is found for each item, and the answer appears in the chat as a table, charts, and quoted
- sources.
+ sources. Finally, each question and answer is saved to the thread's Gateway conversation,
+ so the thread reopens later with its messages.
</desc>
<defs>
<marker
@@ -80,7 +88,7 @@ export function CookbookComparisonDiagram() {
{/* Prepare once: npm run prepare:documents */}
<text x={10} y={22} className={caption}>
- 1. Prepare the reports once
+ Prepare the reports once
</text>
{pipeline.map((step, index) => {
const x = 10 + index * 190;
@@ -119,7 +127,7 @@ export function CookbookComparisonDiagram() {
{/* Every question */}
<text x={10} y={160} className={caption}>
- 2. Answer each question
+ Answer each question
</text>
<rect x={10} y={196} width={170} height={150} rx={12} strokeWidth={1.75} className={box} />
@@ -243,6 +251,39 @@ export function CookbookComparisonDiagram() {
<text x={832} y={374} textAnchor="middle" className={caption}>
Answer in the chat
</text>
+
+ {/* After each answer */}
+ <text x={10} y={412} className={caption}>
+ Keep the thread
+ </text>
+ {thread.map((step, index) => {
+ const x = 10 + index * 190;
+ return (
+ <g key={step.title}>
+ <rect
+ x={x}
+ y={424}
+ width={150}
+ height={56}
+ rx={28}
+ strokeWidth={1.6}
+ className={box}
+ />
+ <text x={x + 75} y={448} textAnchor="middle" className={label}>
+ {step.title}
+ </text>
+ <text
+ x={x + 75}
+ y={467}
+ textAnchor="middle"
+ className="fill-fd-muted-foreground font-sans text-[13px]"
+ >
+ {step.detail}
+ </text>
+ {index < thread.length - 1 && <Arrow d={`M${x + 154} 452 H${x + 184}`} id={id} />}
+ </g>
+ );
+ })}
</svg>
</figure>
);
diff --git a/docs/content/docs/cookbooks/booking-assistant.mdx b/docs/content/docs/cookbooks/booking-assistant.mdx
index e3bf86bc4..d504da3d4 100644
--- a/docs/content/docs/cookbooks/booking-assistant.mdx
+++ b/docs/content/docs/cookbooks/booking-assistant.mdx
@@ -111,9 +111,17 @@ Each step covers one part of the example, in the order a request flows through i
trivago's server speaks MCP over HTTP at `https://mcp.trivago.com/mcp`. Its `trivago-accommodation-search` tool takes a destination, dates, guests, and optional filters for stars, guest rating, and amenities. The example calls it with the MCP TypeScript SDK and keeps only the structured hotel list:
```ts title="src/lib/trivago.ts"
-export async function searchAccommodations(search: AccommodationSearch, signal?: AbortSignal) {
- const client = new Client({ name: "openui-booking-assistant", version: "0.1.0" });
- await client.connect(new StreamableHTTPClientTransport(serverUrl), { signal });
+export async function searchAccommodations(
+ search: AccommodationSearch,
+ signal?: AbortSignal,
+) {
+ const client = new Client({
+ name: "openui-booking-assistant",
+ version: "0.1.0",
+ });
+ await client.connect(new StreamableHTTPClientTransport(serverUrl), {
+ signal,
+ });
try {
const result = await client.callTool(
{ name: "trivago-accommodation-search", arguments: search },
@@ -155,10 +163,11 @@ Give Gateway a function tool named `search_stays`. It takes every detail of the
Currencies, guest ratings, and amenities are enums of the values trivago accepts. Your server validates the arguments again, rejecting a check-in in the past or more rooms than adults, and maps them to trivago's filters. trivago has no price filter, so the tool applies the budget itself:
```ts title="src/lib/tools/search-stays.ts"
-// trivago has no price filter, so apply the budget here and report what it left out.
+// trivago has no price filter, so apply the budget and track what it drops.
const inBudget = found.filter(
(stay) =>
- args.max_price_per_night === null || amount(stay.price_per_night) <= args.max_price_per_night,
+ args.max_price_per_night === null ||
+ amount(stay.price_per_night) <= args.max_price_per_night,
);
const overBudget = found.filter((stay) => !inBudget.includes(stay));
```
@@ -209,7 +218,8 @@ export const DatePicker = defineComponent({
name: "DatePicker",
props: openuiLibrary.components.DatePicker.props,
description:
- "A single date. Prefill it by passing a YYYY-MM-DD string as value; the form submits YYYY-MM-DD.",
+ "A single date. Prefill it by passing a YYYY-MM-DD string as value; " +
+ "the form submits YYYY-MM-DD.",
component: ({ props }) => {
const field = useStateField(props.name, props.value);
return (
@@ -235,27 +245,43 @@ The model prefills a field by passing its value, such as the date `"2026-10-02"`
> Submitted form state contains only the fields the user changed. For every field missing from it, use the value you prefilled in that form.
-Agent Interface sends the whole conversation with every turn, so the model still sees its own form from the previous turn and can fill in the gaps. The remaining rules describe the stay cards, the summary, and the hand-off. Each stay card's value is the stay's booking link, so choosing a card sends the link back with the form, and the summary's **Continue to booking** button opens it with `@OpenUrl`. One example program for each step, the trip form, the stay cards, and the summary, shows the model how the components fit together.
+Agent Interface sends the whole conversation with every turn, so the model still sees its own form from the previous turn and can fill in the gaps. The remaining rules describe the stay cards, the summary, and the hand-off. Each stay card's value is the stay's booking link, so choosing a card sends the link back with the form, and the summary's **Continue to booking** button opens it with `@OpenUrl`. One OpenUI Lang example for each step, the trip form, the stay cards, and the summary, shows the model how the components fit together.
### 5. Connect Agent Interface
-Agent Interface provides the sidebar, composer, tool timeline, and stop control. Connect generation to the local chat route with `fetchLLM`. It sends the thread's messages in Chat Completions format and reads the route's stream with `agUIAdapter()`:
+Agent Interface provides the sidebar, composer, tool timeline, and stop control. Connect generation to the local chat route with `fetchLLM`. It sends the thread's messages in Chat Completions format and reads the route's stream with `openAIReadableStreamAdapter()`:
```tsx title="src/components/booking-chat.tsx"
const llm = fetchLLM({
url: "/api/chat",
- streamAdapter: agUIAdapter(),
+ streamAdapter: openAIReadableStreamAdapter(),
messageFormat: openAIMessageFormat,
});
+
+const storage = useOpenuiCloudStorage({
+ token: "/api/frontend-token",
+ features: { artifact: false },
+});
+
+<AgentInterface
+ llm={llm}
+ storage={storage}
+ componentLibrary={library}
+ agentName="Stay finder"
+/>;
```
-Chat Completions does not store conversations, so Agent Interface keeps each thread in the browser and sends its messages with every turn. Threads last until the page reloads. To keep them longer, pass a `storage` adapter backed by your database; see [Connect a backend](/docs/agent/reference/self-hosting).
+Chat Completions does not store conversations, so the chat route loads each thread's earlier turns from Gateway, with their searches and results, and sends them with every turn.
-The chat route runs the same [function-tool loop](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/lib/tool-loop.ts) as the [conversational analytics cookbook](/cookbooks/conversational-analytics#5-stream-the-answer), streaming AG-UI events so Agent Interface shows each search and its result. It forwards only user messages and assistant answers from the browser and drops tool calls and results, so later steps rely on what the stay cards show, including the booking link in each card's value. A submitted form arrives as one message with the button label and the form's values, so the route accepts user messages of up to 4,000 characters.
+<Callout type="info" title="Thread storage">
-The example also customizes Agent Interface with a theme from `createTheme`, a logo, starters for four different trips, and a thread header that credits trivago. See [Welcome and starters](/docs/agent/customize/welcome-and-starters).
+`useOpenuiCloudStorage()` keeps the thread list in Gateway, and the chat route saves each turn, tool calls included, with [`storeChatCompletionHistory()`](/docs/api-reference/server#conversation-history), so threads and their messages stay after a reload.
-This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
+</Callout>
+
+The [chat route](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/booking-assistant/src/app/api/chat/route.ts) runs `search_stays` whenever the model asks for a search and streams the answer to Agent Interface as the model writes it, so **Behind the scenes** shows each search. Earlier turns come from the Gateway conversation, with their searches and results, so later steps can use the stays a search returned.
+
+The example also customizes Agent Interface with a theme from `createTheme`, a logo, starters for four different trips, and a thread header that credits trivago. See [Welcome and starters](/docs/agent/customize/welcome-and-starters).
## Verify it works
@@ -266,7 +292,8 @@ In the browser:
3. Fill it in again and search. Open **Form data** above your message to see the values that were sent, and expand **Behind the scenes** to see the `search_stays` call.
4. Ask for **“under $100 a night”**, and confirm the reply says how many stays were over budget and the cheapest price among them.
5. Pick a stay, check the summary, and click **Continue to booking**. trivago should open the stay for your dates and guests.
-6. Switch your operating system between light and dark mode, and confirm the theme follows.
+6. Reload the page and open an earlier thread. Confirm its messages load.
+7. Switch your operating system between light and dark mode, and confirm the theme follows.
Generated layouts can vary. Hotels, prices, photos, and links should always come from a search result, and prices can change between searches.
@@ -276,10 +303,22 @@ To use another MCP server, keep the `search_stays` contract and replace `searchA
The form pattern carries over to anything that needs a few details before an action: a restaurant reservation, a support ticket, a travel request. Describe the details, their controls, and which are required, and keep the action behind a summary. Before relying on a third-party MCP server in production, check its terms and plan for it being slow or unavailable.
-This example runs locally without authentication, and its chat route accepts browser requests only from its own page. Before deploying it, add authentication and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/booking-assistant) for the implementation notes.
+This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
-- [Agent Interface quickstart](/docs/agent/getting-started/quickstart)
-- [Gateway Chat Completions API](/docs/gateway/api/chat-completions)
-- [Connect a backend](/docs/agent/reference/self-hosting)
+This example runs locally without authentication. Before deploying it, add [authentication](/docs/gateway/authentication), limits on request size, and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/booking-assistant) for the implementation notes.
+
+## References
+
+- [`@openuidev/react-ui`](/docs/api-reference/react-ui): `AgentInterface` and the built-in component libraries.
+- [`@openuidev/react-headless`](/docs/api-reference/react-headless): `fetchLLM()`, `openAIReadableStreamAdapter()`, and `useOpenuiCloudStorage()`, which the example imports through `@openuidev/react-ui`.
+- [`@openuidev/react-lang`](/docs/api-reference/react-lang): `createLibrary()` and `defineComponent()`.
+- [`@openuidev/lang-core`](/docs/openui-lang/system-prompts): `generateSystemPrompt()`.
+- [`@openuidev/server`](/docs/api-reference/server#conversation-history): `storeChatCompletionHistory()`.
+- [`@openuidev/cli`](/docs/api-reference/cli): `openui generate`.
+- [OpenAI SDK](https://github.com/openai/openai-node): `runTools()` and `toReadableStream()`.
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk): the Streamable HTTP client that calls trivago's MCP server.
+- [Gateway Chat Completions API](/docs/gateway/api/chat-completions).
+- [Agent Interface quickstart](/docs/agent/getting-started/quickstart).
+- [Connect a backend](/docs/agent/reference/self-hosting).
Hotels, prices, and photos: [trivago MCP](https://mcp.trivago.com/docs), fetched live for each search.
diff --git a/docs/content/docs/cookbooks/conversational-analytics.mdx b/docs/content/docs/cookbooks/conversational-analytics.mdx
index f8b071dca..335db9f04 100644
--- a/docs/content/docs/cookbooks/conversational-analytics.mdx
+++ b/docs/content/docs/cookbooks/conversational-analytics.mdx
@@ -58,7 +58,6 @@ Try this conversation:
2. **“Compare Norris and Verstappen lap by lap.”** See their times in a line chart.
3. **“Focus on their final ten laps.”** Narrow the chart while retaining the selected drivers.
-
## How it works
A conversational analytics assistant splits the work between your application and the model. Your application owns the data and decides which questions it can answer. The model interprets each question and decides how to present the answer.
@@ -67,8 +66,8 @@ A conversational analytics assistant splits the work between your application an
1. **The user asks a question.** Agent Interface sends the conversation to your server's chat route, which adds a system prompt that describes your components and a function tool that describes the queries you support, then calls OpenUI Gateway.
2. **The model calls your tool.** Instead of writing SQL, it fills in the tool's structured arguments: which view, which items, and which range. Your server validates the arguments, runs a read-only, parameterized query, and returns the result as JSON. The model sees only what you send it, never the database itself.
-3. **The model composes the answer.** From the tool result, it writes an OpenUI Lang program using only the components in your library: a table for a ranking, a line chart for a comparison, or a sentence for a single number. Gateway validates the program against that library and corrects eligible errors as it streams.
-4. **Agent Interface renders it progressively.** The program starts with its root component, so each table or chart appears as soon as its data arrives. The next request includes the earlier questions and answers, so a follow-up such as "only the last ten laps" reuses that context and runs a fresh query.
+3. **The model composes the answer.** From the tool result, it writes the answer in OpenUI Lang, using only the components in your library: a table for a ranking, a line chart for a comparison, or a sentence for a single number. Gateway validates the OpenUI Lang against that library and corrects eligible errors as it streams.
+4. **Agent Interface renders it progressively.** The answer's OpenUI Lang starts with its root component, so each table or chart appears as soon as its data arrives. The next request includes the earlier questions and answers, so a follow-up such as "only the last ten laps" reuses that context and runs a fresh query.
### Why a tool, not SQL
@@ -135,7 +134,7 @@ export async function executeQueryLapTimes(argsJson: string) {
}
```
-The result contains ranked lap times or aligned chart labels and series. Gateway uses those values to build the answer, and Agent Interface shows the call and its result in the **Behind the scenes** timeline.
+The result contains ranked lap times or aligned chart labels and series. Gateway uses those values to build the answer, and Agent Interface shows the call and its arguments in the **Behind the scenes** timeline.
The query in the same file uses parameterized SQL. Missing times are left out of comparisons rather than plotted as zero.
@@ -179,33 +178,39 @@ This runs `openui generate src/library.ts --spec --out src/generated/spec.json`.
### 4. Connect Agent Interface
-Agent Interface provides the sidebar, composer, tool timeline, and stop control. Connect generation to the local chat route with `fetchLLM`. It sends the thread's messages in Chat Completions format and reads the route's stream with `agUIAdapter()`:
+Agent Interface provides the sidebar, composer, tool timeline, and stop control. Connect generation to the local chat route with `fetchLLM`. It sends the thread's messages in Chat Completions format and reads the route's stream with `openAIReadableStreamAdapter()`:
```tsx title="src/components/analytics-chat.tsx"
const llm = fetchLLM({
url: "/api/chat",
- streamAdapter: agUIAdapter(),
+ streamAdapter: openAIReadableStreamAdapter(),
messageFormat: openAIMessageFormat,
});
+const storage = useOpenuiCloudStorage({
+ token: "/api/frontend-token",
+ features: { artifact: false },
+});
+
<AgentInterface
llm={llm}
+ storage={storage}
componentLibrary={library}
agentName="Data analyst"
theme={{ mode: "light" }}
>
- <AgentInterface.Welcome
- title="Explore your data through conversation"
- description="Ask about recorded lap times from the 2024 Miami Grand Prix, provided by OpenF1. Follow up to explore a different angle."
- />
+ <AgentInterface.Welcome title="Explore your data through conversation" />
<AgentInterface.Composer placeholder="Ask a question about your data…" />
</AgentInterface>;
```
-Chat Completions does not store conversations, so Agent Interface keeps each thread in the browser and sends its messages with every question. That is what lets a follow-up build on the previous answer. Threads last until the page reloads. To keep them, pass a `storage` adapter to Agent Interface:
+Chat Completions does not store conversations, so the chat route loads each thread's earlier turns from Gateway, with their tool calls and results, and sends them with every question. That is what lets a follow-up build on the previous answer.
-- **Gateway conversations.** Store threads with the Gateway [Conversations API](/docs/gateway/api/conversations) and load them in the browser with `useOpenuiCloudStorage()` and a short-lived frontend token. With Chat Completions, your server adds each question and answer to the conversation as items; the [Responses API](/docs/gateway/api/responses) appends them for you. This works with custom backends too: the Gateway-backed LangGraph, Vercel AI SDK, and Vercel Eve templates from [`openui create`](/docs/api-reference/cli) keep their threads this way while the framework runs the agent.
-- **Your own database.** Serve threads from your backend and connect them with `restStorage`; see [Connect a backend](/docs/agent/reference/self-hosting#3-persist-conversations).
+<Callout type="info" title="Thread storage">
+
+`useOpenuiCloudStorage()` keeps the thread list in Gateway, and the chat route saves each turn, tool calls included, with [`storeChatCompletionHistory()`](/docs/api-reference/server#conversation-history), so threads and their messages stay after a reload.
+
+</Callout>
### 5. Stream the answer
@@ -216,64 +221,68 @@ const gateway = new OpenAI({
apiKey: process.env.THESYS_API_KEY,
baseURL: "https://api.thesys.dev/v1/embed",
});
-const lapTimesTool = queryLapTimesTool(drivers);
-const params = {
- model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
- messages: [
- { role: "system" as const, content: analyticsPrompt(drivers) },
- ...conversation(body.messages),
- ],
- tools: [lapTimesTool],
- max_completion_tokens: 6000,
-};
-const firstStream = await gateway.chat.completions.create(
- { ...params, stream: true },
- { signal: request.signal },
+const runner = gateway.chat.completions.runTools(
+ {
+ model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
+ messages: [
+ { role: "system", content: analyticsPrompt(drivers) },
+ ...thread,
+ ],
+ tools: [
+ {
+ type: "function",
+ function: {
+ ...queryLapTimesTool(drivers).function,
+ function: (args: string) =>
+ executeQueryLapTimes(args, { signal: request.signal }).catch(
+ (error: unknown) =>
+ JSON.stringify({
+ error: error instanceof Error ? error.message : String(error),
+ }),
+ ),
+ },
+ },
+ ],
+ stream: true,
+ },
+ { signal: request.signal, maxChatCompletions: 3 },
);
-
-await runChatToolLoop({
- client: gateway,
- params,
- firstStream,
- tools: { [lapTimesTool.function.name]: executeQueryLapTimes },
- emit,
- signal: request.signal,
- maxRounds: 3,
-});
```
-Chat Completions returns function calls to your application rather than running them. The [function-tool loop](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts) runs each requested call, appends the assistant's tool-call message and a `tool` message with the result, and requests the next completion until the model answers.
-
-The loop streams its progress to the browser as AG-UI events rather than raw completion chunks, because Chat Completions has no chunk for a tool result. With these events, Agent Interface shows each call and its result while the answer streams.
-
-The browser sends tool calls and results back with the rest of the thread. `conversation()` drops them and forwards only user questions and assistant answers, so every value the model uses comes from a query your server ran for the current question. The [chat route](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts) also bounds the request's size and validates it before calling Gateway. It opens the first stream before responding, so a rejected key, rate limit, or unknown model returns as an HTTP error with Gateway's status. Errors in later rounds arrive as a `RUN_ERROR` event. Agent Interface shows both in the chat.
-
-Because `componentLibrary` is set, Agent Interface renders the streamed OpenUI Lang with the same library. The prompt emits `root` first, followed by its components in reading order, so resolved components appear while the rest of the response is still arriving.
-
-A follow-up such as **“Focus on their final ten laps”** triggers a new tool call with the same drivers and laps 48 through 57. Gateway then streams the updated chart.
+The route runs `query_lap_times` whenever the model calls it and sends the result back, until the model answers. It streams the answer to Agent Interface as the model writes it, and **Behind the scenes** shows each tool call. Earlier turns come from the Gateway conversation rather than the browser, so every earlier result the model sees is one your server produced. The [chat route](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts) has the details, including error handling.
## Verify it works
In the browser:
-1. Ask for the five fastest drivers. Expand **Behind the scenes** to inspect `query_lap_times` and its result.
+1. Ask for the five fastest drivers. Expand **Behind the scenes** to inspect the `query_lap_times` call and its arguments.
2. Ask for the Norris/Verstappen comparison. Confirm the answer starts appearing while generation is still active.
3. Ask **“Focus on their final ten laps.”** Confirm the chart covers laps 48 through 57 and retains both drivers.
4. Click a follow-up suggestion under an answer. Confirm the new answer keeps the drivers and laps from the conversation.
5. Stop a generation and ask another question to check recovery.
+6. Reload the page and open an earlier thread. Confirm its messages load.
-Generated layouts can vary. Check values against the tool result. Missing data and tool errors should produce an explanation rather than invented points.
+Generated layouts can vary. Check values against the race data in `data/f1.sqlite`. Missing data and tool errors should produce an explanation rather than invented points.
## Adapt it to your data
Replace `queryLapTimes` with a query to your database or API. Update the tool's arguments and description, then add any components your answers need to `src/library.ts` and regenerate the specification.
-This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples. With any of these backends, you can still keep threads in Gateway conversations, as described in [Connect Agent Interface](#4-connect-agent-interface).
+This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
+
+This example runs locally without authentication. Before deploying it, add [authentication](/docs/gateway/authentication), limits on request size, and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/conversational-analytics) for the implementation notes.
-This example runs locally without authentication, and its chat route accepts browser requests only from its own page. Before deploying it, add authentication and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/conversational-analytics) for the implementation notes.
+## References
-- [Agent Interface quickstart](/docs/agent/getting-started/quickstart)
-- [Agent tools](/docs/agent/core-concepts/tools)
-- [Gateway Chat Completions API](/docs/gateway/api/chat-completions)
+- [`@openuidev/react-ui`](/docs/api-reference/react-ui): `AgentInterface` and the built-in component libraries.
+- [`@openuidev/react-headless`](/docs/api-reference/react-headless): `fetchLLM()`, `openAIReadableStreamAdapter()`, and `useOpenuiCloudStorage()`, which the example imports through `@openuidev/react-ui`.
+- [`@openuidev/react-lang`](/docs/api-reference/react-lang): `createLibrary()`.
+- [`@openuidev/lang-core`](/docs/openui-lang/system-prompts): `generateSystemPrompt()`.
+- [`@openuidev/server`](/docs/api-reference/server#conversation-history): `storeChatCompletionHistory()`.
+- [`@openuidev/cli`](/docs/api-reference/cli): `openui generate`.
+- [OpenAI SDK](https://github.com/openai/openai-node): `runTools()` and `toReadableStream()`.
+- [Gateway Chat Completions API](/docs/gateway/api/chat-completions).
+- [Agent Interface quickstart](/docs/agent/getting-started/quickstart).
+- [Agent tools](/docs/agent/core-concepts/tools).
Data source: [OpenF1](https://openf1.org/docs/), race session `9507`. OpenF1 is an independent project, unaffiliated with Formula 1.
diff --git a/docs/content/docs/cookbooks/document-comparison.mdx b/docs/content/docs/cookbooks/document-comparison.mdx
index 0df33355a..a882139d4 100644
--- a/docs/content/docs/cookbooks/document-comparison.mdx
+++ b/docs/content/docs/cookbooks/document-comparison.mdx
@@ -116,7 +116,7 @@ Each step covers one part of the example, in the order a request flows through i
`npm run prepare:documents` downloads each report listed in [documents.ts](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/document-comparison/src/lib/documents.ts) and extracts its text page by page. It then splits each page into overlapping passages, so every passage keeps the page it came from:
```ts title="scripts/prepare-documents.ts"
-// Split each page into overlapping passages so every passage keeps its page number.
+// Split each page into overlapping passages that keep their page number.
function passages(text: string, size = 1200, overlap = 200) {
const clean = text.replace(/\s+/g, " ").trim();
const result: string[] = [];
@@ -150,7 +150,10 @@ const results = selected.map((document) => {
const url = sources.find((source) => source.id === document.id)?.url;
const matches = passages
.filter((passage) => passage.documentId === document.id)
- .map((passage) => ({ ...passage, score: similarity(queryEmbedding, passage.embedding) }))
+ .map((passage) => ({
+ ...passage,
+ score: similarity(queryEmbedding, passage.embedding),
+ }))
.sort((a, b) => b.score - a.score)
.slice(0, args.passages_per_document);
const bestScore = matches[0]?.score ?? 0;
@@ -166,7 +169,7 @@ const results = selected.map((document) => {
});
```
-Results are grouped by document, so every document is represented even when one report discusses the criterion at greater length than the others. `found` is false when a document's best match falls below a similarity of 0.3, which usually means the report does not discuss the criterion. Each passage's `url` adds `#page=` to the PDF's address, which opens most PDF viewers at that page, so the answer can link to its evidence. Agent Interface shows each call and its passages in the **Behind the scenes** timeline.
+Results are grouped by document, so every document is represented even when one report discusses the criterion at greater length than the others. `found` is false when a document's best match falls below a similarity of 0.3, which usually means the report does not discuss the criterion. Each passage's `url` adds `#page=` to the PDF's address, which opens most PDF viewers at that page, so the answer can link to its evidence. Agent Interface shows each search and its arguments in the **Behind the scenes** timeline.
The example keeps all 1,564 embeddings in memory and compares them in JavaScript, which takes a few milliseconds. For thousands of documents, store the embeddings in a vector database instead; the tool's arguments and result stay the same.
@@ -224,19 +227,30 @@ Each card shows the site's icon, the company and page, and the quote. `onePerPag
### 4. Customize Agent Interface
-Connect generation to the local chat route with `fetchLLM`. It sends the thread's messages in Chat Completions format and reads the route's stream with `agUIAdapter()`:
+Connect generation to the local chat route with `fetchLLM`. It sends the thread's messages in Chat Completions format and reads the route's stream with `openAIReadableStreamAdapter()`:
```tsx title="src/components/comparison-chat.tsx"
const llm = fetchLLM({
url: "/api/chat",
- streamAdapter: agUIAdapter(),
+ streamAdapter: openAIReadableStreamAdapter(),
messageFormat: openAIMessageFormat,
});
+
+const storage = useOpenuiCloudStorage({
+ token: "/api/frontend-token",
+ features: { artifact: false },
+});
```
-Chat Completions does not store conversations, so Agent Interface keeps each thread in the browser and sends its messages with every question. That is what lets a follow-up add a criterion to the comparison. Threads last until the page reloads. To keep them, pass a `storage` adapter to Agent Interface; see [Connect a backend](/docs/agent/reference/self-hosting#3-persist-conversations).
+Chat Completions does not store conversations, so the chat route loads each thread's earlier turns from Gateway, with their searches and passages, and sends them with every question. That is what lets a follow-up add a criterion to the comparison.
+
+<Callout type="info" title="Thread storage">
+
+`useOpenuiCloudStorage()` keeps the thread list in Gateway, and the chat route saves each turn, tool calls included, with [`storeChatCompletionHistory()`](/docs/api-reference/server#conversation-history), so threads and their messages stay after a reload.
+
+</Callout>
-The example also customizes Agent Interface through its public props and slots:
+The example also customizes Agent Interface through its public props and slots. The props set the theme, brand, and starters:
```tsx title="src/components/comparison-chat.tsx"
const mode = useSystemThemeMode();
@@ -244,6 +258,7 @@ const theme = useMemo(() => ({ mode, lightTheme, darkTheme }), [mode]);
<AgentInterface
llm={llm}
+ storage={storage}
componentLibrary={library}
agentName="Filing analyst"
logoUrl="/logo.svg"
@@ -251,31 +266,42 @@ const theme = useMemo(() => ({ mode, lightTheme, darkTheme }), [mode]);
starters={starters}
starterVariant="long"
>
- <AgentInterface.Sidebar>
- <AgentInterface.SidebarHeader />
- <AgentInterface.SidebarContent>
- <AgentInterface.NewChatButton />
- <AgentInterface.SidebarItem path="documents" icon={<FileText size={16} />}>
- Documents
- </AgentInterface.SidebarItem>
- <AgentInterface.SidebarSeparator />
- <AgentInterface.ThreadList />
- </AgentInterface.SidebarContent>
- </AgentInterface.Sidebar>
- <AgentInterface.Route path="documents">
- <DocumentLibrary />
- </AgentInterface.Route>
- <AgentInterface.ThreadHeader>
- <span className="thread-context">Comparing NVIDIA · AMD · Intel annual reports</span>
- </AgentInterface.ThreadHeader>
+ {/* The slots below */}
</AgentInterface>;
```
- **Theme.** [theme.ts](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/document-comparison/src/lib/theme.ts) uses `createTheme` to set the accent and user-message colors for light and dark mode, and `useSystemThemeMode` follows the operating system's setting.
- **Brand.** `agentName` and `logoUrl` fill the default sidebar header, which keeps the logo in the collapsed sidebar. [logo.svg](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/document-comparison/public/logo.svg) switches colors for dark mode with a `prefers-color-scheme` media query.
+- **Starters.** `starterVariant="long"` shows starters as a list with icons. See [Welcome and starters](/docs/agent/customize/welcome-and-starters).
+
+Its children replace the sidebar, add the Documents page, and fill the thread header:
+
+```tsx title="src/components/comparison-chat.tsx"
+<AgentInterface.Sidebar>
+ <AgentInterface.SidebarHeader />
+ <AgentInterface.SidebarContent>
+ <AgentInterface.NewChatButton />
+ <AgentInterface.SidebarItem path="documents" icon={<FileText size={16} />}>
+ Documents
+ </AgentInterface.SidebarItem>
+ <AgentInterface.SidebarSeparator />
+ <AgentInterface.ThreadList />
+ </AgentInterface.SidebarContent>
+</AgentInterface.Sidebar>
+
+<AgentInterface.Route path="documents">
+ <DocumentLibrary />
+</AgentInterface.Route>
+
+<AgentInterface.ThreadHeader>
+ <span className="thread-context">
+ Comparing NVIDIA · AMD · Intel annual reports
+ </span>
+</AgentInterface.ThreadHeader>
+```
+
- **Sidebar.** Supplying `AgentInterface.Sidebar` replaces the default sidebar, so the example composes its own header, New chat button, Documents item, and thread list. See [Sidebar](/docs/agent/customize/sidebar).
- **Pages.** A `SidebarItem` with a `path` opens the matching `AgentInterface.Route` in place of the chat. The Documents page lists each report with its page count and a link to the source PDF, and returns to the chat with `useNav`.
-- **Starters.** `starterVariant="long"` shows starters as a list with icons. See [Welcome and starters](/docs/agent/customize/welcome-and-starters).
### 5. Stream the answer
@@ -283,34 +309,36 @@ The chat route passes the search tool and the [prompt](https://github.com/thesys
```ts title="src/app/api/chat/route.ts"
const searchTool = searchDocumentsTool(documents);
-const params = {
- model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
- messages: [
- { role: "system" as const, content: comparisonPrompt(documents) },
- ...conversation(body.messages),
- ],
- tools: [searchTool],
- max_completion_tokens: 6000,
-};
-const firstStream = await gateway.chat.completions.create(
- { ...params, stream: true },
- { signal: request.signal },
+const runner = gateway.chat.completions.runTools(
+ {
+ model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
+ messages: [
+ { role: "system", content: comparisonPrompt(documents) },
+ ...thread,
+ ],
+ tools: [
+ {
+ type: "function",
+ function: {
+ ...searchTool.function,
+ function: (args: string) =>
+ executeSearchDocuments(args, { signal: request.signal }).catch(
+ (error: unknown) =>
+ JSON.stringify({
+ error: error instanceof Error ? error.message : String(error),
+ }),
+ ),
+ },
+ },
+ ],
+ max_completion_tokens: 6000,
+ stream: true,
+ },
+ { signal: request.signal, maxChatCompletions: 4 },
);
-
-await runChatToolLoop({
- client: gateway,
- params,
- firstStream,
- tools: { [searchTool.function.name]: executeSearchDocuments },
- emit,
- signal: request.signal,
- maxRounds: 4,
-});
```
-The route runs the same [function-tool loop](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/document-comparison/src/lib/tool-loop.ts) as the [conversational analytics cookbook](/cookbooks/conversational-analytics#5-stream-the-answer), with `maxRounds: 4`. It runs each requested search, appends the results, and requests the next completion until the model answers, streaming AG-UI events so Agent Interface shows each search and its passages. The extra rounds let the model search again with different wording when a document returns `found: false`. `conversation()` drops the tool calls and results the browser sends back, so every quote comes from a search your server ran for the current question.
-
-This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
+When the model asks for a search, the route runs search_documents and sends the passages back to the model. This repeats until the model stops searching and writes its answer. maxChatCompletions: 4 caps the number of rounds, so a question can't turn into an endless string of searches. If a report comes back with found: false, the model can use one of those rounds to search that report again with different wording.
The prompt turns the evidence into a consistent answer:
@@ -330,7 +358,8 @@ In the browser:
3. Ask **“How has R&D spending changed over three years?”** and **“Break down revenue by segment.”** Confirm the first uses a line chart, and the second a single bar chart with a table row per segment.
4. Ask **“Compare each CEO's total compensation.”** Annual reports refer readers to the proxy statement for executive pay, so the table should say “Not found” with a callout explaining why, and no chart.
5. Open **Documents** in the sidebar and confirm it lists the three reports with their page counts.
-6. Switch your operating system between light and dark mode, and confirm the theme follows.
+6. Reload the page and open an earlier thread. Confirm its messages load.
+7. Switch your operating system between light and dark mode, and confirm the theme follows.
Generated layouts can vary. Values should always match a quoted passage.
@@ -340,11 +369,23 @@ Add your own PDFs to the example's `documents/` folder and run `npm run prepare:
The importer reads a PDF's text layer, so run OCR on scanned documents first. For large collections, store the embeddings in a vector database and keep the `search_documents` tool's contract.
-This example runs locally without authentication, and its chat route accepts browser requests only from its own page. Before deploying it, add authentication and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/document-comparison) for the implementation notes.
+This example calls Gateway directly from a Next.js route, but the tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK. Agent Interface stays the same and reads the framework's stream with the matching adapter. See our [LangGraph Platform](/docs/agent/agent-runtimes/langgraph-platform), [Vercel AI SDK](/docs/agent/agent-runtimes/vercel-ai-sdk), and [Vercel Eve](/docs/agent/agent-runtimes/vercel-eve) integrations, or the [Mastra](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/mastra) and [Google ADK](https://github.com/thesysdev/openui/tree/main/examples/agent-frameworks/google-adk) examples.
-- [Agent Interface quickstart](/docs/agent/getting-started/quickstart)
-- [Agent tools](/docs/agent/core-concepts/tools)
-- [Gateway Chat Completions API](/docs/gateway/api/chat-completions)
-- [Connect a backend](/docs/agent/reference/self-hosting)
+This example runs locally without authentication. Before deploying it, add [authentication](/docs/gateway/authentication), limits on request size, and rate limits. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/document-comparison) for the implementation notes.
+
+## References
+
+- [`@openuidev/react-ui`](/docs/api-reference/react-ui): `AgentInterface` and the built-in component libraries.
+- [`@openuidev/react-headless`](/docs/api-reference/react-headless): `fetchLLM()`, `openAIReadableStreamAdapter()`, and `useOpenuiCloudStorage()`, which the example imports through `@openuidev/react-ui`.
+- [`@openuidev/react-lang`](/docs/api-reference/react-lang): `createLibrary()` and `defineComponent()`.
+- [`@openuidev/lang-core`](/docs/openui-lang/system-prompts): `generateSystemPrompt()`.
+- [`@openuidev/server`](/docs/api-reference/server#conversation-history): `storeChatCompletionHistory()`.
+- [`@openuidev/cli`](/docs/api-reference/cli): `openui generate`.
+- [OpenAI SDK](https://github.com/openai/openai-node): `runTools()`, `toReadableStream()`, and embeddings.
+- [`unpdf`](https://github.com/unjs/unpdf): PDF text extraction.
+- [Gateway Chat Completions API](/docs/gateway/api/chat-completions).
+- [Agent Interface quickstart](/docs/agent/getting-started/quickstart).
+- [Agent tools](/docs/agent/core-concepts/tools).
+- [Connect a backend](/docs/agent/reference/self-hosting).
Documents: the Form 10-K annual reports of NVIDIA, AMD, and Intel, downloaded from each company's investor relations site during setup. They are not included in this repository.
diff --git a/examples/cookbooks/booking-assistant/.env.example b/examples/cookbooks/booking-assistant/.env.example
index b017e01ad..a6277add6 100644
--- a/examples/cookbooks/booking-assistant/.env.example
+++ b/examples/cookbooks/booking-assistant/.env.example
@@ -2,3 +2,5 @@
# Configure THESYS_API_KEY privately in .env.local to enable OpenUI Gateway generation.
# Optional: set OPENUI_MODEL to a supported provider/model identifier.
# Default model: openai/gpt-5.5
+# Optional: DEMO_USER_ID and APP_ID set the Gateway identity for stored threads.
+# Defaults: demo-user and booking-assistant-cookbook.
diff --git a/examples/cookbooks/booking-assistant/README.md b/examples/cookbooks/booking-assistant/README.md
index 2fb9c9c4d..f3a607a2f 100644
--- a/examples/cookbooks/booking-assistant/README.md
+++ b/examples/cookbooks/booking-assistant/README.md
@@ -36,18 +36,19 @@ Try:
## Files
-| File | Purpose |
-| --------------------------------- | --------------------------------------------------------------------- |
-| `src/lib/trivago.ts` | MCP client for trivago's accommodation search, and its filter options |
-| `src/lib/tools/search-stays.ts` | Function schema, argument validation, budget filter, and results |
-| `src/library.ts` | Shared components for the prompt and renderer |
-| `src/components/date-picker.tsx` | A DatePicker that the model can prefill with YYYY-MM-DD dates |
-| `src/lib/prompt.ts` | Booking rules and one example for each step of the flow |
-| `src/app/api/chat/route.ts` | Request validation, Chat Completions generation, and SSE response |
-| `src/lib/tool-loop.ts` | Chat Completions function-tool loop that streams AG-UI events |
-| `src/lib/theme.ts` | Light and dark theme overrides |
-| `src/components/booking-chat.tsx` | Agent Interface, chat transport, theme, starters, and thread header |
-| `src/app/styles.css` | Page layout and full-width photos on the stay cards |
+| File | Purpose |
+| ------------------------------------- | --------------------------------------------------------------------- |
+| `src/lib/trivago.ts` | MCP client for trivago's accommodation search, and its filter options |
+| `src/lib/tools/search-stays.ts` | Function schema, argument validation, budget filter, and results |
+| `src/library.ts` | Shared components for the prompt and renderer |
+| `src/components/date-picker.tsx` | A DatePicker that the model can prefill with YYYY-MM-DD dates |
+| `src/lib/prompt.ts` | Booking rules and one example for each step of the flow |
+| `src/lib/gateway-history.ts` | Loads a thread's stored turns from Gateway as chat messages |
+| `src/app/api/chat/route.ts` | `runTools()` generation, streaming, and turn storage |
+| `src/app/api/frontend-token/route.ts` | Frontend token for Gateway thread storage |
+| `src/lib/theme.ts` | Light and dark theme overrides |
+| `src/components/booking-chat.tsx` | Agent Interface, chat transport, thread storage, theme, and starters |
+| `src/app/styles.css` | Page layout and full-width photos on the stay cards |
`npm run generate` creates the ignored component specification before dev/build/verify. The server passes that specification to `generateSystemPrompt({ cloud: true, library: spec, promptOptions })`, and Agent Interface renders responses with the same component library.
@@ -65,13 +66,15 @@ React UI's `DatePicker` stores `Date` objects, which a model cannot write and wh
## Conversations
-The OpenAI SDK sends requests to `https://api.thesys.dev/v1/embed/chat/completions` using `THESYS_API_KEY`. Chat Completions does not store conversations, so Agent Interface keeps each thread in memory and `fetchLLM` sends its messages with every turn. Threads reset when the page reloads; pass a `storage` adapter to Agent Interface to persist them.
+The OpenAI SDK sends requests to `https://api.thesys.dev/v1/embed/chat/completions` using `THESYS_API_KEY`. Chat Completions does not store conversations, so the chat route stores each turn in the thread's Gateway conversation and loads the earlier turns from there for every turn.
-The chat route forwards only user messages and assistant answers from the browser. It drops browser-supplied tool calls and results, so the model sees only search results the server produced for the current turn. Later steps therefore use what the stay cards show: each card's value is the stay's booking link, so choosing a card sends the link back with the form, and the summary's **Continue to booking** button opens it. A submitted form arrives as one message with the form's values, so the route accepts user messages of up to 4,000 characters.
+Agent Interface stores the thread list with Gateway's [Conversations API](https://www.openui.com/docs/gateway/api/conversations) through `useOpenuiCloudStorage()`. The browser calls Gateway directly with a short-lived [frontend token](https://www.openui.com/docs/gateway/authentication#frontend-tokens) from `/api/frontend-token`, which mints it with `THESYS_API_KEY` for one local user (`DEMO_USER_ID`, default `demo-user`) and app (`APP_ID`, default `booking-assistant-cookbook`), so the key stays on the server and the browser reaches only those threads. Chat Completions doesn't write turns to a conversation, so the chat route appends each turn, including the tool calls and their results, with `storeChatCompletionHistory()` from [`@openuidev/server`](https://www.openui.com/docs/api-reference/server#conversation-history). A stopped or failed answer still keeps the user's message. Threads stay listed after a reload, and a thread you open again loads its messages. To keep threads in your own database instead, use `restStorage`.
-The tool loop streams AG-UI events, which `agUIAdapter()` reads, because Chat Completions has no chunk for a tool result. It is the same loop as in the [conversational analytics](../conversational-analytics) cookbook. The tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK; see the [agent runtime integrations](https://www.openui.com/docs/agent/agent-runtimes/langgraph-platform) and the [agent framework examples](../../agent-frameworks).
+The chat route uses only the new message from the browser. `loadChatCompletionHistory()` in `src/lib/gateway-history.ts` loads the earlier turns from the thread's Gateway conversation, including their searches and results, and the response ends once the turn is stored, so the next step finds it. Each stay card's value is the stay's booking link, so choosing a card sends the link back with the form, and the summary's **Continue to booking** button opens it. A submitted form arrives as one message with the form's values.
-The app binds to loopback, and the chat route accepts browser requests only from its own local page. For deployment, add authentication and rate limits to the chat route.
+The route runs the tool with the OpenAI SDK's [`runTools()`](https://github.com/openai/openai-node#automated-function-calls) and returns the runner's `toReadableStream()`, one JSON chunk per line, which `openAIReadableStreamAdapter()` reads. Chat Completions has no chunk for a tool result, so in a live answer **Behind the scenes** shows each call's arguments but not its result. The tool and prompt can also run on an agent framework such as LangGraph, the Vercel AI SDK, Mastra, or Google ADK; see the [agent runtime integrations](https://www.openui.com/docs/agent/agent-runtimes/langgraph-platform) and the [agent framework examples](../../agent-frameworks).
+
+The app binds to loopback, and every browser shares one local user's threads. For deployment, add [authentication](https://www.openui.com/docs/gateway/authentication), mint each frontend token for the signed-in user, check that each `threadId` belongs to that user before storing a turn in it, and add request-size and rate limits to both routes.
## Verify
diff --git a/examples/cookbooks/booking-assistant/package-lock.json b/examples/cookbooks/booking-assistant/package-lock.json
index ab16586de..bb17ba225 100644
--- a/examples/cookbooks/booking-assistant/package-lock.json
+++ b/examples/cookbooks/booking-assistant/package-lock.json
@@ -13,6 +13,7 @@
"@openuidev/react-headless": "0.16.3",
"@openuidev/react-lang": "0.3.0",
"@openuidev/react-ui": "0.16.3",
+ "@openuidev/server": "0.1.0",
"lucide-react": "^0.575.0",
"next": "16.2.6",
"openai": "^6.49.0",
@@ -2048,6 +2049,18 @@
"react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
}
},
+ "node_modules/@openuidev/server": {
+ "version": "0.1.0",
+ "resolved": "https://registry.npmjs.org/@openuidev/server/-/server-0.1.0.tgz",
+ "integrity": "sha512-Cm7nejELDHw0PoPlY67C4EW6b7DYx1ZnyCYyO5J6SIs6JjSBrY7rNzrnwB3DhAf4LmgO5sN/1WiD94BdZTNLPQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@openuidev/lang-core": "^0.3.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/@posthog/core": {
"version": "1.55.2",
"resolved": "https://registry.npmjs.org/@posthog/core/-/core-1.55.2.tgz",
diff --git a/examples/cookbooks/booking-assistant/package.json b/examples/cookbooks/booking-assistant/package.json
index 73b7811dd..97e6b2ca8 100644
--- a/examples/cookbooks/booking-assistant/package.json
+++ b/examples/cookbooks/booking-assistant/package.json
@@ -19,6 +19,7 @@
"@openuidev/react-headless": "0.16.3",
"@openuidev/react-lang": "0.3.0",
"@openuidev/react-ui": "0.16.3",
+ "@openuidev/server": "0.1.0",
"lucide-react": "^0.575.0",
"next": "16.2.6",
"openai": "^6.49.0",
diff --git a/examples/cookbooks/booking-assistant/pnpm-lock.yaml b/examples/cookbooks/booking-assistant/pnpm-lock.yaml
index 0e6acf723..c22755c60 100644
--- a/examples/cookbooks/booking-assistant/pnpm-lock.yaml
+++ b/examples/cookbooks/booking-assistant/pnpm-lock.yaml
@@ -23,6 +23,9 @@ importers:
'@openuidev/react-ui':
specifier: 0.16.3
+ '@openuidev/server':
+ specifier: 0.1.0
+ version: 0.1.0(@modelcontextprotocol/[email protected]([email protected]))([email protected])
lucide-react:
specifier: ^0.575.0
version: 0.575.0([email protected])
@@ -671,6 +674,10 @@ packages:
zod: ^3.25.0 || ^4.0.0
zustand: ^4.5.5
+ '@openuidev/[email protected]':
+ resolution: {integrity: sha512-Cm7nejELDHw0PoPlY67C4EW6b7DYx1ZnyCYyO5J6SIs6JjSBrY7rNzrnwB3DhAf4LmgO5sN/1WiD94BdZTNLPQ==}
+ engines: {node: '>=18'}
+
'@posthog/[email protected]':
resolution: {integrity: sha512-2mYxGbDmTLUs096VbcZqSWo0lrI48/BrX65r54NynxxFq409BOx9w73HxOAtOKZ1vblkdV6/GxQTe7KDcIQidg==}
@@ -2941,6 +2948,13 @@ snapshots:
- '@types/react-dom'
- supports-color
+ dependencies:
+ '@openuidev/lang-core': 0.3.0(@modelcontextprotocol/[email protected]([email protected]))([email protected])
+ transitivePeerDependencies:
+ - '@modelcontextprotocol/sdk'
+ - zod
+
'@posthog/[email protected]':
dependencies:
'@posthog/types': 1.412.4
diff --git a/examples/cookbooks/booking-assistant/src/app/api/chat/route.ts b/examples/cookbooks/booking-assistant/src/app/api/chat/route.ts
index 1c1f98bbc..6853460c5 100644
--- a/examples/cookbooks/booking-assistant/src/app/api/chat/route.ts
+++ b/examples/cookbooks/booking-assistant/src/app/api/chat/route.ts
@@ -1,118 +1,99 @@
+import { storeChatCompletionHistory } from "@openuidev/server/openai";
import OpenAI from "openai";
-import type {
- ChatCompletionChunk,
- ChatCompletionMessageParam,
-} from "openai/resources/chat/completions";
-import { z } from "zod/v4";
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import { loadChatCompletionHistory } from "../../../lib/gateway-history";
import { bookingPrompt } from "../../../lib/prompt";
-import { runChatToolLoop } from "../../../lib/tool-loop";
import { executeSearchStays, searchStaysTool, today } from "../../../lib/tools/search-stays";
export const runtime = "nodejs";
-// Chat Completions keeps no state, so the browser sends the whole conversation on every turn.
-// Forward only user messages and assistant answers. Tool calls and results from the browser
-// are dropped, so every stay the model shows comes from a search this server runs.
-// A submitted form arrives as the button label plus the form's values, so user messages can be
-// longer than a typed question.
-const chatRequestSchema = z.object({
- messages: z
- .array(
- z.discriminatedUnion("role", [
- z.object({ role: z.literal("user"), content: z.string().trim().min(1).max(4000) }),
- z.object({ role: z.literal("assistant"), content: z.string().nullish() }),
- z.object({ role: z.literal("tool") }),
- ]),
- )
- .min(1)
- .max(100)
- .refine((messages) => messages.at(-1)?.role === "user"),
-});
-
-function conversation(messages: z.infer<typeof chatRequestSchema>["messages"]) {
- return messages.flatMap((message): ChatCompletionMessageParam[] =>
- message.role === "tool" || !message.content
- ? []
- : [{ role: message.role, content: message.content }],
- );
-}
-
-async function parseChatRequest(request: Request) {
- if (request.headers.get("content-type")?.split(";")[0].trim() !== "application/json")
- throw new Error("Send JSON.");
- const reader = request.body?.getReader();
- if (!reader) throw new Error("Send a message.");
- const chunks: Uint8Array[] = [];
- let size = 0;
- try {
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
- size += value.byteLength;
- if (size > 1_000_000) {
- await reader.cancel();
- throw new Error("Request too large.");
- }
- chunks.push(value);
- }
- } finally {
- reader.releaseLock();
- }
- return chatRequestSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+// The thread's earlier turns, loaded from its Gateway conversation with their tool calls and
+// results rather than taken from the browser, so the model sees where each earlier answer came
+// from. To send less of a long thread, compact the messages here.
+function conversation(apiKey: string, threadId: string, signal: AbortSignal) {
+ return loadChatCompletionHistory({ apiKey, conversationId: threadId, signal });
}
export async function POST(request: Request) {
- // This example has no authentication, so it accepts browser requests only from its own
- // local page. Add authentication and rate limits before deploying it.
- const { port } = new URL(request.url);
- const origin = request.headers.get("origin");
- if (origin && origin !== `http://127.0.0.1:${port}` && origin !== `http://localhost:${port}`)
- return Response.json(
- { error: "This example only accepts requests from its local chat interface." },
- { status: 403 },
- );
- let body;
- try {
- body = await parseChatRequest(request);
- } catch {
+ // Agent Interface's storage creates the Gateway conversation first and sends its id as threadId.
+ // The browser sends the whole thread; only its last message, the new question, is used.
+ const { threadId, messages: sent } = (await request.json()) as {
+ threadId?: string;
+ messages?: ChatCompletionMessageParam[];
+ };
+ const question = sent?.at(-1);
+ if (!threadId || question?.role !== "user")
return Response.json(
- { error: "Send the conversation, ending with a message of up to 4,000 characters." },
+ { error: "Send a threadId and the thread's messages, ending with the user's." },
{ status: 400 },
);
- }
const apiKey = process.env.THESYS_API_KEY;
- if (!apiKey)
- return Response.json(
- {
- error:
- "Configure THESYS_API_KEY privately in .env.local and restart to use OpenUI Gateway.",
- },
- { status: 503 },
- );
+ if (!apiKey) throw new Error("Set THESYS_API_KEY in .env.local, then restart.");
const gateway = new OpenAI({ apiKey, baseURL: "https://api.thesys.dev/v1/embed" });
- // App-owned function tools. The loop runs only the names registered here.
const searchTool = searchStaysTool();
- const functionTools = { [searchTool.function.name]: executeSearchStays };
- const params = {
- model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
- messages: [
- { role: "system" as const, content: bookingPrompt(today()) },
- ...conversation(body.messages),
- ],
- tools: [searchTool],
- max_completion_tokens: 6000,
- };
+ const thread = [...(await conversation(apiKey, threadId, request.signal)), question];
+ const messages: ChatCompletionMessageParam[] = [
+ { role: "system", content: bookingPrompt(today()) },
+ ...thread,
+ ];
- // Open the first round before responding, so a rejected key, rate limit, or unknown model
- // returns as an HTTP error with Gateway's status instead of an event mid-stream.
- let firstStream: AsyncIterable<ChatCompletionChunk>;
- try {
- firstStream = await gateway.chat.completions.create(
- { ...params, stream: true },
- { signal: request.signal },
+ // runTools requests a completion, runs the tools the model calls, sends their results back, and
+ // repeats until the model answers. It runs only the tools registered here.
+ const runner = gateway.chat.completions.runTools(
+ {
+ model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
+ messages,
+ tools: [
+ {
+ type: "function",
+ function: {
+ ...searchTool.function,
+ // runTools ends the run when a tool throws, so return the error as the tool's result.
+ function: (args: string) =>
+ executeSearchStays(args, { signal: request.signal }).catch((error: unknown) =>
+ JSON.stringify({ error: error instanceof Error ? error.message : String(error) }),
+ ),
+ },
+ },
+ ],
+ max_completion_tokens: 6000,
+ stream: true,
+ },
+ { signal: request.signal, maxChatCompletions: 3 },
+ );
+
+ // Chat Completions doesn't write to the conversation, so store this turn when the run ends: the
+ // user's message, then each message the run adds, which are the tool calls, their results, and
+ // the answer. Agent Interface loads them when the thread is opened again. A stopped or failed
+ // run still stores the user's message and whatever finished before it ended.
+ const turn: ChatCompletionMessageParam[] = [question];
+ runner.on("message", (message) => turn.push(message));
+ const stored = runner
+ .done()
+ .catch(() => {})
+ .then(() => storeChatCompletionHistory({ apiKey, conversationId: threadId, messages: turn }))
+ .catch((error: unknown) =>
+ console.error("Could not store the turn in the Gateway conversation.", error),
);
+
+ // The runner's stream carries every completion's chunks, one JSON object per line, and Agent
+ // Interface reads it with openAIReadableStreamAdapter(). It ends once the turn is stored, so a
+ // follow-up loads it. Creating it now means no chunk is missed while the route waits below.
+ const stream = runner.toReadableStream().pipeThrough(
+ new TransformStream({
+ async flush() {
+ await stored;
+ },
+ }),
+ );
+
+ // Wait for the first chunk, so a rejected key, rate limit, or unknown model returns as an HTTP
+ // error with Gateway's message instead of failing mid-stream. Gateway reports some errors, such
+ // as an unknown model, inside a successful response, so waiting for the response isn't enough.
+ try {
+ await Promise.race([runner.emitted("chunk"), runner.done()]);
} catch (error) {
const upstream = error as { status?: number; message?: string };
return Response.json(
@@ -121,44 +102,7 @@ export async function POST(request: Request) {
);
}
- // Stream AG-UI events to the browser, running app-owned tools between model turns.
- const encoder = new TextEncoder();
- let open = true;
- const stream = new ReadableStream<Uint8Array>({
- async start(controller) {
- // Stop sending once the browser disconnects.
- const emit = (event: Record<string, unknown>) => {
- if (open) controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
- };
- try {
- await runChatToolLoop({
- client: gateway,
- params,
- firstStream,
- tools: functionTools,
- emit,
- signal: request.signal,
- maxRounds: 3,
- });
- } catch (error) {
- emit({
- type: "RUN_ERROR",
- message: error instanceof Error ? error.message : String(error),
- });
- } finally {
- if (open) controller.close();
- }
- },
- cancel() {
- open = false;
- },
- });
-
return new Response(stream, {
- headers: {
- "Content-Type": "text/event-stream",
- "Cache-Control": "no-cache, no-transform",
- Connection: "keep-alive",
- },
+ headers: { "Content-Type": "application/x-ndjson", "Cache-Control": "no-cache, no-transform" },
});
}
diff --git a/examples/cookbooks/booking-assistant/src/app/api/frontend-token/route.ts b/examples/cookbooks/booking-assistant/src/app/api/frontend-token/route.ts
new file mode 100644
index 000000000..e302a18f3
--- /dev/null
+++ b/examples/cookbooks/booking-assistant/src/app/api/frontend-token/route.ts
@@ -0,0 +1,33 @@
+export const runtime = "nodejs";
+
+// Mints the short-lived frontend token that useOpenuiCloudStorage() sends with its
+// Conversations API calls. Gateway scopes the token to one user and app, so the browser
+// reaches only those threads and never sees THESYS_API_KEY.
+export async function POST(request: Request) {
+ const apiKey = process.env.THESYS_API_KEY;
+ if (!apiKey) throw new Error("Set THESYS_API_KEY in .env.local, then restart.");
+
+ const upstream = await fetch("https://api.thesys.dev/v1/frontend-tokens", {
+ method: "POST",
+ headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+ body: JSON.stringify({
+ // There is no sign-in, so every browser shares one local user, as in apps from
+ // `openui create`. Use the signed-in user's id instead when you add authentication:
+ // https://www.openui.com/docs/gateway/authentication
+ user_id: process.env.DEMO_USER_ID || "demo-user",
+ // Keeps this example's threads apart from other apps that use the same key.
+ app_id: process.env.APP_ID || "booking-assistant-cookbook",
+ }),
+ signal: request.signal,
+ });
+ if (!upstream.ok)
+ return Response.json(
+ { error: "OpenUI Gateway could not create a frontend token." },
+ { status: upstream.status },
+ );
+ const { token, expires_at } = (await upstream.json()) as { token: string; expires_at: number };
+ return Response.json(
+ { token, expires_at },
+ { headers: { "Cache-Control": "private, no-store" } },
+ );
+}
diff --git a/examples/cookbooks/booking-assistant/src/components/booking-chat.tsx b/examples/cookbooks/booking-assistant/src/components/booking-chat.tsx
index 22938c4a6..9e159ff36 100644
--- a/examples/cookbooks/booking-assistant/src/components/booking-chat.tsx
+++ b/examples/cookbooks/booking-assistant/src/components/booking-chat.tsx
@@ -2,9 +2,10 @@
import {
AgentInterface,
- agUIAdapter,
fetchLLM,
openAIMessageFormat,
+ openAIReadableStreamAdapter,
+ useOpenuiCloudStorage,
useSystemThemeMode,
} from "@openuidev/react-ui";
import { Briefcase, CalendarDays, Users, Wallet } from "lucide-react";
@@ -12,10 +13,10 @@ import { useMemo } from "react";
import { darkTheme, lightTheme } from "../lib/theme";
import { library } from "../library";
-// Send the thread's messages in Chat Completions format and read the route's AG-UI events.
+// Send the thread's messages in Chat Completions format and read the runner's stream from the route.
const llm = fetchLLM({
url: "/api/chat",
- streamAdapter: agUIAdapter(),
+ streamAdapter: openAIReadableStreamAdapter(),
messageFormat: openAIMessageFormat,
});
@@ -47,10 +48,18 @@ const starters = [
export default function BookingChat() {
const mode = useSystemThemeMode();
const theme = useMemo(() => ({ mode, lightTheme, darkTheme }), [mode]);
+ // Store threads as Gateway conversations, which the browser reaches with a short-lived token
+ // from /api/frontend-token. The chat route appends each turn to the thread's conversation, so
+ // a thread opened again loads its messages.
+ const storage = useOpenuiCloudStorage({
+ token: "/api/frontend-token",
+ features: { artifact: false },
+ });
return (
<div className="booking-app">
<AgentInterface
llm={llm}
+ storage={storage}
componentLibrary={library}
agentName="Stay finder"
logoUrl="/logo.svg"
diff --git a/examples/cookbooks/booking-assistant/src/lib/gateway-history.ts b/examples/cookbooks/booking-assistant/src/lib/gateway-history.ts
new file mode 100644
index 000000000..0be9f71c3
--- /dev/null
+++ b/examples/cookbooks/booking-assistant/src/lib/gateway-history.ts
@@ -0,0 +1,70 @@
+import type {
+ ChatCompletionMessageFunctionToolCall,
+ ChatCompletionMessageParam,
+} from "openai/resources/chat/completions";
+
+// A conversation item, in the shape storeChatCompletionHistory() stores it.
+type ConversationItem = {
+ type: string;
+ role?: string;
+ content?: { text?: string }[];
+ call_id?: string;
+ name?: string;
+ arguments?: string;
+ output?: string;
+};
+
+// Loads a thread's stored turns from its Gateway conversation as Chat Completions messages, the
+// reverse of storeChatCompletionHistory(): questions, answers, tool calls, and tool results.
+export async function loadChatCompletionHistory(options: {
+ apiKey: string;
+ conversationId: string;
+ signal?: AbortSignal;
+}): Promise<ChatCompletionMessageParam[]> {
+ const items: ConversationItem[] = [];
+ let after: string | undefined;
+ do {
+ const query = new URLSearchParams({ order: "asc", limit: "100" });
+ if (after) query.set("after", after);
+ const response = await fetch(
+ `https://api.thesys.dev/v1/conversations/${encodeURIComponent(options.conversationId)}/items?${query}`,
+ { headers: { Authorization: `Bearer ${options.apiKey}` }, signal: options.signal },
+ );
+ if (!response.ok) throw new Error(`Could not load the thread from Gateway: ${response.status}`);
+ const page = (await response.json()) as {
+ data: ConversationItem[];
+ has_more: boolean;
+ last_id: string;
+ };
+ items.push(...page.data);
+ after = page.has_more ? page.last_id : undefined;
+ } while (after);
+ return toChatMessages(items);
+}
+
+function toChatMessages(items: ConversationItem[]) {
+ // Chat Completions rejects a tool call without a result, so drop the calls of a stopped run.
+ const answered = new Set(
+ items.flatMap((item) => (item.type === "function_call_output" ? [item.call_id] : [])),
+ );
+ const messages: ChatCompletionMessageParam[] = [];
+ for (const item of items) {
+ if (item.type === "message" && (item.role === "user" || item.role === "assistant")) {
+ const text = (item.content ?? []).map((part) => part.text ?? "").join("");
+ if (text) messages.push({ role: item.role, content: text });
+ } else if (item.type === "function_call" && item.call_id && answered.has(item.call_id)) {
+ const call: ChatCompletionMessageFunctionToolCall = {
+ id: item.call_id,
+ type: "function",
+ function: { name: item.name ?? "", arguments: item.arguments ?? "{}" },
+ };
+ // A completion's text and its tool calls make up one assistant message.
+ const last = messages.at(-1);
+ if (last?.role === "assistant") (last.tool_calls ??= []).push(call);
+ else messages.push({ role: "assistant", content: null, tool_calls: [call] });
+ } else if (item.type === "function_call_output" && item.call_id) {
+ messages.push({ role: "tool", tool_call_id: item.call_id, content: item.output ?? "" });
+ }
+ }
+ return messages;
+}
diff --git a/examples/cookbooks/booking-assistant/src/lib/prompt.ts b/examples/cookbooks/booking-assistant/src/lib/prompt.ts
index 2cdfb45d9..99e2f8b5e 100644
--- a/examples/cookbooks/booking-assistant/src/lib/prompt.ts
+++ b/examples/cookbooks/booking-assistant/src/lib/prompt.ts
@@ -55,7 +55,7 @@ export function bookingPrompt(today: string) {
library: spec,
promptOptions: {
additionalRules: [
- `You help people find and book a stay anywhere, with live prices from trivago. Today is ${weekday}, ${today}. search_stays is a Responses function tool executed by the application server, not an OpenUI Query or Mutation expression.`,
+ `You help people find and book a stay anywhere, with live prices from trivago. Today is ${weekday}, ${today}. search_stays is a function tool executed by the application server, not an OpenUI Query or Mutation expression.`,
`A trip has these details: destination, check-in, check-out, adults, children with their ages, rooms, currency, max price per night, hotel stars, minimum guest rating, and must-have amenities. Destination, dates, and adults are required; the rest are optional. Guest ratings: ${guestRatings.join(", ")} or any. Amenities: ${JSON.stringify(amenities)}.`,
"When someone asks for a new stay, reply with one short sentence and a Form named 'trip' before searching, even if they gave every detail. Prefill every field they mentioned with a literal value, never a $variable. Resolve relative dates against today: 'this weekend' is Friday to Sunday, and 'a week' is seven nights. Leave details they did not mention empty or at 'any'. Add a FormControl hint only to a value you inferred, such as dates worked out from 'this weekend'.",
"Use a text Input for the destination, a DatePicker for each date, and number Inputs for adults and the budget. Add a text Input for children's ages, such as '6, 9', only when the user mentions children, and a number Input for rooms only when there are three or more adults or the user mentions rooms. Use Chips with type 'multiple' for stars and amenities, and Chips with type 'single' for the guest rating. Mark destination, dates, and adults {required: true}. Give the form a primary 'Find stays' button.",
diff --git a/examples/cookbooks/booking-assistant/src/lib/tool-loop.ts b/examples/cookbooks/booking-assistant/src/lib/tool-loop.ts
deleted file mode 100644
index ba00e6177..000000000
--- a/examples/cookbooks/booking-assistant/src/lib/tool-loop.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type OpenAI from "openai";
-import type {
- ChatCompletionChunk,
- ChatCompletionCreateParamsStreaming,
- ChatCompletionMessageParam,
-} from "openai/resources/chat/completions";
-
-/**
- * Function-tool loop for the OpenUI Gateway Chat Completions API.
- *
- * Chat Completions returns function calls to the application instead of running
- * them. Each round streams one completion. When the model requests tools, the
- * loop runs them, appends the assistant's tool-call message and one `tool`
- * message per call, and requests the next completion. It ends when the model
- * answers without requesting a tool. The last allowed round sets
- * `tool_choice: "none"` so the model must answer in text.
- *
- * The browser receives AG-UI events rather than raw completion chunks, because
- * Chat Completions has no chunk for a tool result. Agent Interface reads them
- * with `agUIAdapter()` and shows each call with its result.
- */
-
-export type FunctionToolExecutor = (
- argsJson: string,
- ctx: { signal?: AbortSignal },
-) => Promise<string>;
-
-export interface RunChatToolLoopOptions {
- client: OpenAI;
- /** The completion request; `messages` holds the system prompt and the conversation. */
- params: Omit<ChatCompletionCreateParamsStreaming, "stream">;
- /**
- * The already-open stream of the first round, created from `params`. Opening it
- * before responding lets the route return Gateway's errors as HTTP errors.
- */
- firstStream: AsyncIterable<ChatCompletionChunk>;
- /** name → executor. A call to any other name receives an error result. */
- tools: Record<string, FunctionToolExecutor>;
- /** Receives every AG-UI event to forward to the browser. */
- emit: (event: Record<string, unknown>) => void;
- /** Propagates browser aborts into executors and model requests. */
- signal?: AbortSignal;
- /** Cap on model requests per question (default 5). */
- maxRounds?: number;
-}
-
-type ToolCall = { id: string; name: string; arguments: string };
-
-export async function runChatToolLoop(options: RunChatToolLoopOptions): Promise<void> {
- const { client, tools, emit, signal, maxRounds = 5 } = options;
- const messages: ChatCompletionMessageParam[] = [...options.params.messages];
-
- for (let round = 0; round < maxRounds; round++) {
- const lastRound = round === maxRounds - 1;
- const stream =
- round === 0
- ? options.firstStream
- : await client.chat.completions.create(
- {
- ...options.params,
- messages,
- stream: true,
- ...(lastRound ? { tool_choice: "none" as const } : {}),
- },
- { signal },
- );
-
- const messageId = randomUUID();
- let text = "";
- const calls: ToolCall[] = [];
- for await (const chunk of stream) {
- const delta = chunk.choices[0]?.delta;
- if (delta?.content) {
- if (!text) emit({ type: "TEXT_MESSAGE_START", messageId, role: "assistant" });
- text += delta.content;
- emit({ type: "TEXT_MESSAGE_CONTENT", messageId, delta: delta.content });
- }
- // Each call streams as indexed deltas: its id and name first, then argument fragments.
- // The last round ignores calls, in case a model does not honor tool_choice.
- for (const part of lastRound ? [] : (delta?.tool_calls ?? [])) {
- let call = calls[part.index];
- if (!call) {
- call = { id: part.id ?? "", name: part.function?.name ?? "", arguments: "" };
- calls[part.index] = call;
- emit({
- type: "TOOL_CALL_START",
- toolCallId: call.id,
- toolCallName: call.name,
- parentMessageId: messageId,
- });
- }
- if (part.function?.arguments) {
- call.arguments += part.function.arguments;
- emit({ type: "TOOL_CALL_ARGS", toolCallId: call.id, delta: part.function.arguments });
- }
- }
- }
- if (text) emit({ type: "TEXT_MESSAGE_END", messageId });
-
- const requested = calls.filter(Boolean);
- if (requested.length === 0) {
- if (!text) throw new Error("The model returned no answer. Please retry.");
- return;
- }
-
- messages.push({
- role: "assistant",
- content: text || null,
- tool_calls: requested.map((call) => ({
- id: call.id,
- type: "function",
- function: { name: call.name, arguments: call.arguments },
- })),
- });
- for (const call of requested) emit({ type: "TOOL_CALL_END", toolCallId: call.id });
- // A throwing executor settles as an error result rather than aborting the run.
- for (const call of requested) {
- let content: string;
- try {
- const execute = Object.hasOwn(tools, call.name) ? tools[call.name] : undefined;
- if (!execute) throw new Error(`Unknown tool: ${call.name}`);
- content = await execute(call.arguments, { signal });
- } catch (error) {
- content = JSON.stringify({ error: error instanceof Error ? error.message : String(error) });
- }
- messages.push({ role: "tool", tool_call_id: call.id, content });
- emit({
- type: "TOOL_CALL_RESULT",
- messageId: randomUUID(),
- toolCallId: call.id,
- content,
- role: "tool",
- });
- }
- }
-}
diff --git a/examples/cookbooks/booking-assistant/src/lib/tools/search-stays.ts b/examples/cookbooks/booking-assistant/src/lib/tools/search-stays.ts
index e89e7605e..98aca84a8 100644
--- a/examples/cookbooks/booking-assistant/src/lib/tools/search-stays.ts
+++ b/examples/cookbooks/booking-assistant/src/lib/tools/search-stays.ts
@@ -8,7 +8,7 @@ import {
} from "../trivago";
// The search_stays function tool: its JSON schema for Gateway, argument validation, the trivago
-// search, and the executor the tool loop calls.
+// search, and the executor that runTools() calls.
// Today's date where the server runs, as YYYY-MM-DD.
export const today = () => new Intl.DateTimeFormat("en-CA").format(new Date());
diff --git a/examples/cookbooks/conversational-analytics/.env.example b/examples/cookbooks/conversational-analytics/.env.example
index b017e01ad..79d3455bd 100644
--- a/examples/cookbooks/conversational-analytics/.env.example
+++ b/examples/cookbooks/conversational-analytics/.env.example
@@ -2,3 +2,5 @@
# Configure THESYS_API_KEY privately in .env.local to enable OpenUI Gateway generation.
# Optional: set OPENUI_MODEL to a supported provider/model identifier.
# Default model: openai/gpt-5.5
+# Optional: DEMO_USER_ID and APP_ID set the Gateway identity for stored threads.
+# Defaults: demo-user and conversational-analytics-cookbook.
diff --git a/examples/cookbooks/conversational-analytics/README.md b/examples/cookbooks/conversational-analytics/README.md
index 845b16ed4..b1b096260 100644
--- a/examples/cookbooks/conversational-analytics/README.md
+++ b/examples/cookbooks/conversational-analytics/README.md
@@ -32,33 +32,36 @@ Try:
1. Agent Interface sends the thread's messages to `/api/chat`.
2. The server calls OpenUI Gateway's Chat Completions API, which requests `query_lap_times` with a view, driver numbers, and lap range.
3. The server validates the arguments and queries the local SQLite snapshot.
-4. The tool loop returns the result to Gateway and streams tool events and generated OpenUI Lang to the browser.
+4. `runTools()` returns the result to Gateway, and the route streams the tool calls and generated OpenUI Lang to the browser.
5. Agent Interface displays tool activity and progressively renders the visual answer.
The tool supports `fastest_laps` (one best recorded lap per driver) and `lap_times` (one to four drivers on matching lap numbers). Rankings can include all drivers by passing an empty `driver_numbers` array. The final ten race laps are 48 through 57. Comparisons include absolute times and a per-lap difference from the first selected driver, so the UI can show small differences clearly.
## Files
-| File | Purpose |
-| ----------------------------------- | ------------------------------------------------------------- |
-| `scripts/prepare-data.ts` | Download OpenF1's race snapshot and prepare SQLite |
-| `src/lib/f1-data.ts` | Source validation, importer, database, and driver catalog |
-| `src/lib/tools/lap-times.ts` | Function schema, argument validation, and read-only query |
-| `src/library.ts` | Shared components for the prompt and renderer |
-| `src/lib/prompt.ts` | Gateway instructions and the supported data scope |
-| `src/app/api/chat/route.ts` | Request validation, Gateway generation, and SSE response |
-| `src/lib/tool-loop.ts` | Chat Completions function-tool loop that streams AG-UI events |
-| `src/components/analytics-chat.tsx` | Agent Interface, chat transport, and starters |
+| File | Purpose |
+| ------------------------------------- | ------------------------------------------------------------- |
+| `scripts/prepare-data.ts` | Download OpenF1's race snapshot and prepare SQLite |
+| `src/lib/f1-data.ts` | Source validation, importer, database, and driver catalog |
+| `src/lib/tools/lap-times.ts` | Function schema, argument validation, and read-only query |
+| `src/library.ts` | Shared components for the prompt and renderer |
+| `src/lib/prompt.ts` | Gateway instructions and the supported data scope |
+| `src/lib/gateway-history.ts` | Loads a thread's stored turns from Gateway as chat messages |
+| `src/app/api/chat/route.ts` | `runTools()` generation, streaming, and turn storage |
+| `src/app/api/frontend-token/route.ts` | Frontend token for Gateway thread storage |
+| `src/components/analytics-chat.tsx` | Agent Interface, chat transport, thread storage, and starters |
`npm run generate` creates the ignored component specification before dev/build/verify. The server passes that specification to `generateSystemPrompt({ cloud: true, library: spec, promptOptions })`, and Agent Interface renders responses with the same component library.
## Conversations
-The OpenAI SDK sends requests to `https://api.thesys.dev/v1/embed/chat/completions` using `THESYS_API_KEY`. Chat Completions does not store conversations, so Agent Interface keeps each thread in memory and `fetchLLM` sends its messages with every question. Follow-up suggestions are sent the same way, so they build on the earlier answers. Threads reset when the page reloads. To persist them, pass a `storage` adapter to Agent Interface: `useOpenuiCloudStorage()` for threads stored with Gateway's [Conversations API](https://www.openui.com/docs/gateway/api/conversations), which works with custom backends such as the Gateway-backed LangGraph and Vercel AI SDK templates from `openui create`, or `restStorage` for threads in your own database.
+The OpenAI SDK sends requests to `https://api.thesys.dev/v1/embed/chat/completions` using `THESYS_API_KEY`. Chat Completions does not store conversations, so the chat route stores each turn in the thread's Gateway conversation and loads the earlier turns from there for every question. Follow-up suggestions are sent the same way, so they build on the earlier answers.
-The chat route forwards only user questions and assistant answers from the browser. It drops browser-supplied tool calls and results, so the model sees only query results the server produced for the current question. The tool loop streams AG-UI events, which `agUIAdapter()` reads, because Chat Completions has no chunk for a tool result.
+Agent Interface stores the thread list with Gateway's [Conversations API](https://www.openui.com/docs/gateway/api/conversations) through `useOpenuiCloudStorage()`. The browser calls Gateway directly with a short-lived [frontend token](https://www.openui.com/docs/gateway/authentication#frontend-tokens) from `/api/frontend-token`, which mints it with `THESYS_API_KEY` for one local user (`DEMO_USER_ID`, default `demo-user`) and app (`APP_ID`, default `conversational-analytics-cookbook`), so the key stays on the server and the browser reaches only those threads. Chat Completions doesn't write turns to a conversation, so the chat route appends each turn, including the tool calls and their results, with `storeChatCompletionHistory()` from [`@openuidev/server`](https://www.openui.com/docs/api-reference/server#conversation-history). A stopped or failed answer still keeps the user's message. Threads stay listed after a reload, and a thread you open again loads its messages. To keep threads in your own database instead, use `restStorage`.
-The app binds to loopback, and the chat route accepts browser requests only from its own local page. For deployment, add authentication and rate limits to the chat route, and provide persistent SQLite storage or a hosted database for the race data. Gateway receives the conversation, component/tool instructions, driver catalog, and requested query results.
+The chat route uses only the new question from the browser. `loadChatCompletionHistory()` in `src/lib/gateway-history.ts` loads the earlier turns from the thread's Gateway conversation, including their tool calls and results, so the model sees where each earlier answer came from, and every result it sees came from this server. The response ends once the turn is stored, so a follow-up finds it. The route runs the tool with the OpenAI SDK's [`runTools()`](https://github.com/openai/openai-node#automated-function-calls) and returns the runner's `toReadableStream()`, one JSON chunk per line, which `openAIReadableStreamAdapter()` reads. Chat Completions has no chunk for a tool result, so in a live answer **Behind the scenes** shows each call's arguments but not its result.
+
+The app binds to loopback, and every browser shares one local user's threads. For deployment, add [authentication](https://www.openui.com/docs/gateway/authentication), mint each frontend token for the signed-in user, check that each `threadId` belongs to that user before storing a turn in it, add request-size and rate limits to both routes, and provide persistent SQLite storage or a hosted database for the race data. Gateway receives the conversation, component/tool instructions, driver catalog, and requested query results.
## Data notes
diff --git a/examples/cookbooks/conversational-analytics/package-lock.json b/examples/cookbooks/conversational-analytics/package-lock.json
index ff3b4aba8..605212578 100644
--- a/examples/cookbooks/conversational-analytics/package-lock.json
+++ b/examples/cookbooks/conversational-analytics/package-lock.json
@@ -12,6 +12,7 @@
"@openuidev/react-headless": "0.16.3",
"@openuidev/react-lang": "0.3.0",
"@openuidev/react-ui": "0.16.3",
+ "@openuidev/server": "0.1.0",
"next": "16.2.6",
"openai": "^6.49.0",
"react": "19.2.4",
@@ -1995,6 +1996,18 @@
"react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
}
},
+ "node_modules/@openuidev/server": {
+ "version": "0.1.0",
+ "resolved": "https://registry.npmjs.org/@openuidev/server/-/server-0.1.0.tgz",
+ "integrity": "sha512-Cm7nejELDHw0PoPlY67C4EW6b7DYx1ZnyCYyO5J6SIs6JjSBrY7rNzrnwB3DhAf4LmgO5sN/1WiD94BdZTNLPQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@openuidev/lang-core": "^0.3.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/@posthog/core": {
"version": "1.55.2",
"resolved": "https://registry.npmjs.org/@posthog/core/-/core-1.55.2.tgz",
diff --git a/examples/cookbooks/conversational-analytics/package.json b/examples/cookbooks/conversational-analytics/package.json
index 34ec84629..e62182adb 100644
--- a/examples/cookbooks/conversational-analytics/package.json
+++ b/examples/cookbooks/conversational-analytics/package.json
@@ -19,6 +19,7 @@
"@openuidev/react-headless": "0.16.3",
"@openuidev/react-lang": "0.3.0",
"@openuidev/react-ui": "0.16.3",
+ "@openuidev/server": "0.1.0",
"next": "16.2.6",
"openai": "^6.49.0",
"react": "19.2.4",
diff --git a/examples/cookbooks/conversational-analytics/pnpm-lock.yaml b/examples/cookbooks/conversational-analytics/pnpm-lock.yaml
index a100a152d..2712f21e9 100644
--- a/examples/cookbooks/conversational-analytics/pnpm-lock.yaml
+++ b/examples/cookbooks/conversational-analytics/pnpm-lock.yaml
@@ -20,6 +20,9 @@ importers:
'@openuidev/react-ui':
specifier: 0.16.3
+ '@openuidev/server':
+ specifier: 0.1.0
+ version: 0.1.0([email protected])
next:
specifier: 16.2.6
@@ -808,6 +811,10 @@ packages:
zod: ^3.25.0 || ^4.0.0
zustand: ^4.5.5
+ '@openuidev/[email protected]':
+ resolution: {integrity: sha512-Cm7nejELDHw0PoPlY67C4EW6b7DYx1ZnyCYyO5J6SIs6JjSBrY7rNzrnwB3DhAf4LmgO5sN/1WiD94BdZTNLPQ==}
+ engines: {node: '>=18'}
+
'@posthog/[email protected]':
resolution: {integrity: sha512-2mYxGbDmTLUs096VbcZqSWo0lrI48/BrX65r54NynxxFq409BOx9w73HxOAtOKZ1vblkdV6/GxQTe7KDcIQidg==}
@@ -2838,6 +2845,13 @@ snapshots:
- '@types/react-dom'
- supports-color
+ dependencies:
+ '@openuidev/lang-core': 0.3.0([email protected])
+ transitivePeerDependencies:
+ - '@modelcontextprotocol/sdk'
+ - zod
+
'@posthog/[email protected]':
dependencies:
'@posthog/types': 1.412.4
diff --git a/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts b/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts
index 403e8ebcd..f111b264b 100644
--- a/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts
+++ b/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts
@@ -1,130 +1,104 @@
+import { storeChatCompletionHistory } from "@openuidev/server/openai";
import OpenAI from "openai";
-import type {
- ChatCompletionChunk,
- ChatCompletionMessageParam,
-} from "openai/resources/chat/completions";
-import { z } from "zod/v4";
-import { listDrivers, openDatabase, type Driver } from "../../../lib/f1-data";
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import { listDrivers, openDatabase } from "../../../lib/f1-data";
+import { loadChatCompletionHistory } from "../../../lib/gateway-history";
import { analyticsPrompt } from "../../../lib/prompt";
-import { runChatToolLoop } from "../../../lib/tool-loop";
import { executeQueryLapTimes, queryLapTimesTool } from "../../../lib/tools/lap-times";
export const runtime = "nodejs";
-// Chat Completions keeps no state, so the browser sends the whole conversation on every turn.
-// Forward only user questions and assistant answers. Tool calls and results from the browser
-// are dropped, so every value the model uses comes from a query this server runs.
-const chatRequestSchema = z.object({
- messages: z
- .array(
- z.discriminatedUnion("role", [
- z.object({ role: z.literal("user"), content: z.string().trim().min(1).max(600) }),
- z.object({ role: z.literal("assistant"), content: z.string().nullish() }),
- z.object({ role: z.literal("tool") }),
- ]),
- )
- .min(1)
- .max(100)
- .refine((messages) => messages.at(-1)?.role === "user"),
-});
-
-function conversation(messages: z.infer<typeof chatRequestSchema>["messages"]) {
- return messages.flatMap((message): ChatCompletionMessageParam[] =>
- message.role === "tool" || !message.content
- ? []
- : [{ role: message.role, content: message.content }],
- );
-}
-
-async function parseChatRequest(request: Request) {
- if (request.headers.get("content-type")?.split(";")[0].trim() !== "application/json")
- throw new Error("Send JSON.");
- const reader = request.body?.getReader();
- if (!reader) throw new Error("Send a question.");
- const chunks: Uint8Array[] = [];
- let size = 0;
- try {
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
- size += value.byteLength;
- if (size > 1_000_000) {
- await reader.cancel();
- throw new Error("Request too large.");
- }
- chunks.push(value);
- }
- } finally {
- reader.releaseLock();
- }
- return chatRequestSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+// The thread's earlier turns, loaded from its Gateway conversation with their tool calls and
+// results rather than taken from the browser, so the model sees where each earlier answer came
+// from. To send less of a long thread, compact the messages here.
+function conversation(apiKey: string, threadId: string, signal: AbortSignal) {
+ return loadChatCompletionHistory({ apiKey, conversationId: threadId, signal });
}
export async function POST(request: Request) {
- // This example has no authentication, so it accepts browser requests only from its own
- // local page. Add authentication and rate limits before deploying it.
- const { port } = new URL(request.url);
- const origin = request.headers.get("origin");
- if (origin && origin !== `http://127.0.0.1:${port}` && origin !== `http://localhost:${port}`)
- return Response.json(
- { error: "This example only accepts requests from its local chat interface." },
- { status: 403 },
- );
- let body;
- try {
- body = await parseChatRequest(request);
- } catch {
+ // Agent Interface's storage creates the Gateway conversation first and sends its id as threadId.
+ // The browser sends the whole thread; only its last message, the new question, is used.
+ const { threadId, messages: sent } = (await request.json()) as {
+ threadId?: string;
+ messages?: ChatCompletionMessageParam[];
+ };
+ const question = sent?.at(-1);
+ if (!threadId || question?.role !== "user")
return Response.json(
- { error: "Send the conversation, ending with a question of up to 600 characters." },
+ { error: "Send a threadId and the thread's messages, ending with the user's." },
{ status: 400 },
);
- }
const apiKey = process.env.THESYS_API_KEY;
- if (!apiKey)
- return Response.json(
- {
- error:
- "Configure THESYS_API_KEY privately in .env.local and restart to use OpenUI Gateway.",
- },
- { status: 503 },
- );
+ if (!apiKey) throw new Error("Set THESYS_API_KEY in .env.local, then restart.");
- let drivers: Driver[];
- let db;
- try {
- db = openDatabase();
- drivers = listDrivers(db);
- } catch {
- return Response.json(
- { error: "Prepare the race data with npm run prepare:data before asking a question." },
- { status: 503 },
- );
- } finally {
- db?.close();
- }
+ const db = openDatabase();
+ const drivers = listDrivers(db);
+ db.close();
const gateway = new OpenAI({ apiKey, baseURL: "https://api.thesys.dev/v1/embed" });
- // App-owned function tools. The loop runs only the names registered here.
const lapTimesTool = queryLapTimesTool(drivers);
- const functionTools = { [lapTimesTool.function.name]: executeQueryLapTimes };
- const params = {
- model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
- messages: [
- { role: "system" as const, content: analyticsPrompt(drivers) },
- ...conversation(body.messages),
- ],
- tools: [lapTimesTool],
- max_completion_tokens: 6000,
- };
- // Open the first round before responding, so a rejected key, rate limit, or unknown model
- // returns as an HTTP error with Gateway's status instead of an event mid-stream.
- let firstStream: AsyncIterable<ChatCompletionChunk>;
- try {
- firstStream = await gateway.chat.completions.create(
- { ...params, stream: true },
- { signal: request.signal },
+ const thread = [...(await conversation(apiKey, threadId, request.signal)), question];
+ const messages: ChatCompletionMessageParam[] = [
+ { role: "system", content: analyticsPrompt(drivers) },
+ ...thread,
+ ];
+
+ // runTools requests a completion, runs the tools the model calls, sends their results back, and
+ // repeats until the model answers. It runs only the tools registered here.
+ const runner = gateway.chat.completions.runTools(
+ {
+ model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
+ messages,
+ tools: [
+ {
+ type: "function",
+ function: {
+ ...lapTimesTool.function,
+ // runTools ends the run when a tool throws, so return the error as the tool's result.
+ function: (args: string) =>
+ executeQueryLapTimes(args, { signal: request.signal }).catch((error: unknown) =>
+ JSON.stringify({ error: error instanceof Error ? error.message : String(error) }),
+ ),
+ },
+ },
+ ],
+ max_completion_tokens: 6000,
+ stream: true,
+ },
+ { signal: request.signal, maxChatCompletions: 3 },
+ );
+
+ // Chat Completions doesn't write to the conversation, so store this turn when the run ends: the
+ // user's message, then each message the run adds, which are the tool calls, their results, and
+ // the answer. Agent Interface loads them when the thread is opened again. A stopped or failed
+ // run still stores the user's message and whatever finished before it ended.
+ const turn: ChatCompletionMessageParam[] = [question];
+ runner.on("message", (message) => turn.push(message));
+ const stored = runner
+ .done()
+ .catch(() => {})
+ .then(() => storeChatCompletionHistory({ apiKey, conversationId: threadId, messages: turn }))
+ .catch((error: unknown) =>
+ console.error("Could not store the turn in the Gateway conversation.", error),
);
+
+ // The runner's stream carries every completion's chunks, one JSON object per line, and Agent
+ // Interface reads it with openAIReadableStreamAdapter(). It ends once the turn is stored, so a
+ // follow-up loads it. Creating it now means no chunk is missed while the route waits below.
+ const stream = runner.toReadableStream().pipeThrough(
+ new TransformStream({
+ async flush() {
+ await stored;
+ },
+ }),
+ );
+
+ // Wait for the first chunk, so a rejected key, rate limit, or unknown model returns as an HTTP
+ // error with Gateway's message instead of failing mid-stream. Gateway reports some errors, such
+ // as an unknown model, inside a successful response, so waiting for the response isn't enough.
+ try {
+ await Promise.race([runner.emitted("chunk"), runner.done()]);
} catch (error) {
const upstream = error as { status?: number; message?: string };
return Response.json(
@@ -133,44 +107,7 @@ export async function POST(request: Request) {
);
}
- // Stream AG-UI events to the browser, running app-owned tools between model turns.
- const encoder = new TextEncoder();
- let open = true;
- const stream = new ReadableStream<Uint8Array>({
- async start(controller) {
- // Stop sending once the browser disconnects.
- const emit = (event: Record<string, unknown>) => {
- if (open) controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
- };
- try {
- await runChatToolLoop({
- client: gateway,
- params,
- firstStream,
- tools: functionTools,
- emit,
- signal: request.signal,
- maxRounds: 3,
- });
- } catch (error) {
- emit({
- type: "RUN_ERROR",
- message: error instanceof Error ? error.message : String(error),
- });
- } finally {
- if (open) controller.close();
- }
- },
- cancel() {
- open = false;
- },
- });
-
return new Response(stream, {
- headers: {
- "Content-Type": "text/event-stream",
- "Cache-Control": "no-cache, no-transform",
- Connection: "keep-alive",
- },
+ headers: { "Content-Type": "application/x-ndjson", "Cache-Control": "no-cache, no-transform" },
});
}
diff --git a/examples/cookbooks/conversational-analytics/src/app/api/frontend-token/route.ts b/examples/cookbooks/conversational-analytics/src/app/api/frontend-token/route.ts
new file mode 100644
index 000000000..64e124225
--- /dev/null
+++ b/examples/cookbooks/conversational-analytics/src/app/api/frontend-token/route.ts
@@ -0,0 +1,33 @@
+export const runtime = "nodejs";
+
+// Mints the short-lived frontend token that useOpenuiCloudStorage() sends with its
+// Conversations API calls. Gateway scopes the token to one user and app, so the browser
+// reaches only those threads and never sees THESYS_API_KEY.
+export async function POST(request: Request) {
+ const apiKey = process.env.THESYS_API_KEY;
+ if (!apiKey) throw new Error("Set THESYS_API_KEY in .env.local, then restart.");
+
+ const upstream = await fetch("https://api.thesys.dev/v1/frontend-tokens", {
+ method: "POST",
+ headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+ body: JSON.stringify({
+ // There is no sign-in, so every browser shares one local user, as in apps from
+ // `openui create`. Use the signed-in user's id instead when you add authentication:
+ // https://www.openui.com/docs/gateway/authentication
+ user_id: process.env.DEMO_USER_ID || "demo-user",
+ // Keeps this example's threads apart from other apps that use the same key.
+ app_id: process.env.APP_ID || "conversational-analytics-cookbook",
+ }),
+ signal: request.signal,
+ });
+ if (!upstream.ok)
+ return Response.json(
+ { error: "OpenUI Gateway could not create a frontend token." },
+ { status: upstream.status },
+ );
+ const { token, expires_at } = (await upstream.json()) as { token: string; expires_at: number };
+ return Response.json(
+ { token, expires_at },
+ { headers: { "Cache-Control": "private, no-store" } },
+ );
+}
diff --git a/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx b/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx
index df965d237..058f3f8b6 100644
--- a/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx
+++ b/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx
@@ -2,17 +2,18 @@
import {
AgentInterface,
- agUIAdapter,
fetchLLM,
openAIMessageFormat,
+ openAIReadableStreamAdapter,
+ useOpenuiCloudStorage,
type ThemeProps,
} from "@openuidev/react-ui";
import { library } from "../library";
-// Send the thread's messages in Chat Completions format and read the route's AG-UI events.
+// Send the thread's messages in Chat Completions format and read the runner's stream from the route.
const llm = fetchLLM({
url: "/api/chat",
- streamAdapter: agUIAdapter(),
+ streamAdapter: openAIReadableStreamAdapter(),
messageFormat: openAIMessageFormat,
});
@@ -36,10 +37,18 @@ const starters = [
];
export default function AnalyticsChat() {
+ // Store threads as Gateway conversations, which the browser reaches with a short-lived token
+ // from /api/frontend-token. The chat route appends each turn to the thread's conversation, so
+ // a thread opened again loads its messages.
+ const storage = useOpenuiCloudStorage({
+ token: "/api/frontend-token",
+ features: { artifact: false },
+ });
return (
<div className="analytics-app">
<AgentInterface
llm={llm}
+ storage={storage}
componentLibrary={library}
agentName="Data analyst"
theme={theme}
diff --git a/examples/cookbooks/conversational-analytics/src/lib/gateway-history.ts b/examples/cookbooks/conversational-analytics/src/lib/gateway-history.ts
new file mode 100644
index 000000000..0be9f71c3
--- /dev/null
+++ b/examples/cookbooks/conversational-analytics/src/lib/gateway-history.ts
@@ -0,0 +1,70 @@
+import type {
+ ChatCompletionMessageFunctionToolCall,
+ ChatCompletionMessageParam,
+} from "openai/resources/chat/completions";
+
+// A conversation item, in the shape storeChatCompletionHistory() stores it.
+type ConversationItem = {
+ type: string;
+ role?: string;
+ content?: { text?: string }[];
+ call_id?: string;
+ name?: string;
+ arguments?: string;
+ output?: string;
+};
+
+// Loads a thread's stored turns from its Gateway conversation as Chat Completions messages, the
+// reverse of storeChatCompletionHistory(): questions, answers, tool calls, and tool results.
+export async function loadChatCompletionHistory(options: {
+ apiKey: string;
+ conversationId: string;
+ signal?: AbortSignal;
+}): Promise<ChatCompletionMessageParam[]> {
+ const items: ConversationItem[] = [];
+ let after: string | undefined;
+ do {
+ const query = new URLSearchParams({ order: "asc", limit: "100" });
+ if (after) query.set("after", after);
+ const response = await fetch(
+ `https://api.thesys.dev/v1/conversations/${encodeURIComponent(options.conversationId)}/items?${query}`,
+ { headers: { Authorization: `Bearer ${options.apiKey}` }, signal: options.signal },
+ );
+ if (!response.ok) throw new Error(`Could not load the thread from Gateway: ${response.status}`);
+ const page = (await response.json()) as {
+ data: ConversationItem[];
+ has_more: boolean;
+ last_id: string;
+ };
+ items.push(...page.data);
+ after = page.has_more ? page.last_id : undefined;
+ } while (after);
+ return toChatMessages(items);
+}
+
+function toChatMessages(items: ConversationItem[]) {
+ // Chat Completions rejects a tool call without a result, so drop the calls of a stopped run.
+ const answered = new Set(
+ items.flatMap((item) => (item.type === "function_call_output" ? [item.call_id] : [])),
+ );
+ const messages: ChatCompletionMessageParam[] = [];
+ for (const item of items) {
+ if (item.type === "message" && (item.role === "user" || item.role === "assistant")) {
+ const text = (item.content ?? []).map((part) => part.text ?? "").join("");
+ if (text) messages.push({ role: item.role, content: text });
+ } else if (item.type === "function_call" && item.call_id && answered.has(item.call_id)) {
+ const call: ChatCompletionMessageFunctionToolCall = {
+ id: item.call_id,
+ type: "function",
+ function: { name: item.name ?? "", arguments: item.arguments ?? "{}" },
+ };
+ // A completion's text and its tool calls make up one assistant message.
+ const last = messages.at(-1);
+ if (last?.role === "assistant") (last.tool_calls ??= []).push(call);
+ else messages.push({ role: "assistant", content: null, tool_calls: [call] });
+ } else if (item.type === "function_call_output" && item.call_id) {
+ messages.push({ role: "tool", tool_call_id: item.call_id, content: item.output ?? "" });
+ }
+ }
+ return messages;
+}
diff --git a/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts b/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts
deleted file mode 100644
index ba00e6177..000000000
--- a/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type OpenAI from "openai";
-import type {
- ChatCompletionChunk,
- ChatCompletionCreateParamsStreaming,
- ChatCompletionMessageParam,
-} from "openai/resources/chat/completions";
-
-/**
- * Function-tool loop for the OpenUI Gateway Chat Completions API.
- *
- * Chat Completions returns function calls to the application instead of running
- * them. Each round streams one completion. When the model requests tools, the
- * loop runs them, appends the assistant's tool-call message and one `tool`
- * message per call, and requests the next completion. It ends when the model
- * answers without requesting a tool. The last allowed round sets
- * `tool_choice: "none"` so the model must answer in text.
- *
- * The browser receives AG-UI events rather than raw completion chunks, because
- * Chat Completions has no chunk for a tool result. Agent Interface reads them
- * with `agUIAdapter()` and shows each call with its result.
- */
-
-export type FunctionToolExecutor = (
- argsJson: string,
- ctx: { signal?: AbortSignal },
-) => Promise<string>;
-
-export interface RunChatToolLoopOptions {
- client: OpenAI;
- /** The completion request; `messages` holds the system prompt and the conversation. */
- params: Omit<ChatCompletionCreateParamsStreaming, "stream">;
- /**
- * The already-open stream of the first round, created from `params`. Opening it
- * before responding lets the route return Gateway's errors as HTTP errors.
- */
- firstStream: AsyncIterable<ChatCompletionChunk>;
- /** name → executor. A call to any other name receives an error result. */
- tools: Record<string, FunctionToolExecutor>;
- /** Receives every AG-UI event to forward to the browser. */
- emit: (event: Record<string, unknown>) => void;
- /** Propagates browser aborts into executors and model requests. */
- signal?: AbortSignal;
- /** Cap on model requests per question (default 5). */
- maxRounds?: number;
-}
-
-type ToolCall = { id: string; name: string; arguments: string };
-
-export async function runChatToolLoop(options: RunChatToolLoopOptions): Promise<void> {
- const { client, tools, emit, signal, maxRounds = 5 } = options;
- const messages: ChatCompletionMessageParam[] = [...options.params.messages];
-
- for (let round = 0; round < maxRounds; round++) {
- const lastRound = round === maxRounds - 1;
- const stream =
- round === 0
- ? options.firstStream
- : await client.chat.completions.create(
- {
- ...options.params,
- messages,
- stream: true,
- ...(lastRound ? { tool_choice: "none" as const } : {}),
- },
- { signal },
- );
-
- const messageId = randomUUID();
- let text = "";
- const calls: ToolCall[] = [];
- for await (const chunk of stream) {
- const delta = chunk.choices[0]?.delta;
- if (delta?.content) {
- if (!text) emit({ type: "TEXT_MESSAGE_START", messageId, role: "assistant" });
- text += delta.content;
- emit({ type: "TEXT_MESSAGE_CONTENT", messageId, delta: delta.content });
- }
- // Each call streams as indexed deltas: its id and name first, then argument fragments.
- // The last round ignores calls, in case a model does not honor tool_choice.
- for (const part of lastRound ? [] : (delta?.tool_calls ?? [])) {
- let call = calls[part.index];
- if (!call) {
- call = { id: part.id ?? "", name: part.function?.name ?? "", arguments: "" };
- calls[part.index] = call;
- emit({
- type: "TOOL_CALL_START",
- toolCallId: call.id,
- toolCallName: call.name,
- parentMessageId: messageId,
- });
- }
- if (part.function?.arguments) {
- call.arguments += part.function.arguments;
- emit({ type: "TOOL_CALL_ARGS", toolCallId: call.id, delta: part.function.arguments });
- }
- }
- }
- if (text) emit({ type: "TEXT_MESSAGE_END", messageId });
-
- const requested = calls.filter(Boolean);
- if (requested.length === 0) {
- if (!text) throw new Error("The model returned no answer. Please retry.");
- return;
- }
-
- messages.push({
- role: "assistant",
- content: text || null,
- tool_calls: requested.map((call) => ({
- id: call.id,
- type: "function",
- function: { name: call.name, arguments: call.arguments },
- })),
- });
- for (const call of requested) emit({ type: "TOOL_CALL_END", toolCallId: call.id });
- // A throwing executor settles as an error result rather than aborting the run.
- for (const call of requested) {
- let content: string;
- try {
- const execute = Object.hasOwn(tools, call.name) ? tools[call.name] : undefined;
- if (!execute) throw new Error(`Unknown tool: ${call.name}`);
- content = await execute(call.arguments, { signal });
- } catch (error) {
- content = JSON.stringify({ error: error instanceof Error ? error.message : String(error) });
- }
- messages.push({ role: "tool", tool_call_id: call.id, content });
- emit({
- type: "TOOL_CALL_RESULT",
- messageId: randomUUID(),
- toolCallId: call.id,
- content,
- role: "tool",
- });
- }
- }
-}
diff --git a/examples/cookbooks/conversational-analytics/src/lib/tools/lap-times.ts b/examples/cookbooks/conversational-analytics/src/lib/tools/lap-times.ts
index 15c88c63f..32d02c590 100644
--- a/examples/cookbooks/conversational-analytics/src/lib/tools/lap-times.ts
+++ b/examples/cookbooks/conversational-analytics/src/lib/tools/lap-times.ts
@@ -3,7 +3,7 @@ import { z } from "zod/v4";
import { listDrivers, openDatabase, race, type Driver } from "../f1-data";
// The query_lap_times function tool: its JSON schema for Gateway, argument validation,
-// the read-only query, and the executor the tool loop calls.
+// the read-only query, and the executor that runTools() calls.
export function queryLapTimesTool(drivers: Driver[]) {
return {
diff --git a/examples/cookbooks/document-comparison/.env.example b/examples/cookbooks/document-comparison/.env.example
index 7bf8ac556..72f03528d 100644
--- a/examples/cookbooks/document-comparison/.env.example
+++ b/examples/cookbooks/document-comparison/.env.example
@@ -4,3 +4,5 @@
# (https://platform.openai.com/api-keys). It embeds documents and questions.
# Optional: set OPENUI_MODEL to a supported provider/model identifier.
# Default model: openai/gpt-5.5
+# Optional: DEMO_USER_ID and APP_ID set the Gateway identity for stored threads.
+# Defaults: demo-user and document-comparison-cookbook.
diff --git a/examples/cookbooks/document-comparison/README.md b/examples/cookbooks/document-comparison/README.md
index 99a5d6c9a..8cfad0f8e 100644
--- a/examples/cookbooks/document-comparison/README.md
+++ b/examples/cookbooks/document-comparison/README.md
@@ -38,26 +38,27 @@ Try:
1. Agent Interface sends the thread's messages to `/api/chat`, which calls OpenUI Gateway's Chat Completions API.
2. The model calls `search_documents` once per criterion, with a short description of the information to find.
3. The server embeds the description, ranks each document's passages by similarity, and returns the closest ones with page numbers, links to those pages, and a `found` flag.
-4. The tool loop returns the passages to the model and streams tool events and generated OpenUI Lang to the browser as AG-UI events.
+4. `runTools()` returns the passages to the model, and the route streams the tool calls and generated OpenUI Lang to the browser.
5. Agent Interface displays tool activity and progressively renders the comparison: a page-cited table, charts, callouts for gaps and conflicts, and a card for each quoted page.
## Files
-| File | Purpose |
-| ------------------------------------- | ------------------------------------------------------------------------------ |
-| `scripts/prepare-documents.ts` | Download the PDFs, extract pages, split passages, embed, and store |
-| `src/lib/documents.ts` | Sample document sources, database schema, and document list |
-| `src/lib/embeddings.ts` | OpenAI embeddings and similarity |
-| `src/lib/tools/search-documents.ts` | Function schema, argument validation, and passage search |
-| `src/library.ts` | Shared components for the prompt and renderer |
-| `src/components/sources.tsx` | The Sources component, built on React UI's source strip |
-| `src/lib/prompt.ts` | Comparison rules and example answers for Gateway |
-| `src/app/api/chat/route.ts` | Request validation, Chat Completions generation, and SSE response |
-| `src/app/api/documents/route.ts` | Document list for the Documents page |
-| `src/lib/tool-loop.ts` | Chat Completions function-tool loop that streams AG-UI events |
-| `src/lib/theme.ts` | Light and dark theme overrides |
-| `src/components/comparison-chat.tsx` | Agent Interface, chat transport, custom sidebar, Documents route, and starters |
-| `src/components/document-library.tsx` | The Documents page |
+| File | Purpose |
+| ------------------------------------- | ----------------------------------------------------------------------------- |
+| `scripts/prepare-documents.ts` | Download the PDFs, extract pages, split passages, embed, and store |
+| `src/lib/documents.ts` | Sample document sources, database schema, and document list |
+| `src/lib/embeddings.ts` | OpenAI embeddings and similarity |
+| `src/lib/tools/search-documents.ts` | Function schema, argument validation, and passage search |
+| `src/library.ts` | Shared components for the prompt and renderer |
+| `src/components/sources.tsx` | The Sources component, built on React UI's source strip |
+| `src/lib/prompt.ts` | Comparison rules and example answers for Gateway |
+| `src/lib/gateway-history.ts` | Loads a thread's stored turns from Gateway as chat messages |
+| `src/app/api/chat/route.ts` | `runTools()` generation, streaming, and turn storage |
+| `src/app/api/documents/route.ts` | Document list for the Documents page |
+| `src/app/api/frontend-token/route.ts` | Frontend token for Gateway thread storage |
+| `src/lib/theme.ts` | Light and dark theme overrides |
+| `src/components/comparison-chat.tsx` | Agent Interface, chat transport, thread storage, sidebar, and Documents route |
+| `src/components/document-library.tsx` | The Documents page |
`npm run generate` creates the ignored component specification before dev/build/verify. The server passes that specification to `generateSystemPrompt({ cloud: true, library: spec, promptOptions })`, and Agent Interface renders responses with the same component library.
@@ -71,11 +72,13 @@ The downloaded reports and the database are ignored by Git and are not redistrib
## Conversations
-The OpenAI SDK sends requests to `https://api.thesys.dev/v1/embed/chat/completions` using `THESYS_API_KEY`. Chat Completions does not store conversations, so Agent Interface keeps each thread in memory and `fetchLLM` sends its messages with every question. Follow-up suggestions are sent the same way, so they build on the earlier answers. Threads reset when the page reloads; pass a `storage` adapter to Agent Interface to persist them.
+The OpenAI SDK sends requests to `https://api.thesys.dev/v1/embed/chat/completions` using `THESYS_API_KEY`. Chat Completions does not store conversations, so the chat route stores each turn in the thread's Gateway conversation and loads the earlier turns from there for every question. Follow-up suggestions are sent the same way, so they build on the earlier answers.
-The chat route forwards only user questions and assistant answers from the browser. It drops browser-supplied tool calls and results, so the model sees only passages the server found for the current question. The tool loop streams AG-UI events, which `agUIAdapter()` reads, because Chat Completions has no chunk for a tool result. It is the same loop as in the [conversational analytics](../conversational-analytics) cookbook.
+Agent Interface stores the thread list with Gateway's [Conversations API](https://www.openui.com/docs/gateway/api/conversations) through `useOpenuiCloudStorage()`. The browser calls Gateway directly with a short-lived [frontend token](https://www.openui.com/docs/gateway/authentication#frontend-tokens) from `/api/frontend-token`, which mints it with `THESYS_API_KEY` for one local user (`DEMO_USER_ID`, default `demo-user`) and app (`APP_ID`, default `document-comparison-cookbook`), so the key stays on the server and the browser reaches only those threads. Chat Completions doesn't write turns to a conversation, so the chat route appends each turn, including the tool calls and their results, with `storeChatCompletionHistory()` from [`@openuidev/server`](https://www.openui.com/docs/api-reference/server#conversation-history). A stopped or failed answer still keeps the user's message. Threads stay listed after a reload, and a thread you open again loads its messages. To keep threads in your own database instead, use `restStorage`.
-The app binds to loopback, and the chat route accepts browser requests only from its own local page. For deployment, add authentication and rate limits to the chat route.
+The chat route uses only the new question from the browser. `loadChatCompletionHistory()` in `src/lib/gateway-history.ts` loads the earlier turns from the thread's Gateway conversation, including their searches and passages, so the model sees where each earlier quote came from, and every passage it sees came from this server. The response ends once the turn is stored, so a follow-up finds it. The route runs the tool with the OpenAI SDK's [`runTools()`](https://github.com/openai/openai-node#automated-function-calls) and returns the runner's `toReadableStream()`, one JSON chunk per line, which `openAIReadableStreamAdapter()` reads. Chat Completions has no chunk for a tool result, so in a live answer **Behind the scenes** shows each call's arguments but not its result.
+
+The app binds to loopback, and every browser shares one local user's threads. For deployment, add [authentication](https://www.openui.com/docs/gateway/authentication), mint each frontend token for the signed-in user, check that each `threadId` belongs to that user before storing a turn in it, and add request-size and rate limits to both routes.
## Verify
diff --git a/examples/cookbooks/document-comparison/package-lock.json b/examples/cookbooks/document-comparison/package-lock.json
index 169fdc28b..13a706e4c 100644
--- a/examples/cookbooks/document-comparison/package-lock.json
+++ b/examples/cookbooks/document-comparison/package-lock.json
@@ -12,6 +12,7 @@
"@openuidev/react-headless": "0.16.3",
"@openuidev/react-lang": "0.3.0",
"@openuidev/react-ui": "0.16.3",
+ "@openuidev/server": "0.1.0",
"lucide-react": "^0.575.0",
"next": "16.2.6",
"openai": "^6.49.0",
@@ -1937,6 +1938,18 @@
"react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
}
},
+ "node_modules/@openuidev/server": {
+ "version": "0.1.0",
+ "resolved": "https://registry.npmjs.org/@openuidev/server/-/server-0.1.0.tgz",
+ "integrity": "sha512-Cm7nejELDHw0PoPlY67C4EW6b7DYx1ZnyCYyO5J6SIs6JjSBrY7rNzrnwB3DhAf4LmgO5sN/1WiD94BdZTNLPQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@openuidev/lang-core": "^0.3.0"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/@posthog/core": {
"version": "1.55.2",
"resolved": "https://registry.npmjs.org/@posthog/core/-/core-1.55.2.tgz",
diff --git a/examples/cookbooks/document-comparison/package.json b/examples/cookbooks/document-comparison/package.json
index 6d33e257b..2014e0d33 100644
--- a/examples/cookbooks/document-comparison/package.json
+++ b/examples/cookbooks/document-comparison/package.json
@@ -19,6 +19,7 @@
"@openuidev/react-headless": "0.16.3",
"@openuidev/react-lang": "0.3.0",
"@openuidev/react-ui": "0.16.3",
+ "@openuidev/server": "0.1.0",
"lucide-react": "^0.575.0",
"next": "16.2.6",
"openai": "^6.49.0",
diff --git a/examples/cookbooks/document-comparison/pnpm-lock.yaml b/examples/cookbooks/document-comparison/pnpm-lock.yaml
index 0608e1da2..f74a7025f 100644
--- a/examples/cookbooks/document-comparison/pnpm-lock.yaml
+++ b/examples/cookbooks/document-comparison/pnpm-lock.yaml
@@ -20,6 +20,9 @@ importers:
'@openuidev/react-ui':
specifier: 0.16.3
+ '@openuidev/server':
+ specifier: 0.1.0
+ version: 0.1.0([email protected])
lucide-react:
specifier: ^0.575.0
version: 0.575.0([email protected])
@@ -814,6 +817,10 @@ packages:
zod: ^3.25.0 || ^4.0.0
zustand: ^4.5.5
+ '@openuidev/[email protected]':
+ resolution: {integrity: sha512-Cm7nejELDHw0PoPlY67C4EW6b7DYx1ZnyCYyO5J6SIs6JjSBrY7rNzrnwB3DhAf4LmgO5sN/1WiD94BdZTNLPQ==}
+ engines: {node: '>=18'}
+
'@posthog/[email protected]':
resolution: {integrity: sha512-2mYxGbDmTLUs096VbcZqSWo0lrI48/BrX65r54NynxxFq409BOx9w73HxOAtOKZ1vblkdV6/GxQTe7KDcIQidg==}
@@ -2856,6 +2863,13 @@ snapshots:
- '@types/react-dom'
- supports-color
+ dependencies:
+ '@openuidev/lang-core': 0.3.0([email protected])
+ transitivePeerDependencies:
+ - '@modelcontextprotocol/sdk'
+ - zod
+
'@posthog/[email protected]':
dependencies:
'@posthog/types': 1.412.4
diff --git a/examples/cookbooks/document-comparison/src/app/api/chat/route.ts b/examples/cookbooks/document-comparison/src/app/api/chat/route.ts
index de0744857..c96037ebf 100644
--- a/examples/cookbooks/document-comparison/src/app/api/chat/route.ts
+++ b/examples/cookbooks/document-comparison/src/app/api/chat/route.ts
@@ -1,130 +1,105 @@
+import { storeChatCompletionHistory } from "@openuidev/server/openai";
import OpenAI from "openai";
-import type {
- ChatCompletionChunk,
- ChatCompletionMessageParam,
-} from "openai/resources/chat/completions";
-import { z } from "zod/v4";
-import { listDocuments, openDatabase, type Document } from "../../../lib/documents";
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import { listDocuments, openDatabase } from "../../../lib/documents";
+import { loadChatCompletionHistory } from "../../../lib/gateway-history";
import { comparisonPrompt } from "../../../lib/prompt";
-import { runChatToolLoop } from "../../../lib/tool-loop";
import { executeSearchDocuments, searchDocumentsTool } from "../../../lib/tools/search-documents";
export const runtime = "nodejs";
-// Chat Completions keeps no state, so the browser sends the whole conversation on every turn.
-// Forward only user questions and assistant answers. Tool calls and results from the browser
-// are dropped, so every passage the model cites comes from a search this server runs.
-const chatRequestSchema = z.object({
- messages: z
- .array(
- z.discriminatedUnion("role", [
- z.object({ role: z.literal("user"), content: z.string().trim().min(1).max(600) }),
- z.object({ role: z.literal("assistant"), content: z.string().nullish() }),
- z.object({ role: z.literal("tool") }),
- ]),
- )
- .min(1)
- .max(100)
- .refine((messages) => messages.at(-1)?.role === "user"),
-});
-
-function conversation(messages: z.infer<typeof chatRequestSchema>["messages"]) {
- return messages.flatMap((message): ChatCompletionMessageParam[] =>
- message.role === "tool" || !message.content
- ? []
- : [{ role: message.role, content: message.content }],
- );
-}
-
-async function parseChatRequest(request: Request) {
- if (request.headers.get("content-type")?.split(";")[0].trim() !== "application/json")
- throw new Error("Send JSON.");
- const reader = request.body?.getReader();
- if (!reader) throw new Error("Send a question.");
- const chunks: Uint8Array[] = [];
- let size = 0;
- try {
- while (true) {
- const { done, value } = await reader.read();
- if (done) break;
- size += value.byteLength;
- if (size > 1_000_000) {
- await reader.cancel();
- throw new Error("Request too large.");
- }
- chunks.push(value);
- }
- } finally {
- reader.releaseLock();
- }
- return chatRequestSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+// The thread's earlier turns, loaded from its Gateway conversation with their tool calls and
+// results rather than taken from the browser, so the model sees where each earlier answer came
+// from. To send less of a long thread, compact the messages here.
+function conversation(apiKey: string, threadId: string, signal: AbortSignal) {
+ return loadChatCompletionHistory({ apiKey, conversationId: threadId, signal });
}
export async function POST(request: Request) {
- // This example has no authentication, so it accepts browser requests only from its own
- // local page. Add authentication and rate limits before deploying it.
- const { port } = new URL(request.url);
- const origin = request.headers.get("origin");
- if (origin && origin !== `http://127.0.0.1:${port}` && origin !== `http://localhost:${port}`)
- return Response.json(
- { error: "This example only accepts requests from its local chat interface." },
- { status: 403 },
- );
- let body;
- try {
- body = await parseChatRequest(request);
- } catch {
+ // Agent Interface's storage creates the Gateway conversation first and sends its id as threadId.
+ // The browser sends the whole thread; only its last message, the new question, is used.
+ const { threadId, messages: sent } = (await request.json()) as {
+ threadId?: string;
+ messages?: ChatCompletionMessageParam[];
+ };
+ const question = sent?.at(-1);
+ if (!threadId || question?.role !== "user")
return Response.json(
- { error: "Send the conversation, ending with a question of up to 600 characters." },
+ { error: "Send a threadId and the thread's messages, ending with the user's." },
{ status: 400 },
);
- }
const apiKey = process.env.THESYS_API_KEY;
if (!apiKey || !process.env.OPENAI_API_KEY)
- return Response.json(
- {
- error: "Configure THESYS_API_KEY and OPENAI_API_KEY privately in .env.local and restart.",
- },
- { status: 503 },
- );
+ throw new Error("Set THESYS_API_KEY and OPENAI_API_KEY in .env.local, then restart.");
- let documents: Document[];
- let db;
- try {
- db = openDatabase();
- documents = listDocuments(db);
- } catch {
- return Response.json(
- { error: "Prepare the documents with npm run prepare:documents before asking a question." },
- { status: 503 },
- );
- } finally {
- db?.close();
- }
+ const db = openDatabase();
+ const documents = listDocuments(db);
+ db.close();
const gateway = new OpenAI({ apiKey, baseURL: "https://api.thesys.dev/v1/embed" });
- // App-owned function tools. The loop runs only the names registered here.
const searchTool = searchDocumentsTool(documents);
- const functionTools = { [searchTool.function.name]: executeSearchDocuments };
- const params = {
- model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
- messages: [
- { role: "system" as const, content: comparisonPrompt(documents) },
- ...conversation(body.messages),
- ],
- tools: [searchTool],
- max_completion_tokens: 6000,
- };
+ const thread = [...(await conversation(apiKey, threadId, request.signal)), question];
+ const messages: ChatCompletionMessageParam[] = [
+ { role: "system", content: comparisonPrompt(documents) },
+ ...thread,
+ ];
- // Open the first round before responding, so a rejected key, rate limit, or unknown model
- // returns as an HTTP error with Gateway's status instead of an event mid-stream.
- let firstStream: AsyncIterable<ChatCompletionChunk>;
- try {
- firstStream = await gateway.chat.completions.create(
- { ...params, stream: true },
- { signal: request.signal },
+ // runTools requests a completion, runs the tools the model calls, sends their results back, and
+ // repeats until the model answers. It runs only the tools registered here.
+ const runner = gateway.chat.completions.runTools(
+ {
+ model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
+ messages,
+ tools: [
+ {
+ type: "function",
+ function: {
+ ...searchTool.function,
+ // runTools ends the run when a tool throws, so return the error as the tool's result.
+ function: (args: string) =>
+ executeSearchDocuments(args, { signal: request.signal }).catch((error: unknown) =>
+ JSON.stringify({ error: error instanceof Error ? error.message : String(error) }),
+ ),
+ },
+ },
+ ],
+ max_completion_tokens: 6000,
+ stream: true,
+ },
+ { signal: request.signal, maxChatCompletions: 4 },
+ );
+
+ // Chat Completions doesn't write to the conversation, so store this turn when the run ends: the
+ // user's message, then each message the run adds, which are the tool calls, their results, and
+ // the answer. Agent Interface loads them when the thread is opened again. A stopped or failed
+ // run still stores the user's message and whatever finished before it ended.
+ const turn: ChatCompletionMessageParam[] = [question];
+ runner.on("message", (message) => turn.push(message));
+ const stored = runner
+ .done()
+ .catch(() => {})
+ .then(() => storeChatCompletionHistory({ apiKey, conversationId: threadId, messages: turn }))
+ .catch((error: unknown) =>
+ console.error("Could not store the turn in the Gateway conversation.", error),
);
+
+ // The runner's stream carries every completion's chunks, one JSON object per line, and Agent
+ // Interface reads it with openAIReadableStreamAdapter(). It ends once the turn is stored, so a
+ // follow-up loads it. Creating it now means no chunk is missed while the route waits below.
+ const stream = runner.toReadableStream().pipeThrough(
+ new TransformStream({
+ async flush() {
+ await stored;
+ },
+ }),
+ );
+
+ // Wait for the first chunk, so a rejected key, rate limit, or unknown model returns as an HTTP
+ // error with Gateway's message instead of failing mid-stream. Gateway reports some errors, such
+ // as an unknown model, inside a successful response, so waiting for the response isn't enough.
+ try {
+ await Promise.race([runner.emitted("chunk"), runner.done()]);
} catch (error) {
const upstream = error as { status?: number; message?: string };
return Response.json(
@@ -133,44 +108,7 @@ export async function POST(request: Request) {
);
}
- // Stream AG-UI events to the browser, running app-owned tools between model turns.
- const encoder = new TextEncoder();
- let open = true;
- const stream = new ReadableStream<Uint8Array>({
- async start(controller) {
- // Stop sending once the browser disconnects.
- const emit = (event: Record<string, unknown>) => {
- if (open) controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
- };
- try {
- await runChatToolLoop({
- client: gateway,
- params,
- firstStream,
- tools: functionTools,
- emit,
- signal: request.signal,
- maxRounds: 4,
- });
- } catch (error) {
- emit({
- type: "RUN_ERROR",
- message: error instanceof Error ? error.message : String(error),
- });
- } finally {
- if (open) controller.close();
- }
- },
- cancel() {
- open = false;
- },
- });
-
return new Response(stream, {
- headers: {
- "Content-Type": "text/event-stream",
- "Cache-Control": "no-cache, no-transform",
- Connection: "keep-alive",
- },
+ headers: { "Content-Type": "application/x-ndjson", "Cache-Control": "no-cache, no-transform" },
});
}
diff --git a/examples/cookbooks/document-comparison/src/app/api/frontend-token/route.ts b/examples/cookbooks/document-comparison/src/app/api/frontend-token/route.ts
new file mode 100644
index 000000000..25ad98239
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/app/api/frontend-token/route.ts
@@ -0,0 +1,33 @@
+export const runtime = "nodejs";
+
+// Mints the short-lived frontend token that useOpenuiCloudStorage() sends with its
+// Conversations API calls. Gateway scopes the token to one user and app, so the browser
+// reaches only those threads and never sees THESYS_API_KEY.
+export async function POST(request: Request) {
+ const apiKey = process.env.THESYS_API_KEY;
+ if (!apiKey) throw new Error("Set THESYS_API_KEY in .env.local, then restart.");
+
+ const upstream = await fetch("https://api.thesys.dev/v1/frontend-tokens", {
+ method: "POST",
+ headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+ body: JSON.stringify({
+ // There is no sign-in, so every browser shares one local user, as in apps from
+ // `openui create`. Use the signed-in user's id instead when you add authentication:
+ // https://www.openui.com/docs/gateway/authentication
+ user_id: process.env.DEMO_USER_ID || "demo-user",
+ // Keeps this example's threads apart from other apps that use the same key.
+ app_id: process.env.APP_ID || "document-comparison-cookbook",
+ }),
+ signal: request.signal,
+ });
+ if (!upstream.ok)
+ return Response.json(
+ { error: "OpenUI Gateway could not create a frontend token." },
+ { status: upstream.status },
+ );
+ const { token, expires_at } = (await upstream.json()) as { token: string; expires_at: number };
+ return Response.json(
+ { token, expires_at },
+ { headers: { "Cache-Control": "private, no-store" } },
+ );
+}
diff --git a/examples/cookbooks/document-comparison/src/components/comparison-chat.tsx b/examples/cookbooks/document-comparison/src/components/comparison-chat.tsx
index 652c2d25c..fd23d14c2 100644
--- a/examples/cookbooks/document-comparison/src/components/comparison-chat.tsx
+++ b/examples/cookbooks/document-comparison/src/components/comparison-chat.tsx
@@ -2,9 +2,10 @@
import {
AgentInterface,
- agUIAdapter,
fetchLLM,
openAIMessageFormat,
+ openAIReadableStreamAdapter,
+ useOpenuiCloudStorage,
useSystemThemeMode,
} from "@openuidev/react-ui";
import { ChartLine, ChartPie, FileText, ShieldAlert, TrendingUp } from "lucide-react";
@@ -13,10 +14,10 @@ import { darkTheme, lightTheme } from "../lib/theme";
import { library } from "../library";
import { DocumentLibrary } from "./document-library";
-// Send the thread's messages in Chat Completions format and read the route's AG-UI events.
+// Send the thread's messages in Chat Completions format and read the runner's stream from the route.
const llm = fetchLLM({
url: "/api/chat",
- streamAdapter: agUIAdapter(),
+ streamAdapter: openAIReadableStreamAdapter(),
messageFormat: openAIMessageFormat,
});
@@ -49,10 +50,18 @@ const starters = [
export default function ComparisonChat() {
const mode = useSystemThemeMode();
const theme = useMemo(() => ({ mode, lightTheme, darkTheme }), [mode]);
+ // Store threads as Gateway conversations, which the browser reaches with a short-lived token
+ // from /api/frontend-token. The chat route appends each turn to the thread's conversation, so
+ // a thread opened again loads its messages.
+ const storage = useOpenuiCloudStorage({
+ token: "/api/frontend-token",
+ features: { artifact: false },
+ });
return (
<div className="comparison-app">
<AgentInterface
llm={llm}
+ storage={storage}
componentLibrary={library}
agentName="Filing analyst"
logoUrl="/logo.svg"
diff --git a/examples/cookbooks/document-comparison/src/lib/gateway-history.ts b/examples/cookbooks/document-comparison/src/lib/gateway-history.ts
new file mode 100644
index 000000000..0be9f71c3
--- /dev/null
+++ b/examples/cookbooks/document-comparison/src/lib/gateway-history.ts
@@ -0,0 +1,70 @@
+import type {
+ ChatCompletionMessageFunctionToolCall,
+ ChatCompletionMessageParam,
+} from "openai/resources/chat/completions";
+
+// A conversation item, in the shape storeChatCompletionHistory() stores it.
+type ConversationItem = {
+ type: string;
+ role?: string;
+ content?: { text?: string }[];
+ call_id?: string;
+ name?: string;
+ arguments?: string;
+ output?: string;
+};
+
+// Loads a thread's stored turns from its Gateway conversation as Chat Completions messages, the
+// reverse of storeChatCompletionHistory(): questions, answers, tool calls, and tool results.
+export async function loadChatCompletionHistory(options: {
+ apiKey: string;
+ conversationId: string;
+ signal?: AbortSignal;
+}): Promise<ChatCompletionMessageParam[]> {
+ const items: ConversationItem[] = [];
+ let after: string | undefined;
+ do {
+ const query = new URLSearchParams({ order: "asc", limit: "100" });
+ if (after) query.set("after", after);
+ const response = await fetch(
+ `https://api.thesys.dev/v1/conversations/${encodeURIComponent(options.conversationId)}/items?${query}`,
+ { headers: { Authorization: `Bearer ${options.apiKey}` }, signal: options.signal },
+ );
+ if (!response.ok) throw new Error(`Could not load the thread from Gateway: ${response.status}`);
+ const page = (await response.json()) as {
+ data: ConversationItem[];
+ has_more: boolean;
+ last_id: string;
+ };
+ items.push(...page.data);
+ after = page.has_more ? page.last_id : undefined;
+ } while (after);
+ return toChatMessages(items);
+}
+
+function toChatMessages(items: ConversationItem[]) {
+ // Chat Completions rejects a tool call without a result, so drop the calls of a stopped run.
+ const answered = new Set(
+ items.flatMap((item) => (item.type === "function_call_output" ? [item.call_id] : [])),
+ );
+ const messages: ChatCompletionMessageParam[] = [];
+ for (const item of items) {
+ if (item.type === "message" && (item.role === "user" || item.role === "assistant")) {
+ const text = (item.content ?? []).map((part) => part.text ?? "").join("");
+ if (text) messages.push({ role: item.role, content: text });
+ } else if (item.type === "function_call" && item.call_id && answered.has(item.call_id)) {
+ const call: ChatCompletionMessageFunctionToolCall = {
+ id: item.call_id,
+ type: "function",
+ function: { name: item.name ?? "", arguments: item.arguments ?? "{}" },
+ };
+ // A completion's text and its tool calls make up one assistant message.
+ const last = messages.at(-1);
+ if (last?.role === "assistant") (last.tool_calls ??= []).push(call);
+ else messages.push({ role: "assistant", content: null, tool_calls: [call] });
+ } else if (item.type === "function_call_output" && item.call_id) {
+ messages.push({ role: "tool", tool_call_id: item.call_id, content: item.output ?? "" });
+ }
+ }
+ return messages;
+}
diff --git a/examples/cookbooks/document-comparison/src/lib/tool-loop.ts b/examples/cookbooks/document-comparison/src/lib/tool-loop.ts
deleted file mode 100644
index ba00e6177..000000000
--- a/examples/cookbooks/document-comparison/src/lib/tool-loop.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type OpenAI from "openai";
-import type {
- ChatCompletionChunk,
- ChatCompletionCreateParamsStreaming,
- ChatCompletionMessageParam,
-} from "openai/resources/chat/completions";
-
-/**
- * Function-tool loop for the OpenUI Gateway Chat Completions API.
- *
- * Chat Completions returns function calls to the application instead of running
- * them. Each round streams one completion. When the model requests tools, the
- * loop runs them, appends the assistant's tool-call message and one `tool`
- * message per call, and requests the next completion. It ends when the model
- * answers without requesting a tool. The last allowed round sets
- * `tool_choice: "none"` so the model must answer in text.
- *
- * The browser receives AG-UI events rather than raw completion chunks, because
- * Chat Completions has no chunk for a tool result. Agent Interface reads them
- * with `agUIAdapter()` and shows each call with its result.
- */
-
-export type FunctionToolExecutor = (
- argsJson: string,
- ctx: { signal?: AbortSignal },
-) => Promise<string>;
-
-export interface RunChatToolLoopOptions {
- client: OpenAI;
- /** The completion request; `messages` holds the system prompt and the conversation. */
- params: Omit<ChatCompletionCreateParamsStreaming, "stream">;
- /**
- * The already-open stream of the first round, created from `params`. Opening it
- * before responding lets the route return Gateway's errors as HTTP errors.
- */
- firstStream: AsyncIterable<ChatCompletionChunk>;
- /** name → executor. A call to any other name receives an error result. */
- tools: Record<string, FunctionToolExecutor>;
- /** Receives every AG-UI event to forward to the browser. */
- emit: (event: Record<string, unknown>) => void;
- /** Propagates browser aborts into executors and model requests. */
- signal?: AbortSignal;
- /** Cap on model requests per question (default 5). */
- maxRounds?: number;
-}
-
-type ToolCall = { id: string; name: string; arguments: string };
-
-export async function runChatToolLoop(options: RunChatToolLoopOptions): Promise<void> {
- const { client, tools, emit, signal, maxRounds = 5 } = options;
- const messages: ChatCompletionMessageParam[] = [...options.params.messages];
-
- for (let round = 0; round < maxRounds; round++) {
- const lastRound = round === maxRounds - 1;
- const stream =
- round === 0
- ? options.firstStream
- : await client.chat.completions.create(
- {
- ...options.params,
- messages,
- stream: true,
- ...(lastRound ? { tool_choice: "none" as const } : {}),
- },
- { signal },
- );
-
- const messageId = randomUUID();
- let text = "";
- const calls: ToolCall[] = [];
- for await (const chunk of stream) {
- const delta = chunk.choices[0]?.delta;
- if (delta?.content) {
- if (!text) emit({ type: "TEXT_MESSAGE_START", messageId, role: "assistant" });
- text += delta.content;
- emit({ type: "TEXT_MESSAGE_CONTENT", messageId, delta: delta.content });
- }
- // Each call streams as indexed deltas: its id and name first, then argument fragments.
- // The last round ignores calls, in case a model does not honor tool_choice.
- for (const part of lastRound ? [] : (delta?.tool_calls ?? [])) {
- let call = calls[part.index];
- if (!call) {
- call = { id: part.id ?? "", name: part.function?.name ?? "", arguments: "" };
- calls[part.index] = call;
- emit({
- type: "TOOL_CALL_START",
- toolCallId: call.id,
- toolCallName: call.name,
- parentMessageId: messageId,
- });
- }
- if (part.function?.arguments) {
- call.arguments += part.function.arguments;
- emit({ type: "TOOL_CALL_ARGS", toolCallId: call.id, delta: part.function.arguments });
- }
- }
- }
- if (text) emit({ type: "TEXT_MESSAGE_END", messageId });
-
- const requested = calls.filter(Boolean);
- if (requested.length === 0) {
- if (!text) throw new Error("The model returned no answer. Please retry.");
- return;
- }
-
- messages.push({
- role: "assistant",
- content: text || null,
- tool_calls: requested.map((call) => ({
- id: call.id,
- type: "function",
- function: { name: call.name, arguments: call.arguments },
- })),
- });
- for (const call of requested) emit({ type: "TOOL_CALL_END", toolCallId: call.id });
- // A throwing executor settles as an error result rather than aborting the run.
- for (const call of requested) {
- let content: string;
- try {
- const execute = Object.hasOwn(tools, call.name) ? tools[call.name] : undefined;
- if (!execute) throw new Error(`Unknown tool: ${call.name}`);
- content = await execute(call.arguments, { signal });
- } catch (error) {
- content = JSON.stringify({ error: error instanceof Error ? error.message : String(error) });
- }
- messages.push({ role: "tool", tool_call_id: call.id, content });
- emit({
- type: "TOOL_CALL_RESULT",
- messageId: randomUUID(),
- toolCallId: call.id,
- content,
- role: "tool",
- });
- }
- }
-}
diff --git a/examples/cookbooks/document-comparison/src/lib/tools/search-documents.ts b/examples/cookbooks/document-comparison/src/lib/tools/search-documents.ts
index 6e1099065..defbddeda 100644
--- a/examples/cookbooks/document-comparison/src/lib/tools/search-documents.ts
+++ b/examples/cookbooks/document-comparison/src/lib/tools/search-documents.ts
@@ -5,7 +5,7 @@ import { openDatabase, sources, type Document } from "../documents";
import { embed, similarity } from "../embeddings";
// The search_documents function tool: its JSON schema for Gateway, argument validation,
-// semantic search over the prepared passages, and the executor the tool loop calls.
+// semantic search over the prepared passages, and the executor that runTools() calls.
export function searchDocumentsTool(documents: Document[]) {
return {