Skip to content

The Open Standard for Generative UI

feat(cookbooks): move conversational analytics to Chat Completions (#1256)

Visharad Kashyapaf39268c254b
diff --git a/docs/components/cookbook-analytics-architecture.tsx b/docs/components/cookbook-analytics-architecture.tsx
index 4121005ff..520656ac4 100644
--- a/docs/components/cookbook-analytics-architecture.tsx
+++ b/docs/components/cookbook-analytics-architecture.tsx
@@ -30,7 +30,7 @@ const boxes: Box[] = [
height: 184,
icon: Sparkles,
title: "OpenUI Gateway",
- lines: ["Runs the model", "Checks the generated UI", "Stores the conversation"],
+ lines: ["Runs the model", "Checks the generated UI"],
highlight: true,
},
{
diff --git a/docs/content/docs/cookbooks/conversational-analytics.mdx b/docs/content/docs/cookbooks/conversational-analytics.mdx
index 36877ea76..f8b071dca 100644
--- a/docs/content/docs/cookbooks/conversational-analytics.mdx
+++ b/docs/content/docs/cookbooks/conversational-analytics.mdx
@@ -16,7 +16,8 @@ In this cookbook, you'll learn how to:
- Give the model access to your data through a function tool with typed, validated arguments, instead of letting it write SQL.
- Describe a component library to the model, and render its answers with the same library.
- Stream answers into [Agent Interface](/docs/agent/getting-started/introduction), OpenUI's ready-made React chat shell with threads, streaming messages, and tool activity, so charts and tables appear while the response is still being generated.
-- Keep the conversation in [OpenUI Gateway](/docs/gateway), OpenUI's hosted model API that routes requests to model providers, corrects generated UI, and stores conversations, so follow-up questions build on earlier answers.
+- Generate answers with [OpenUI Gateway](/docs/gateway), OpenUI's hosted model API that routes requests to model providers and corrects generated UI, through its OpenAI-compatible [Chat Completions API](/docs/gateway/api/chat-completions).
+- Send the conversation with each question, so follow-up questions build on earlier answers.
<div className="not-prose my-6">
<a
@@ -57,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.
-Conversation history is stored in OpenUI Gateway and remains available across page reloads and local server restarts.
## How it works
@@ -65,10 +65,10 @@ A conversational analytics assistant splits the work between your application an
<CookbookAnalyticsArchitecture />
-1. **The user asks a question.** Agent Interface sends it to OpenUI Gateway through your server's chat route, which adds the conversation id, a function tool that describes the queries you support, and a system prompt that describes your components.
+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. Gateway stores the conversation, so a follow-up such as "only the last ten laps" reuses the earlier context and runs a fresh query.
+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.
### Why a tool, not SQL
@@ -179,35 +179,17 @@ 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, sending only the latest user message. Gateway restores the earlier context from the conversation id:
-
-```ts title="src/components/analytics-chat.tsx"
-const chatLLM: ChatLLM = {
- streamProtocol: openAIResponsesAdapter(),
- send: ({ threadId, messages, signal }) =>
- fetch("/api/chat", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- threadId,
- input: openAIConversationMessageFormat.toApi(messages.slice(-1)),
- }),
- signal,
- }),
-};
-```
-
-Use the Gateway storage hook for the sidebar and saved messages:
+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()`:
```tsx title="src/components/analytics-chat.tsx"
-const storage = useOpenuiCloudStorage({
- token: "/api/frontend-token",
- features: { artifact: false },
+const llm = fetchLLM({
+ url: "/api/chat",
+ streamAdapter: agUIAdapter(),
+ messageFormat: openAIMessageFormat,
});
<AgentInterface
- llm={chatLLM}
- storage={storage}
+ llm={llm}
componentLibrary={library}
agentName="Data analyst"
theme={{ mode: "light" }}
@@ -220,9 +202,10 @@ const storage = useOpenuiCloudStorage({
</AgentInterface>;
```
-`useOpenuiCloudStorage` is exported by the example's pinned `@openuidev/react-ui` package. The [token route](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/conversational-analytics/src/app/api/frontend-token/route.ts) issues a short-lived token for a stable `user_id` and `app_id`; the master key stays on the server. Before generating, the chat route checks that the conversation belongs to the same scope. A conversation id from the browser is not proof of ownership.
+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:
-Keep `DEMO_USER_ID` and `APP_ID` stable to retain conversation history. Their defaults are `local-demo` and `conversational-analytics-cookbook`.
+- **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).
### 5. Stream the answer
@@ -234,36 +217,36 @@ const gateway = new OpenAI({
baseURL: "https://api.thesys.dev/v1/embed",
});
const lapTimesTool = queryLapTimesTool(drivers);
-const createParams = {
+const params = {
model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
- instructions: analyticsPrompt(drivers),
- input: [...stopped, ...body.input],
- conversation: body.threadId,
+ messages: [
+ { role: "system" as const, content: analyticsPrompt(drivers) },
+ ...conversation(body.messages),
+ ],
tools: [lapTimesTool],
- store: true,
- max_output_tokens: 6000,
+ max_completion_tokens: 6000,
};
-```
-
-When Gateway requests a function call, execute it and send its result back with the matching `call_id`. The example uses the OpenUI Gateway template's [function-tool loop](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts):
+const firstStream = await gateway.chat.completions.create(
+ { ...params, stream: true },
+ { signal: request.signal },
+);
-```ts
-await runFunctionToolLoop({
+await runChatToolLoop({
client: gateway,
- createParams,
+ params,
firstStream,
- tools: { [lapTimesTool.name]: executeQueryLapTimes },
- enqueue,
+ tools: { [lapTimesTool.function.name]: executeQueryLapTimes },
+ emit,
signal: request.signal,
maxRounds: 3,
});
```
-The loop forwards tool activity and text deltas as Responses Server-Sent Events. Each continuation sends only the new tool outputs to the saved conversation. Gateway already holds the preceding question and response items.
+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 [chat route](https://github.com/thesysdev/openui/blob/main/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts) validates the request before calling Gateway and forwards Gateway's own errors to Agent Interface, which shows them in the chat.
+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.
-Stopping a response while `query_lap_times` runs can leave a stored function call without its output, and Gateway rejects the conversation's next turn until the call is answered. Before each turn, the route lists the conversation's latest items and sends a "stopped" output for any unanswered call, which is the `stopped` array above.
+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.
@@ -276,8 +259,8 @@ In the browser:
1. Ask for the five fastest drivers. Expand **Behind the scenes** to inspect `query_lap_times` and its result.
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. Stop a generation and ask another question to check recovery.
-5. Reload the page or restart the server. Reopen the conversation from the sidebar and confirm its messages, visual answers, and tool activity are retained.
+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.
Generated layouts can vary. Check values against the tool result. Missing data and tool errors should produce an explanation rather than invented points.
@@ -285,10 +268,12 @@ Generated layouts can vary. Check values against the tool result. Missing data a
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 runs locally with a single demo identity. Before deploying it, replace the local guard with authentication and rate limits, derive user identity from the signed-in session, and retain conversation ownership checks. See the [example README](https://github.com/thesysdev/openui/tree/main/examples/cookbooks/conversational-analytics) 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. 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 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.
- [Agent Interface quickstart](/docs/agent/getting-started/quickstart)
- [Agent tools](/docs/agent/core-concepts/tools)
-- [Gateway Responses API](/docs/gateway/api/responses)
+- [Gateway Chat Completions API](/docs/gateway/api/chat-completions)
Data source: [OpenF1](https://openf1.org/docs/), race session `9507`. OpenF1 is an independent project, unaffiliated with Formula 1.
diff --git a/examples/cookbooks/conversational-analytics/.env.example b/examples/cookbooks/conversational-analytics/.env.example
index 8834daa91..b017e01ad 100644
--- a/examples/cookbooks/conversational-analytics/.env.example
+++ b/examples/cookbooks/conversational-analytics/.env.example
@@ -1,5 +1,4 @@
# Create an inference key at https://console.thesys.dev/keys.
-# Configure THESYS_API_KEY privately in .env.local to enable OpenUI Gateway generation
-# and saved conversations.
+# 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
diff --git a/examples/cookbooks/conversational-analytics/README.md b/examples/cookbooks/conversational-analytics/README.md
index 1825fbdd7..845b16ed4 100644
--- a/examples/cookbooks/conversational-analytics/README.md
+++ b/examples/cookbooks/conversational-analytics/README.md
@@ -29,41 +29,36 @@ Try:
## How it works
-1. Agent Interface sends the latest user message to `/api/chat`.
-2. OpenUI Gateway requests `query_lap_times` with a view, driver numbers, and lap range.
+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 the saved Gateway conversation and forwards tool events and generated OpenUI Lang to the browser.
+4. The tool loop returns the result to Gateway and streams tool events 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` | The Gateway template's function-tool loop |
-| `src/lib/gateway-session.ts` | Local identity, frontend tokens, conversation ownership, and stopped tool calls |
-| `src/components/analytics-chat.tsx` | Agent Interface, Gateway storage, 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/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 |
`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.
-## Gateway conversations
+## Conversations
-The OpenAI SDK transports requests to `https://api.thesys.dev/v1/embed` using `THESYS_API_KEY`. Generation uses `conversation: threadId` and `store: true`. Continuations submit only new function outputs because Gateway retains preceding input and response items.
+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.
-`useOpenuiCloudStorage` from the pinned `@openuidev/react-ui` package loads the sidebar and messages using short-lived tokens from `/api/frontend-token`. `openAIResponsesAdapter` handles streamed tool activity and answers. The client sends only the latest user message; the server rejects injected history or function outputs.
+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.
-Stopping a response while `query_lap_times` runs can leave a stored function call without its output, which Gateway rejects on the next turn. The chat route sends a "stopped" output for any such call ahead of the next question.
-
-`DEMO_USER_ID` defaults to `local-demo` and `APP_ID` to `conversational-analytics-cookbook`. Keep them stable to retain history across reloads and restarts. The server verifies conversation membership in the same scope before generation.
-
-The app binds to loopback and its chat/token routes reject production requests. For deployment, replace the local guard with authentication and rate limits on both routes, derive user identity from the session, retain conversation ownership checks, and provide persistent SQLite storage or a hosted database. Gateway receives the conversation, component/tool instructions, driver catalog, and requested query results.
+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.
## Data notes
@@ -81,8 +76,10 @@ npm run verify
`verify` generates the component specification and runs a production build with type checking. It needs neither credentials nor a download.
-In the browser, inspect `query_lap_times` under **Behind the scenes**, watch partial responses appear during generation, follow up with a narrower lap range, stop and retry, and reopen the conversation after a reload or server restart.
+In the browser, inspect `query_lap_times` under **Behind the scenes**, watch partial responses appear during generation, click a follow-up suggestion or ask for a narrower lap range, and stop and retry.
## Adapt it
Replace `queryLapTimes` with a query to your database or API and update the function schema and prompt. Extend `src/library.ts` to support additional presentations, then regenerate the specification.
+
+To run the tool and prompt on an agent framework instead, see the [LangGraph Platform](../../agent-frameworks/langgraph-platform), [Vercel AI SDK](../../agent-frameworks/vercel-ai-sdk), [Vercel Eve](../../agent-frameworks/vercel-eve), [Mastra](../../agent-frameworks/mastra), and [Google ADK](../../agent-frameworks/google-adk) examples.
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 3d6bbe18d..403e8ebcd 100644
--- a/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts
+++ b/examples/cookbooks/conversational-analytics/src/app/api/chat/route.ts
@@ -1,31 +1,41 @@
import OpenAI from "openai";
-import type { ResponseCreateParamsNonStreaming } from "openai/resources/responses/responses";
+import type {
+ ChatCompletionChunk,
+ ChatCompletionMessageParam,
+} from "openai/resources/chat/completions";
import { z } from "zod/v4";
import { listDrivers, openDatabase, type Driver } from "../../../lib/f1-data";
-import {
- localDemoAccess,
- ownsConversation,
- stoppedToolOutputs,
-} from "../../../lib/gateway-session";
import { analyticsPrompt } from "../../../lib/prompt";
-import { runFunctionToolLoop } from "../../../lib/tool-loop";
+import { runChatToolLoop } from "../../../lib/tool-loop";
import { executeQueryLapTimes, queryLapTimesTool } from "../../../lib/tools/lap-times";
export const runtime = "nodejs";
-// Gateway stores the conversation, so the browser sends only its latest question.
-// Accept exactly one bounded user message; never forward browser-supplied history or tool output.
-const chatRequestSchema = z.strictObject({
- threadId: z.string().min(1).max(200),
- input: z.tuple([
- z.strictObject({
- type: z.literal("message"),
- role: z.literal("user"),
- content: z.string().trim().min(1).max(600),
- }),
- ]),
+// 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.");
@@ -38,7 +48,7 @@ async function parseChatRequest(request: Request) {
const { done, value } = await reader.read();
if (done) break;
size += value.byteLength;
- if (size > 16_384) {
+ if (size > 1_000_000) {
await reader.cancel();
throw new Error("Request too large.");
}
@@ -51,14 +61,21 @@ async function parseChatRequest(request: Request) {
}
export async function POST(request: Request) {
- const denied = localDemoAccess(request);
- if (denied) return denied;
+ // 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 {
return Response.json(
- { error: "Send one text question of up to 600 characters and a conversation id." },
+ { error: "Send the conversation, ending with a question of up to 600 characters." },
{ status: 400 },
);
}
@@ -72,21 +89,6 @@ export async function POST(request: Request) {
{ status: 503 },
);
- let stopped;
- try {
- if (!(await ownsConversation(body.threadId, request.signal)))
- return Response.json(
- { error: "Conversation not found for this app and user." },
- { status: 403 },
- );
- stopped = await stoppedToolOutputs(body.threadId, request.signal);
- } catch {
- return Response.json(
- { error: "Unable to verify Gateway conversation access." },
- { status: 503 },
- );
- }
-
let drivers: Driver[];
let db;
try {
@@ -104,23 +106,25 @@ export async function POST(request: Request) {
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.name]: executeQueryLapTimes };
- const createParams: ResponseCreateParamsNonStreaming = {
+ const functionTools = { [lapTimesTool.function.name]: executeQueryLapTimes };
+ const params = {
model: process.env.OPENUI_MODEL || "openai/gpt-5.5",
- instructions: analyticsPrompt(drivers),
- input: [...stopped, ...body.input],
- conversation: body.threadId,
- store: true,
+ messages: [
+ { role: "system" as const, content: analyticsPrompt(drivers) },
+ ...conversation(body.messages),
+ ],
tools: [lapTimesTool],
- max_output_tokens: 6000,
+ max_completion_tokens: 6000,
};
- let firstStream: AsyncIterable<Record<string, unknown>>;
+ // 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.responses.create(
- { ...createParams, stream: true },
+ firstStream = await gateway.chat.completions.create(
+ { ...params, stream: true },
{ signal: request.signal },
- )) as unknown as AsyncIterable<Record<string, unknown>>;
+ );
} catch (error) {
const upstream = error as { status?: number; message?: string };
return Response.json(
@@ -129,28 +133,37 @@ export async function POST(request: Request) {
);
}
- // Forward Gateway's Responses events as SSE, running app-owned tools between model turns.
+ // 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) {
- const enqueue = (event: Record<string, unknown>) =>
- controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+ // 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 runFunctionToolLoop({
+ await runChatToolLoop({
client: gateway,
- createParams,
+ params,
firstStream,
tools: functionTools,
- enqueue,
+ emit,
signal: request.signal,
maxRounds: 3,
});
} catch (error) {
- enqueue({ type: "error", message: error instanceof Error ? error.message : String(error) });
+ emit({
+ type: "RUN_ERROR",
+ message: error instanceof Error ? error.message : String(error),
+ });
} finally {
- controller.close();
+ if (open) controller.close();
}
},
+ cancel() {
+ open = false;
+ },
});
return new Response(stream, {
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
deleted file mode 100644
index d8b2d0ca3..000000000
--- a/examples/cookbooks/conversational-analytics/src/app/api/frontend-token/route.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { localDemoAccess, mintFrontendToken } from "../../../lib/gateway-session";
-
-export const runtime = "nodejs";
-
-export async function POST(request: Request) {
- const denied = localDemoAccess(request);
- if (denied) return denied;
- try {
- return Response.json(await mintFrontendToken(request.signal), {
- headers: { "Cache-Control": "private, no-store" },
- });
- } catch (error) {
- return Response.json(
- { error: error instanceof Error ? error.message : "Unable to connect to Gateway storage." },
- { status: 503 },
- );
- }
-}
diff --git a/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx b/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx
index 0a6cc1c36..df965d237 100644
--- a/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx
+++ b/examples/cookbooks/conversational-analytics/src/components/analytics-chat.tsx
@@ -2,28 +2,19 @@
import {
AgentInterface,
- openAIConversationMessageFormat,
- openAIResponsesAdapter,
- useOpenuiCloudStorage,
- type ChatLLM,
+ agUIAdapter,
+ fetchLLM,
+ openAIMessageFormat,
type ThemeProps,
} from "@openuidev/react-ui";
import { library } from "../library";
-// Gateway restores earlier turns from the conversation id, so send only the latest message.
-const chatLLM: ChatLLM = {
- streamProtocol: openAIResponsesAdapter(),
- send: ({ threadId, messages, signal }) =>
- fetch("/api/chat", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- threadId,
- input: openAIConversationMessageFormat.toApi(messages.slice(-1)),
- }),
- signal,
- }),
-};
+// Send the thread's messages in Chat Completions format and read the route's AG-UI events.
+const llm = fetchLLM({
+ url: "/api/chat",
+ streamAdapter: agUIAdapter(),
+ messageFormat: openAIMessageFormat,
+});
const theme: ThemeProps = { mode: "light" };
const starters = [
@@ -45,15 +36,10 @@ const starters = [
];
export default function AnalyticsChat() {
- const storage = useOpenuiCloudStorage({
- token: "/api/frontend-token",
- features: { artifact: false },
- });
return (
<div className="analytics-app">
<AgentInterface
- llm={chatLLM}
- storage={storage}
+ llm={llm}
componentLibrary={library}
agentName="Data analyst"
theme={theme}
diff --git a/examples/cookbooks/conversational-analytics/src/lib/gateway-session.ts b/examples/cookbooks/conversational-analytics/src/lib/gateway-session.ts
deleted file mode 100644
index 10e107e48..000000000
--- a/examples/cookbooks/conversational-analytics/src/lib/gateway-session.ts
+++ /dev/null
@@ -1,110 +0,0 @@
-import OpenAI from "openai";
-import type { ResponseInputItem } from "openai/resources/responses/responses";
-import { z } from "zod/v4";
-
-const tokenSchema = z.object({ token: z.string().min(1), expires_at: z.number() });
-const pageSchema = z.object({
- data: z.array(z.object({ id: z.string() })),
- has_more: z.boolean(),
- last_id: z.string().optional(),
-});
-
-// A stable, server-owned identity for this loopback-only, single-user example.
-// Replace this boundary with authentication before deploying the app.
-export function localDemoAccess(request: Request): Response | undefined {
- const url = new URL(request.url);
- // Next.js can normalize request.url to localhost even when the browser uses 127.0.0.1.
- const host = request.headers.get("host") || url.host;
- const localHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
- const hostName = host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.split(":")[0];
- const origin = request.headers.get("origin");
- if (
- process.env.NODE_ENV === "production" ||
- !localHosts.has(url.hostname) ||
- !localHosts.has(hostName) ||
- (origin && origin !== `${url.protocol}//${host}`) ||
- request.headers.get("sec-fetch-site") === "cross-site"
- ) {
- return Response.json(
- { error: "This example uses a local demo identity. Add authentication before deployment." },
- { status: 403 },
- );
- }
-}
-
-export async function mintFrontendToken(signal?: AbortSignal) {
- const apiKey = process.env.THESYS_API_KEY;
- if (!apiKey) throw new Error("Configure THESYS_API_KEY privately in .env.local and restart.");
- const response = await fetch("https://api.thesys.dev/v1/frontend-tokens", {
- method: "POST",
- headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
- body: JSON.stringify({
- user_id: process.env.DEMO_USER_ID || "local-demo",
- app_id: process.env.APP_ID || "conversational-analytics-cookbook",
- }),
- cache: "no-store",
- signal,
- });
- if (!response.ok) throw new Error("Unable to connect to Gateway conversation storage.");
- return tokenSchema.parse(await response.json());
-}
-
-// Use the same token-scoped list API and cursor contract as Gateway storage.
-// Never authorize a browser-supplied conversation id with the master key alone.
-export async function ownsConversation(threadId: string, signal?: AbortSignal) {
- const { token } = await mintFrontendToken(signal);
- let after: string | undefined;
- for (let page = 0; page < 50; page++) {
- const query = new URLSearchParams({ limit: "100" });
- if (after) query.set("after", after);
- const response = await fetch(`https://api.thesys.dev/v1/conversations?${query}`, {
- headers: { "x-thesys-frontend-token": token },
- cache: "no-store",
- signal,
- });
- if (!response.ok) throw new Error("Unable to verify Gateway conversation access.");
- const result = pageSchema.parse(await response.json());
- if (result.data.some((conversation) => conversation.id === threadId)) return true;
- if (!result.has_more) return false;
- if (!result.last_id || result.last_id === after)
- throw new Error("Gateway returned an invalid conversation cursor.");
- after = result.last_id;
- }
- throw new Error("Conversation lookup exceeded the demo's page limit.");
-}
-
-// Stopping a response while its tool runs can leave a stored function_call without an output,
-// and Gateway then rejects every later turn in that conversation. Gateway has no endpoint for
-// adding the missing output directly, so return outputs to send ahead of the next question.
-export async function stoppedToolOutputs(
- threadId: string,
- signal?: AbortSignal,
-): Promise<ResponseInputItem[]> {
- const conversations = new OpenAI({
- apiKey: process.env.THESYS_API_KEY,
- baseURL: "https://api.thesys.dev/v1",
- });
- const { data } = await conversations.conversations.items.list(
- threadId,
- { order: "desc", limit: 20 },
- { signal },
- );
- const answered = new Set(
- data.flatMap((item) => (item.type === "function_call_output" ? [item.call_id] : [])),
- );
- return data
- .flatMap((item) =>
- item.type === "function_call" && !answered.has(item.call_id)
- ? [
- {
- type: "function_call_output" as const,
- call_id: item.call_id,
- output: JSON.stringify({
- error: "The user stopped this response before the tool finished.",
- }),
- },
- ]
- : [],
- )
- .reverse();
-}
diff --git a/examples/cookbooks/conversational-analytics/src/lib/prompt.ts b/examples/cookbooks/conversational-analytics/src/lib/prompt.ts
index cc5c6869c..c2c6b977d 100644
--- a/examples/cookbooks/conversational-analytics/src/lib/prompt.ts
+++ b/examples/cookbooks/conversational-analytics/src/lib/prompt.ts
@@ -14,7 +14,7 @@ export function analyticsPrompt(drivers: Driver[]) {
library: spec,
promptOptions: {
additionalRules: [
- `You answer questions about recorded lap times in the ${race.name} (${race.date}, ${race.laps} laps). Call query_lap_times before answering any data question. It is a Responses function tool executed by the application server, not an OpenUI Query expression.`,
+ `You answer questions about recorded lap times in the ${race.name} (${race.date}, ${race.laps} laps). Call query_lap_times before answering any data question. It is a function tool executed by the application server, not an OpenUI Query expression.`,
`Available drivers: ${JSON.stringify(drivers)}. Resolve names to driver numbers using this list.`,
"Use fastest_laps to rank drivers and lap_times to compare one to four drivers. The final ten laps are 48 through 57. On follow-ups, keep the previous drivers and lap range unless the user changes them, and query again.",
"After the tool returns, emit root first, then the components in reading order. Use a table or bar chart for rankings and a line chart for lap-by-lap comparisons. End with a FollowUpBlock of two or three short questions this data can answer, such as other drivers, lap ranges, or views.",
diff --git a/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts b/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts
index 674660efd..ba00e6177 100644
--- a/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts
+++ b/examples/cookbooks/conversational-analytics/src/lib/tool-loop.ts
@@ -1,181 +1,137 @@
-// Copied from templates/openui-cloud/src/lib/tool-loop.ts; keep the two in sync.
+import { randomUUID } from "node:crypto";
import type OpenAI from "openai";
import type {
- ResponseCreateParamsNonStreaming,
- ResponseInputItem,
-} from "openai/resources/responses/responses";
+ ChatCompletionChunk,
+ ChatCompletionCreateParamsStreaming,
+ ChatCompletionMessageParam,
+} from "openai/resources/chat/completions";
/**
- * Function-tool execution loop for the OpenUI Gateway Responses API.
+ * Function-tool loop for the OpenUI Gateway Chat Completions API.
*
- * OpenUI Gateway executes its own tools (web_search, image_search, MCP)
- * server-side, but `type: "function"` tools you declare are executed by
- * YOUR server: the model emits a `function_call`, you run it, post the
- * `function_call_output` back, and the model continues — possibly calling more
- * tools — until it produces the final answer.
+ * 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.
*
- * Two rules make this safe alongside Gateway's server-side tools, and both are
- * enforced here rather than left to the caller:
- *
- * 1. Execute ONLY calls whose `name` you declared (the keys of `tools`).
- * Gateway may stream its own tools as real-named `function_call` items. Those
- * are already executed server-side and must never be run or answered again.
- * 2. Skip any call whose `call_id` already received a `function_call_output`
- * on the same stream. The API never streams an output for a call it wants
- * the client to execute, so an output's presence means "already settled".
- *
- * The loop mirrors the openai SDK's `runTools` invariant: the round cap limits
- * additional model turns, never settlement — the last allowed round posts its
- * outputs with `tool_choice: "none"`, and calls that a non-enforcing server
- * still lets through are settled in one final forward-only turn, so a stored
- * conversation is never left holding an unanswered `function_call`. Two
- * deliberate deviations from
- * `runTools`, both forced by server-side tools + stored conversations:
- * undeclared names are ignored rather than answered with an "invalid tool"
- * message (rule 1), and executor throws become error outputs rather than
- * aborting the run (a mid-run abort would strand calls in the conversation).
+ * 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: { callId: string; signal?: AbortSignal },
+ ctx: { signal?: AbortSignal },
) => Promise<string>;
-export interface RunFunctionToolLoopOptions {
+export interface RunChatToolLoopOptions {
client: OpenAI;
- /** The params of the original request; reused verbatim for continuations. */
- createParams: ResponseCreateParamsNonStreaming;
- /** The already-open stream of the first response. */
- firstStream: AsyncIterable<Record<string, unknown>>;
- /** name → executor. The keys are the ONLY tool names this loop will run. */
+ /** 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 stream event (forward these to the browser as SSE). */
- enqueue: (event: Record<string, unknown>) => void;
- /** Propagates browser aborts into executors and continuation requests. */
+ /** 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 round-trips after tool results (default 5). */
+ /** Cap on model requests per question (default 5). */
maxRounds?: number;
}
-interface PendingCall {
- callId: string;
- name: string;
- argsJson: string;
-}
+type ToolCall = { id: string; name: string; arguments: string };
-/**
- * Drive the stream to completion, executing declared function tools between
- * model turns. Resolves when the model finishes without requesting any of the
- * caller's tools; if `maxRounds` is reached, the final round still posts its
- * outputs but pins `tool_choice: "none"` so the model must answer in text.
- */
-export async function runFunctionToolLoop(options: RunFunctionToolLoopOptions): Promise<void> {
- const { client, createParams, tools, enqueue, signal, maxRounds = 5 } = options;
+export async function runChatToolLoop(options: RunChatToolLoopOptions): Promise<void> {
+ const { client, tools, emit, signal, maxRounds = 5 } = options;
+ const messages: ChatCompletionMessageParam[] = [...options.params.messages];
- // Run every pending call and surface each result to the browser; a throwing
- // executor settles as an error output rather than aborting the run.
- const executeCalls = async (calls: PendingCall[]): Promise<ResponseInputItem[]> => {
- const outputs: ResponseInputItem[] = [];
- for (const call of calls) {
- let output: string;
- try {
- output = await tools[call.name]!(call.argsJson, { callId: call.callId, signal });
- } catch (err) {
- output = JSON.stringify({ error: err instanceof Error ? err.message : String(err) });
+ 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 });
+ }
}
- const item = { type: "function_call_output" as const, call_id: call.callId, output };
- outputs.push(item);
- enqueue({
- type: "response.output_item.added",
- item: { ...item, id: `fc_out_${call.callId}` },
- });
}
- return outputs;
- };
-
- const continueWith = (outputs: ResponseInputItem[], settleOnly: boolean) =>
- client.responses.create(
- {
- ...createParams,
- input: outputs,
- stream: true,
- ...(settleOnly ? { tool_choice: "none" as const } : {}),
- },
- { signal },
- ) as unknown as Promise<AsyncIterable<Record<string, unknown>>>;
-
- let pending = await consumeStream(options.firstStream, tools, enqueue);
+ if (text) emit({ type: "TEXT_MESSAGE_END", messageId });
- for (let round = 0; pending.length > 0; round++) {
- // Last allowed round: settlement still happens, but the model may not
- // request more tools.
- const settleOnly = round >= maxRounds - 1;
- const stream = await continueWith(await executeCalls(pending), settleOnly);
- pending = await consumeStream(stream, tools, enqueue);
- if (settleOnly) break;
- }
-
- // Non-empty only when the settle round produced NEW calls — i.e. the server
- // did not enforce tool_choice:"none" (observed with some models). Settle
- // them once more, forward-only: a stored conversation must never be left
- // holding an unanswered function_call.
- if (pending.length > 0) {
- const stream = await continueWith(await executeCalls(pending), true);
- for await (const event of stream) enqueue(event);
- }
-}
-
-/**
- * Forward every event and collect the declared-tool calls that the stream
- * leaves unanswered. Arguments may arrive on the added item, as deltas, or on
- * the done item — all three are handled, last write wins.
- */
-async function consumeStream(
- stream: AsyncIterable<Record<string, unknown>>,
- tools: Record<string, FunctionToolExecutor>,
- enqueue: (event: Record<string, unknown>) => void,
-): Promise<PendingCall[]> {
- const callsByItemId = new Map<string, PendingCall>();
- const calls: PendingCall[] = [];
- const answeredCallIds = new Set<string>();
-
- for await (const event of stream) {
- enqueue(event);
+ const requested = calls.filter(Boolean);
+ if (requested.length === 0) {
+ if (!text) throw new Error("The model returned no answer. Please retry.");
+ return;
+ }
- const type = event.type;
- if (type === "response.output_item.added" || type === "response.output_item.done") {
- const item = event.item as
- | { type?: string; id?: string; call_id?: string; name?: string; arguments?: string }
- | undefined;
- if (item?.type === "function_call_output" && item.call_id) {
- answeredCallIds.add(item.call_id);
- } else if (item?.type === "function_call" && item.call_id && item.name) {
- const known =
- (item.id ? callsByItemId.get(item.id) : undefined) ?? callsByItemId.get(item.call_id);
- if (known) {
- if (item.arguments != null) known.argsJson = item.arguments;
- } else if (Object.hasOwn(tools, item.name)) {
- // Rule 1: track only declared tools — everything else (including
- // Gateway-internal thesys_* calls) is passed through untouched.
- const call: PendingCall = {
- callId: item.call_id,
- name: item.name,
- argsJson: item.arguments ?? "",
- };
- calls.push(call);
- if (item.id) callsByItemId.set(item.id, call);
- callsByItemId.set(item.call_id, call);
- }
+ 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) });
}
- } else if (type === "response.function_call_arguments.delta") {
- const call = callsByItemId.get(event.item_id as string);
- if (call && typeof event.delta === "string") call.argsJson += event.delta;
- } else if (type === "response.function_call_arguments.done") {
- const call = callsByItemId.get(event.item_id as string);
- if (call && typeof event.arguments === "string") call.argsJson = event.arguments;
+ messages.push({ role: "tool", tool_call_id: call.id, content });
+ emit({
+ type: "TOOL_CALL_RESULT",
+ messageId: randomUUID(),
+ toolCallId: call.id,
+ content,
+ role: "tool",
+ });
}
}
-
- // Rule 2: a call that already has an output on this stream is settled.
- return calls.filter((call) => !answeredCallIds.has(call.callId));
}
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 5a821ac3a..15c88c63f 100644
--- a/examples/cookbooks/conversational-analytics/src/lib/tools/lap-times.ts
+++ b/examples/cookbooks/conversational-analytics/src/lib/tools/lap-times.ts
@@ -8,42 +8,44 @@ import { listDrivers, openDatabase, race, type Driver } from "../f1-data";
export function queryLapTimesTool(drivers: Driver[]) {
return {
type: "function" as const,
- name: "query_lap_times",
- description: `Query recorded lap times from the ${race.name}. Rank each driver's fastest lap or compare up to four drivers lap by lap. Times are seconds; lower is faster. Read-only server-owned SQL.`,
- parameters: {
- type: "object",
- properties: {
- view: { type: "string", enum: ["fastest_laps", "lap_times"] },
- driver_numbers: {
- type: "array",
- items: { type: "integer", enum: drivers.map((driver) => driver.number) },
- maxItems: 4,
- description: "Empty for all drivers in fastest_laps; select one to four for lap_times.",
- },
- lap_start: {
- type: "integer",
- minimum: 1,
- maximum: race.laps,
- description: "First lap, inclusive. Use 1 for the whole race.",
- },
- lap_end: {
- type: "integer",
- minimum: 1,
- maximum: race.laps,
- description: "Last lap, inclusive. Use 57 for the whole race.",
- },
- limit: {
- type: "integer",
- minimum: 1,
- maximum: 20,
- description:
- "Number of drivers in the fastest-lap ranking. Use 5 unless asked otherwise.",
+ function: {
+ name: "query_lap_times",
+ description: `Query recorded lap times from the ${race.name}. Rank each driver's fastest lap or compare up to four drivers lap by lap. Times are seconds; lower is faster. Read-only server-owned SQL.`,
+ parameters: {
+ type: "object",
+ properties: {
+ view: { type: "string", enum: ["fastest_laps", "lap_times"] },
+ driver_numbers: {
+ type: "array",
+ items: { type: "integer", enum: drivers.map((driver) => driver.number) },
+ maxItems: 4,
+ description: "Empty for all drivers in fastest_laps; select one to four for lap_times.",
+ },
+ lap_start: {
+ type: "integer",
+ minimum: 1,
+ maximum: race.laps,
+ description: "First lap, inclusive. Use 1 for the whole race.",
+ },
+ lap_end: {
+ type: "integer",
+ minimum: 1,
+ maximum: race.laps,
+ description: "Last lap, inclusive. Use 57 for the whole race.",
+ },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: 20,
+ description:
+ "Number of drivers in the fastest-lap ranking. Use 5 unless asked otherwise.",
+ },
},
+ required: ["view", "driver_numbers", "lap_start", "lap_end", "limit"],
+ additionalProperties: false,
},
- required: ["view", "driver_numbers", "lap_start", "lap_end", "limit"],
- additionalProperties: false,
+ strict: true,
},
- strict: true,
};
}