The open-source agent harness - the runtime layer that turns an LLM into a working agent.
UI SDK Changes (#123)
qaifi-tf0a371d517a16
diff --git a/docs/ui-sdk/get-started/installation.mdx b/docs/ui-sdk/get-started/installation.mdxindex c709e6e29..338090d22 100644--- a/docs/ui-sdk/get-started/installation.mdx+++ b/docs/ui-sdk/get-started/installation.mdx@@ -1,6 +1,7 @@---title: "Installation"description: "Install the SDK, import the stylesheet, and satisfy peer dependencies."+hidden: true---## Install@@ -21,73 +22,57 @@ yarn add @truefoundry/trueforge-ui</CodeGroup>-`react` and `react-dom` are required peer dependencies and must be version 18 or 19. `@assistant-ui/core`, `@assistant-ui/react`, and `@types/react` are optional peers — the package bundles working versions, so install them yourself only if you use their APIs directly or need to pin a version.+`react` and `react-dom` are required peer dependencies and must be version 18 or 19. `@assistant-ui/core`, `@assistant-ui/react`, and `@types/react` are optional peers, you need to install them yourself only if you use their APIs directly or need to pin a version.-## Import the stylesheet+Next: [Quickstart](/ui-sdk/get-started/quickstart).-The SDK ships a prebuilt stylesheet. Import it after Tailwind in your host CSS:+## FAQs-```css title="app.css"-@import "tailwindcss";-@import "@truefoundry/trueforge-ui/styles.css";-```--Reference only the following stylesheet `@truefoundry/trueforge-ui/styles.css.`It is self-contained and includes all styles required by the SDK components. No Tailwind configuration is required in your application.--The SDK intentionally excludes Tailwind Preflight to prevent it from overriding your application’s base styles. If your application does not use Tailwind, you can remove the `@import "tailwindcss"` statement from your own styles.--The stylesheet also includes:+<AccordionGroup>+ <Accordion title="Error: requires an AuiProvider">+ Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.-- Markdown styles scoped to .markdown-body-- Semantic design tokens+ <CodeGroup>-Most design tokens are applied as inline styles at runtime. As a result, they cannot be reliably overridden through application CSS. Use theme.tokens to customize these values instead.+ ```ts vite.config.ts+ export default defineConfig({+ resolve: {+ dedupe: [+ "react",+ "react-dom",+ "@assistant-ui/core",+ "@assistant-ui/react",+ "@assistant-ui/store",+ ],+ },+ });+ ```-See [Theming](/ui-sdk/guides/theming#precedence) for details.+ ```json package.json+ {+ "resolutions": {+ "@assistant-ui/core": "<version>",+ "@assistant-ui/store": "<version>"+ }+ }+ ```-## Deduplicate the assistant-ui singletons+ </CodeGroup>-`react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.+ The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.-<CodeGroup>--```ts vite.config.ts-export default defineConfig({- resolve: {- dedupe: [- "react",- "react-dom",- "@assistant-ui/core",- "@assistant-ui/react",- "@assistant-ui/store",- ],- },-});-```+ Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.+ </Accordion>-```json package.json-{- "resolutions": {- "@assistant-ui/core": "<version>",- "@assistant-ui/store": "<version>"- }-}-```+ <Accordion title="The UI renders but is collapsed to zero height">+ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.-</CodeGroup>--The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.--Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.--## Give the component a height--The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.--```tsx-<div className="flex h-dvh min-h-0 w-full flex-1 flex-col">- <TrueforgeUI /* ... */ className="h-full min-h-0" />-</div>-```+ ```tsx+ <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">+ <TrueforgeUI /* ... */ className="h-full min-h-0" />+ </div>+ ```-Next: [Quickstart](/ui-sdk/get-started/quickstart).\ No newline at end of file+ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.+ </Accordion>+</AccordionGroup>\ No newline at end of filediff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdxindex 359cdcc83..0c62d9018 100644--- a/docs/ui-sdk/get-started/quickstart.mdx+++ b/docs/ui-sdk/get-started/quickstart.mdx@@ -3,56 +3,26 @@ title: "Quickstart"description: "Render a working agent chat UI against one of three backends."----Make sure you have completed [Installation](/ui-sdk/get-started/installation) first — the stylesheet import and the height requirement both matter, and skipping either produces a blank screen.+## Installation-Then pick a backend. The `server` prop takes one of three shapes, and everything else about the component is identical between them.+<CodeGroup>-<CardGroup cols={3}>- <Card title="TrueFoundry (Quickest)" icon="bolt" href="#truefoundry">- Point to TrueFoundry control plane.- </Card>-- <Card title="TrueForge" icon="clock" href="#trueforge">- Harness adapter. Coming soon.- </Card>+```text npm+npm install @truefoundry/trueforge-ui+```- <Card title="Custom" icon="wrench" href="#custom">- Compose or implement the server yourself.- </Card>-</CardGroup>--## TrueFoundry--The zero-config path. The SDK builds the agent UI server from your API key and control plane URL; the gateway URL is optional and resolved from the control plane when omitted.--```tsx title="App.tsx"-import { TrueforgeUI } from "@truefoundry/trueforge-ui";--export default function App() {- return (- <div style={{ height: "100dvh" }}>- <TrueforgeUI- server={{- type: "truefoundry",- apiKey: {{API_KEY}},- controlPlaneURL: {{CONTROL_PLANE_URL}},- }}- layout="sidebar"- />- </div>- );-}+```text pnpm+pnpm add @truefoundry/trueforge-ui```-Add `gatewayPlaneURL` alongside `controlPlaneURL` to target a specific gateway.+```text yarn+```-Because this config is resolved asynchronously, the SDK shows a brief loading indicator before the chat appears. The other two paths mount immediately.+</CodeGroup>-<Frame caption="What `TrueforgeUI` renders — a full agent chat with streaming, history, and tool calls.">- <img src="/images/getting-started-chat.png" alt="The TrueforgeUI component rendering an agent chat with an agent-steps panel and a streamed response" />-</Frame>+`react` and `react-dom` are required peer dependencies and must be version 18 or 19. `@assistant-ui/core`, `@assistant-ui/react`, and `@types/react` are optional peers, you need to install them yourself only if you use their APIs directly or need to pin a version.-## TrueForge+## Connect with TrueForge ServerTyped for hosts adopting the harness adapter.@@ -66,50 +36,60 @@ Typed for hosts adopting the harness adapter./>```-<Warning>- The harness adapter has not shipped yet. Selecting this type surfaces a not-implemented error and calls `onError` rather than rendering a chat, so use [TrueFoundry](#truefoundry) or a [custom server](#custom) until the adapter lands.-</Warning>--## Custom--Use this when you compose chat and builder yourself — a chat-only gateway adapter with a stub catalog, a full host BFF, or a proxy that keeps credentials server-side. Pass the server object directly, with no `type` wrapper.--`createTrueFoundryServer` combines a chat port with the builder callbacks. The stubs below return empty lists, which is enough to mount; fill them in as you add agent management.--```tsx title="App.tsx"-import { TrueforgeUI, createTrueFoundryServer } from "@truefoundry/trueforge-ui";-import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";--// this structure will most likely change. Govinda to update this-const chatServer = createTrueFoundryChatServer({- apiKey: import.meta.env.VITE_TFY_API_KEY,- baseUrl: import.meta.env.VITE_TFY_GATEWAY_URL,-});--const server = createTrueFoundryServer({- chatServer,- getCapabilities: async () => ({- data: { sandbox: { enabled: false }, skill: { enabled: false } },- }),- getModels: async () => [],- getSkills: async () => [],- getMcp: async () => [],- searchAgents: async () => [],- saveAgent: async () => ({}),-});--export default function App() {- return (- <div style={{ height: "100dvh" }}>- <TrueforgeUI server={server} layout="sidebar" />- </div>- );-}-```+<Frame caption="What `TrueforgeUI` renders — a full agent chat with streaming, history, and tool calls.">+ +</Frame>-Three notes on this path. Empty `getModels` means the composer has no models to offer, so supply real ones before enabling composer mode — see [Agent modes](/ui-sdk/concepts/agent-modes). `createTrueFoundryServer` attaches no `catalog`, so the settings panel stays hidden until you pass one. And `getCapabilities` is required: it declares which optional features your backend supports, so the UI hides sandbox and skill affordances rather than offering ones that fail.+## Troubleshooting++<AccordionGroup>+ <Accordion title="Error: requires an AuiProvider">+ Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.++ <CodeGroup>++ ```ts vite.config.ts+ export default defineConfig({+ resolve: {+ dedupe: [+ "react",+ "react-dom",+ "@assistant-ui/core",+ "@assistant-ui/react",+ "@assistant-ui/store",+ ],+ },+ });+ ```++ ```json package.json+ {+ "resolutions": {+ "@assistant-ui/core": "<version>",+ "@assistant-ui/store": "<version>"+ }+ }+ ```++ </CodeGroup>++ The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.++ Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.+ </Accordion>++ <Accordion title="The UI renders but is collapsed to zero height">+ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.++ ```tsx+ <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">+ <TrueforgeUI /* ... */ className="h-full min-h-0" />+ </div>+ ```-To skip `createTrueFoundryServer` entirely and implement the interface from scratch — against any backend, not just TrueFoundry — see [Bring your own server](/ui-sdk/guides/custom-server).+ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.+ </Accordion>+</AccordionGroup>## Where to go nextdiff --git a/docs/ui-sdk/guides/setup-different-servers/connect-with-true-foundry.mdx b/docs/ui-sdk/guides/setup-different-servers/connect-with-true-foundry.mdxnew file mode 100644index 000000000..a59c6b9fe--- /dev/null+++ b/docs/ui-sdk/guides/setup-different-servers/connect-with-true-foundry.mdx@@ -0,0 +1,28 @@+---+title: "Connect with TrueFoundry"+---++The zero-config path. The SDK builds the agent UI server from your API key and control plane URL; the gateway URL is optional and resolved from the control plane when omitted.++```jsx App.tsx+import { TrueforgeUI } from "@truefoundry/trueforge-ui";++export default function App() {+ return (+ <div style={{ height: "100dvh" }}>+ <TrueforgeUI+ server={{+ type: "truefoundry",+ apiKey: {{API_KEY}},+ controlPlaneURL: {{CONTROL_PLANE_URL}},+ }}+ layout="sidebar"+ />+ </div>+ );+}+```++Add `gatewayPlaneURL` alongside `controlPlaneURL` to target a specific gateway.++Because this config is resolved asynchronously, the SDK shows a brief loading indicator before the chat appears. The other two paths mount immediately.\ No newline at end of filediff --git a/docs/ui-sdk/index.mdx b/docs/ui-sdk/index.mdxindex 70799f86f..7abdb8613 100644--- a/docs/ui-sdk/index.mdx+++ b/docs/ui-sdk/index.mdx@@ -5,17 +5,13 @@ description: "A themeable React SDK for building AI agent chat applications."`@truefoundry/trueforge-ui` provides a production-ready agent chat experience as a single, reusable React component that can be integrated into an existing application.-It supports:--- Streaming responses-- Session history-- Tool calls and approval workflows-- File attachments-- Agent library with compose new agent option-- Sub-agents+Features:++- Chat - Streaming responses, Session history, Tool calls and approval workflows, File attachments+- Agents - Agent library with compose new agent option, Sub-agents- Reasoning traces- Model, MCP, Skill and Sandbox connector-- Configurable server - TrueForge, TrueFoundry or fully custom+- Configurable server - TrueForge, TrueFoundry or fully customThe component is built on assistant-ui and follows shadcn/ui conventions. This allows you to customize the branding, layout, and individual UI components while retaining full control over the application’s look and feeldiff --git a/docs/ui-sdk/guides/custom-server.mdx b/docs/ui-sdk/setup-different-servers/custom-server.mdxsimilarity index 59%rename from docs/ui-sdk/guides/custom-server.mdxrename to docs/ui-sdk/setup-different-servers/custom-server.mdxindex 66a0a04ab..ba6cc16c7 100644--- a/docs/ui-sdk/guides/custom-server.mdx+++ b/docs/ui-sdk/setup-different-servers/custom-server.mdx@@ -3,17 +3,50 @@ title: "Bring your own server"description: "Implement AgentUIServer and pass the object straight to the component."----Because `server` accepts an `AgentUIServer` directly, you can front any backend — including-your own proxy that keeps API keys server-side. The object is used immediately, so there is no-loading indicator on mount.+Use this when you compose chat and builder yourself — a chat-only gateway adapter with a stub catalog, a full host BFF, or a proxy that keeps credentials server-side. Pass the server object directly, with no `type` wrapper.++`createTrueFoundryServer` combines a chat port with the builder callbacks. The stubs below return empty lists, which is enough to mount; fill them in as you add agent management.++```jsx App.tsx+import { TrueforgeUI, createTrueFoundryServer } from "@truefoundry/trueforge-ui";+import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";++// this structure will most likely change. Govinda to update this+const chatServer = createTrueFoundryChatServer({+ apiKey: import.meta.env.VITE_TFY_API_KEY,+ baseUrl: import.meta.env.VITE_TFY_GATEWAY_URL,+});++const server = createTrueFoundryServer({+ chatServer,+ getCapabilities: async () => ({+ data: { sandbox: { enabled: false }, skill: { enabled: false } },+ }),+ getModels: async () => [],+ getSkills: async () => [],+ getMcp: async () => [],+ searchAgents: async () => [],+ saveAgent: async () => ({}),+});++export default function App() {+ return (+ <div style={{ height: "100dvh" }}>+ <TrueforgeUI server={server} layout="sidebar" />+ </div>+ );+}+```++To skip `createTrueFoundryServer` entirely and implement the interface from scratch — against any backend, not just TrueFoundry — see [Bring your own server](/ui-sdk/guides/custom-server).++Because `server` accepts an `AgentUIServer` directly, you can front any backend — including your own proxy that keeps API keys server-side. The object is used immediately, so there is no loading indicator on mount.## Minimal implementation-The shape below is the smallest thing that mounts. Optional methods are omitted; required ones-must exist even if they only throw in paths your UI never reaches.+The shape below is the smallest thing that mounts. Optional methods are omitted; required ones must exist even if they only throw in paths your UI never reaches.-List methods return a `PageResult`, which carries methods as well as data — so a small helper-for the single-page case keeps the boilerplate in one place.+List methods return a `PageResult`, which carries methods as well as data — so a small helper for the single-page case keeps the boilerplate in one place.```ts title="server.ts"import type { AgentUIServer, PageResult, Session } from "@truefoundry/trueforge-ui";@@ -94,9 +127,7 @@ export const server: AgentUIServer = {};```-Declaring `sandbox` and `skill` as disabled is the honest starting point — the UI then hides-those affordances instead of offering controls your backend cannot serve. Flip them on as you-implement each.+Declaring `sandbox` and `skill` as disabled is the honest starting point — the UI then hides those affordances instead of offering controls your backend cannot serve. Flip them on as you implement each.```tsx title="App.tsx"<TrueforgeUI server={server} layout="sidebar" agentConfig={{ mode: "AgentLibrary" }} />@@ -104,9 +135,7 @@ implement each.## Streaming-`createTurn` yields envelopes of the form `{ sequenceNumber, event }` — not bare events. The-number must increase monotonically within the turn, and it is what lets a reconnecting client-resume via `subscribeToTurn({ afterSequenceNumber })`.+`createTurn` yields envelopes of the form `{ sequenceNumber, event }` — not bare events. The number must increase monotonically within the turn, and it is what lets a reconnecting client resume via `subscribeToTurn({ afterSequenceNumber })`.The minimum viable stream for one assistant reply is three events:@@ -148,18 +177,13 @@ async *createTurn({ sessionId, input }) {}```-Two things are easy to get wrong. Deltas carry the *increment* rather than the accumulated-text, and every delta for one message shares a single `id`. And a stream that ends without a-`turn.done` leaves the UI showing the turn as still running.+Two things are easy to get wrong. Deltas carry the _increment_ rather than the accumulated text, and every delta for one message shares a single `id`. And a stream that ends without a `turn.done` leaves the UI showing the turn as still running.-[Streaming events](/ui-sdk/reference/events) documents the full protocol — tool calls, approval-prompts, sub-agent threads, and sandbox artifacts.+[Streaming events](/ui-sdk/reference/events) documents the full protocol — tool calls, approval prompts, sub-agent threads, and sandbox artifacts.## Pagination-`PageResult<T, R>` carries `data` (the rows), `response` (your raw backend payload), and the-methods `hasNextPage()` and `getNextPage()`. Page tokens travel the other way: requests accept-a `pageToken`, so `getNextPage()` calls your backend again with the token you kept.+`PageResult<T, R>` carries `data` (the rows), `response` (your raw backend payload), and the methods `hasNextPage()` and `getNextPage()`. Page tokens travel the other way: requests accept a `pageToken`, so `getNextPage()` calls your backend again with the token you kept.```tsasync listSessions({ pageToken, limit = 20 } = {}) {@@ -174,38 +198,33 @@ async listSessions({ pageToken, limit = 20 } = {}) {}```-Because the result carries methods, you cannot hand back a bare parsed JSON object — construct-it, or reuse a helper like the `onePage` above.+Because the result carries methods, you cannot hand back a bare parsed JSON object — construct it, or reuse a helper like the `onePage` above.-`listEvents` additionally accepts `lastTurnId`, used when hydrating history for an existing-session.+`listEvents` additionally accepts `lastTurnId`, used when hydrating history for an existing session.## Optional capabilities<AccordionGroup><Accordion title="deleteSession / deleteAgent">- In a hand-written `AgentUIServer` like the one above, omitting these leaves the- corresponding affordances unavailable rather than broken. (This differs from- `createTrueFoundryServer`, where an omitted `deleteAgent` throws when called.)+ In a hand-written `AgentUIServer` like the one above, omitting these leaves the corresponding affordances unavailable rather than broken. (This differs from `createTrueFoundryServer`, where an omitted `deleteAgent` throws when called.)</Accordion>+<Accordion title="downloadSandboxFile">- Return a `Blob`. Required only if your agents produce sandbox artifacts users should be able- to download.+ Return a `Blob`. Required only if your agents produce sandbox artifacts users should be able to download.</Accordion>+<Accordion title="subscribeToTurn">- Resumes a live stream from `afterSequenceNumber`, so a reconnecting client picks up where it- left off instead of replaying the turn. Skip it if your backend cannot resume.+ Resumes a live stream from `afterSequenceNumber`, so a reconnecting client picks up where it left off instead of replaying the turn. Skip it if your backend cannot resume.</Accordion>+<Accordion title="catalog">- Attach a [`CatalogServer`](/ui-sdk/reference/catalog) to enable the settings UI — models,- connectors, skills, and sandboxes. Without it those surfaces do not render.+ Attach a [`CatalogServer`](/ui-sdk/reference/catalog) to enable the settings UI — models, connectors, skills, and sandboxes. Without it those surfaces do not render.</Accordion></AccordionGroup>## Widening the types-The interfaces are generic so you can carry backend-specific fields through the UI without-casting. `AgentUIServer` takes the chat port, the builder port, and the catalog:+The interfaces are generic so you can carry backend-specific fields through the UI without casting. `AgentUIServer` takes the chat port, the builder port, and the catalog:```tsinterface MyModel extends ModelSelection {@@ -223,14 +242,12 @@ const server: AgentUIServer<};```-See [Widening the types](/ui-sdk/concepts/server-contract#widening-the-types) for the full set of-parameters.+See [Widening the types](/ui-sdk/concepts/server-contract#widening-the-types) for the full set of parameters.## Attachments-Attachment handling defaults to `trueFoundryAttachmentAdapter`. Override it through the-`adapters` prop on `TrueforgeUI` if your backend stores uploads differently.+Attachment handling defaults to `trueFoundryAttachmentAdapter`. Override it through the `adapters` prop on `TrueforgeUI` if your backend stores uploads differently.```tsx<TrueforgeUI server={server} layout="sidebar" adapters={{ attachments: myAdapter }} />-```+```\ No newline at end of filediff --git a/docs/ui-sdk/concepts/server-contract.mdx b/docs/ui-sdk/setup-different-servers/server-contract.mdxsimilarity index 66%rename from docs/ui-sdk/concepts/server-contract.mdxrename to docs/ui-sdk/setup-different-servers/server-contract.mdxindex c35409b3d..eb59f86b2 100644--- a/docs/ui-sdk/concepts/server-contract.mdx+++ b/docs/ui-sdk/setup-different-servers/server-contract.mdx@@ -3,8 +3,7 @@ title: "Server contract"description: "The interfaces a backend must implement for the SDK to talk to it."----The `server` prop accepts either a built-in config object or an object implementing-`AgentUIServer`.+The `server` prop accepts either a built-in config object or an object implementing `AgentUIServer`.```tstype TrueforgeServerConfig =@@ -19,13 +18,9 @@ type TrueforgeServerConfig =| AgentUIServer;```-Each form resolves differently. An `AgentUIServer` object is used immediately. A `truefoundry`-config is resolved asynchronously, so the SDK renders a loading indicator (`role="status"`) for-a moment first. A `trueforge` config is typed for the forthcoming harness adapter and currently-resolves to a not-implemented error — see [Quickstart](/ui-sdk/get-started/quickstart#trueforge).+Each form resolves differently. An `AgentUIServer` object is used immediately. A `truefoundry` config is resolved asynchronously, so the SDK renders a loading indicator (`role="status"`) for a moment first. A `trueforge` config is typed for the forthcoming harness adapter and currently resolves to a not-implemented error — see [Quickstart](/ui-sdk/get-started/quickstart#trueforge).-`catalog` is optional on both built-in forms and is attached to the resolved server, which is-how you enable the [settings UI](/ui-sdk/reference/catalog) without hand-building a server.+`catalog` is optional on both built-in forms and is attached to the resolved server, which is how you enable the [settings UI](/ui-sdk/reference/catalog) without hand-building a server.## The composed contract@@ -33,12 +28,9 @@ how you enable the [settings UI](/ui-sdk/reference/catalog) without hand-buildintype AgentUIServer = AgentChatServer & AgentBuilderServer & { catalog?: CatalogServer };```-Chat and session operations, agent-builder operations, and an optional settings catalog. Only-the first two are required.+Chat and session operations, agent-builder operations, and an optional settings catalog. Only the first two are required.-Every interface is generic. The SDK's types constrain only the fields the UI itself reads, so-when your backend returns richer objects you widen the type parameters rather than casting or-stripping fields. See [widening](#widening-the-types) below.+Every interface is generic. The SDK's types constrain only the fields the UI itself reads, so when your backend returns richer objects you widen the type parameters rather than casting or stripping fields. See [widening](#widening-the-types) below.## AgentChatServer@@ -89,19 +81,13 @@ interface AgentChatServer {}```-Three methods are optional. `deleteSession` gates the delete control in the session list.-`subscribeToTurn` lets a reconnecting client resume a stream from `afterSequenceNumber` rather-than replaying it. `downloadSandboxFile` enables artifact downloads.+Three methods are optional. `deleteSession` gates the delete control in the session list. `subscribeToTurn` lets a reconnecting client resume a stream from `afterSequenceNumber` rather than replaying it. `downloadSandboxFile` enables artifact downloads.<Note>- `downloadSandboxFile` receives both `turnId` and `sandboxId` because backends address- sandboxes differently. If your download route is scoped to a turn, resolve the sandbox from- `turnId` and ignore `sandboxId`; if you address sandboxes directly, use `sandboxId`.+ `downloadSandboxFile` receives both `turnId` and `sandboxId` because backends address sandboxes differently. If your download route is scoped to a turn, resolve the sandbox from `turnId` and ignore `sandboxId`; if you address sandboxes directly, use `sandboxId`.</Note>-`createTurn` and `subscribeToTurn` yield `TurnStreamData`, an envelope of-`{ sequenceNumber, event }`. The event protocol is documented in-[Streaming events](/ui-sdk/reference/events).+`createTurn` and `subscribeToTurn` yield `TurnStreamData`, an envelope of `{ sequenceNumber, event }`. The event protocol is documented in [Streaming events](/ui-sdk/reference/events).## Sessions@@ -117,12 +103,9 @@ interface Session {}```-`id`, `isMutable`, `createdAt`, and `updatedAt` are required; timestamps are ISO strings. Set-`isMutable: true` while the agent spec may still be edited — that is what permits-`updateSession`.+`id`, `isMutable`, `createdAt`, and `updatedAt` are required; timestamps are ISO strings. Set `isMutable: true` while the agent spec may still be edited — that is what permits `updateSession`.-`CreateSessionRequest` is `{ agentName?, agentSpec?, title? }`; `UpdateSessionRequest` is the-same plus a required `sessionId`.+`CreateSessionRequest` is `{ agentName?, agentSpec?, title? }`; `UpdateSessionRequest` is the same plus a required `sessionId`.## Pagination@@ -135,14 +118,9 @@ interface PageResult<T, R = unknown> {}```-`PageResult` is an object with methods, not a plain DTO. `data` holds the rows, `response`-carries your raw backend payload, and the two methods drive paging. Requests accept a-`pageToken`, so `getNextPage()` is where you call your backend again with the token you held-onto.+`PageResult` is an object with methods, not a plain DTO. `data` holds the rows, `response` carries your raw backend payload, and the two methods drive paging. Requests accept a `pageToken`, so `getNextPage()` is where you call your backend again with the token you held onto.-The `response` type parameter is the shape your endpoint returned — `ListSessionsResponse`,-`ListTurnsResponse`, or `ListSessionEventsResponse`, each `{ data, pagination }` where-`pagination` is a `TokenPagination` of `{ nextPageToken?, previousPageToken?, limit }`.+The `response` type parameter is the shape your endpoint returned — `ListSessionsResponse`, `ListTurnsResponse`, or `ListSessionEventsResponse`, each `{ data, pagination }` where `pagination` is a `TokenPagination` of `{ nextPageToken?, previousPageToken?, limit }`.```tsasync listSessions({ pageToken, limit = 20 } = {}) {@@ -158,8 +136,7 @@ async listSessions({ pageToken, limit = 20 } = {}) {```<Note>- Because `PageResult` carries methods, you cannot return a bare object literal parsed from- JSON. Build it — or write a small helper — so `hasNextPage` and `getNextPage` are present.+ Because `PageResult` carries methods, you cannot return a bare object literal parsed from JSON. Build it — or write a small helper — so `hasNextPage` and `getNextPage` are present.</Note>## Turn input@@ -189,9 +166,7 @@ interface UserToolResponseEvent {}```-A plain chat message arrives as `user.message`. Approving or rejecting a tool call, and-answering a prompt the agent raised, arrive as the other two — all three through the same-`createTurn` entry point, so branch on `type`.+A plain chat message arrives as `user.message`. Approving or rejecting a tool call, and answering a prompt the agent raised, arrive as the other two — all three through the same `createTurn` entry point, so branch on `type`.## Turn state@@ -212,10 +187,7 @@ type TurnState =| { status: "error"; message: string; completedAt: string };```-A turn ends in one of three terminal states, each carrying `completedAt`. A `done` turn may-still carry `requiredActions` — that is how a turn signals it is waiting on the user, such as a-tool approval, rather than being finished outright. The user's reply arrives on the next-`createTurn` call as a `user.tool_approval` or `user.tool_response` input item.+A turn ends in one of three terminal states, each carrying `completedAt`. A `done` turn may still carry `requiredActions` — that is how a turn signals it is waiting on the user, such as a tool approval, rather than being finished outright. The user's reply arrives on the next `createTurn` call as a `user.tool_approval` or `user.tool_response` input item.## AgentBuilderServer@@ -237,8 +209,7 @@ interface AgentBuilderServer {### Capabilities-`getCapabilities` tells the UI which optional features your backend supports, so it can hide-what you do not offer rather than surfacing controls that fail.+`getCapabilities` tells the UI which optional features your backend supports, so it can hide what you do not offer rather than surfacing controls that fail.```tsinterface AgentBuilderCapabilitiesResponse {@@ -250,10 +221,7 @@ interface AgentBuilderCapabilitiesResponse {}```-It is fetched once when the server resolves. `skill.reason` is shown to the user when skills are-disabled, so use it to explain why — for example that no skill registry is configured. Setting-`settings.enabled` to `false` hides the settings control even when a `catalog` is attached;-omitting `settings` leaves it visible.+It is fetched once when the server resolves. `skill.reason` is shown to the user when skills are disabled, so use it to explain why — for example that no skill registry is configured. Setting `settings.enabled` to `false` hides the settings control even when a `catalog` is attached; omitting `settings` leaves it visible.```tsasync getCapabilities() {@@ -261,8 +229,7 @@ async getCapabilities() {}```-Read the resolved value anywhere in your own components with-[`useServerCapabilities()`](/ui-sdk/reference/hooks).+Read the resolved value anywhere in your own components with [`useServerCapabilities()`](/ui-sdk/reference/hooks).### Picker rows@@ -276,16 +243,10 @@ The remaining methods return the minimum each selector renders:| `AgentLibraryEntry` | `name`, `agentId` | `agentSpec` |<Note>- Return a non-empty `reasoningEfforts` on a `ModelSelection` and the UI shows a- reasoning-effort picker beside the model selector. On `AgentLibraryEntry`, `agentId` is the- stable identifier used for selection, history filtering, and session binding — it is required- even when it matches the display `name`. Supply `agentSpec` to enable Edit; omit it for- try-only agents.+ Return a non-empty `reasoningEfforts` on a `ModelSelection` and the UI shows a reasoning-effort picker beside the model selector. On `AgentLibraryEntry`, `agentId` is the stable identifier used for selection, history filtering, and session binding — it is required even when it matches the display `name`. Supply `agentSpec` to enable Edit; omit it for try-only agents.</Note>-`SearchAgentsParams` is `{ query?, limit?, offset? }` — offset paging, since it backs a search-box rather than an infinite list. `SaveAgentRequest` is `{ agentName, agentSpec }`, and its-return value is passed through untyped.+`SearchAgentsParams` is `{ query?, limit?, offset? }` — offset paging, since it backs a search box rather than an infinite list. `SaveAgentRequest` is `{ agentName, agentSpec }`, and its return value is passed through untyped.## AgentSpec@@ -305,14 +266,11 @@ interface Model {Only `model` is required. `instructions` carries the system prompt.-`SkillMount` and `McpServerMount` are typed as `object`. The runtime stores and forwards mounts-without reading any field, and your backend owns their shape — so the base constrains only that-a mount is an object, and you intersect your concrete type over it.+`SkillMount` and `McpServerMount` are typed as `object`. The runtime stores and forwards mounts without reading any field, and your backend owns their shape — so the base constrains only that a mount is an object, and you intersect your concrete type over it.## Widening the types-Every interface takes type parameters defaulting to the SDK-minimal shapes. Supply your own to-carry extra fields through the UI without casting:+Every interface takes type parameters defaulting to the SDK-minimal shapes. Supply your own to carry extra fields through the UI without casting:```tsinterface MyModel extends ModelSelection {@@ -328,8 +286,7 @@ const server: AgentUIServer<AgentChatServer<MySpec>, AgentBuilderServer<MySpec,};```-The UI keeps reading only the fields it knows about; your own components — supplied through-[slot overrides](/ui-sdk/guides/slot-overrides) — can read the rest.+The UI keeps reading only the fields it knows about; your own components — supplied through [slot overrides](/ui-sdk/guides/slot-overrides) — can read the rest.## Next@@ -337,13 +294,16 @@ The UI keeps reading only the fields it knows about; your own components — sup<Card title="Worked implementation" icon="server" href="/ui-sdk/guides/custom-server">A minimal `AgentUIServer` you can copy.</Card>+<Card title="Streaming events" icon="bolt" href="/ui-sdk/reference/events">The event protocol `createTurn` yields.</Card>+<Card title="Settings catalog" icon="sliders" href="/ui-sdk/reference/catalog">The optional `catalog` port behind the settings UI.</Card>+<Card title="Type reference" icon="code" href="/ui-sdk/reference/server">Every exported server type.</Card>-</CardGroup>+</CardGroup>\ No newline at end of file