The open-source agent harness - the runtime layer that turns an LLM into a working agent.
[SDK UI Docs] Getting started updates (#121)
qaifi-tf6a7f0c2e5943
diff --git a/docs/ui-sdk/concepts/architecture.mdx b/docs/ui-sdk/concepts/architecture.mdxindex 12d74b692..d78b785de 100644--- a/docs/ui-sdk/concepts/architecture.mdx+++ b/docs/ui-sdk/concepts/architecture.mdx@@ -6,7 +6,7 @@ description: "The pieces you compose: providers, layouts, containers, and slots.You can use the SDK at three levels of control. Most applications stay at the first.<Steps>- <Step title="Drop in TrueforgeUI">+ <Step title="Simply use TrueforgeUI">One component, a `server` and a `layout`. It mounts everything it needs internally.</Step><Step title="Supply your own layout">@@ -21,16 +21,11 @@ You can use the SDK at three levels of control. Most applications stay at the fiTwo kinds of component are exported, and the distinction determines which one you reach for.-**Containers** are connected to the chat runtime. `ThreadContainer`, `ComposerContainer`, and-`ThreadListContainer` know how to read messages, stream responses, and switch sessions. They-take few props because they get their data from context. Use them to assemble a layout.+**Containers** are connected to the chat runtime. `ThreadContainer`, `ComposerContainer`, and `ThreadListContainer` know how to read messages, stream responses, and switch sessions. They take few props because they get their data from context. Use them to assemble a layout.-**Atoms** are presentational. `AssistantMessageBubble`, `ComposerShell`, and `ToolCallCard`-take everything they render as props and hold no runtime state. You rarely render an atom-directly — instead you replace one, and the container that renders it picks up your version.+**Atoms** are presentational. `AssistantMessageBubble`, `ComposerShell`, and `ToolCallCard` take everything they render as props and hold no runtime state. You rarely render an atom directly — instead you replace one, and the container that renders it picks up your version.-That replacement is what `overrides` does: name a component, supply your own, and it is used-everywhere that component appears. See [Slot overrides](/ui-sdk/guides/slot-overrides).+That replacement is what `overrides` does: name a component, supply your own, and it is used everywhere that component appears. See [Slot overrides](/ui-sdk/guides/slot-overrides).## Provider stack@@ -51,18 +46,11 @@ everywhere that component appears. See [Slot overrides](/ui-sdk/guides/slot-overOrder matters: `SlotsProvider` must be outside `TrueFoundryChatProvider`.<Warning>- Composing manually means you own runtime resets. `TrueforgeUI` remounts the chat runtime- when the selected agent changes, a new draft starts, or the chat is cleared; a hand-rolled- stack does not. Change the `key` on `TrueFoundryChatProvider` yourself at those moments, or- stale messages carry over between agents.+ Composing manually means you own runtime resets. `TrueforgeUI` remounts the chat runtime when the selected agent changes, a new draft starts, or the chat is cleared; a hand-rolled stack does not. Change the `key` on `TrueFoundryChatProvider` yourself at those moments, or stale messages carry over between agents.</Warning>## Styling hooks-These class names and attributes are stable and safe to target from your own CSS:-`.aui-root`, `.aui-theme-root`, `.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`,-`.aui-monaco`, plus `data-slot` attributes on individual components. Most slot values are-prefixed `aui_`, but not all — `avatar`, `tool-call-card`, and `tool-group-card` are among the-unprefixed ones, so inspect the element rather than assuming the prefix.+These class names and attributes are stable and safe to target from your own CSS: `.aui-root`, `.aui-theme-root`, `.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`, `.aui-monaco`, plus `data-slot` attributes on individual components. Most slot values are prefixed `aui_`, but not all — `avatar`, `tool-call-card`, and `tool-group-card` are among the unprefixed ones, so inspect the element rather than assuming the prefix.-For token-level changes, prefer [theming](/ui-sdk/guides/theming) over CSS overrides.+For token-level changes, prefer [theming](/ui-sdk/guides/theming) over CSS overrides.\ No newline at end of filediff --git a/docs/ui-sdk/get-started/installation.mdx b/docs/ui-sdk/get-started/installation.mdxindex b8d6cba1e..c709e6e29 100644--- a/docs/ui-sdk/get-started/installation.mdx+++ b/docs/ui-sdk/get-started/installation.mdx@@ -21,10 +21,7 @@ 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. The package is ESM-only and client-only.+`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.## Import the stylesheet@@ -35,23 +32,22 @@ The SDK ships a prebuilt stylesheet. Import it after Tailwind in your host CSS:@import "@truefoundry/trueforge-ui/styles.css";```-`@truefoundry/trueforge-ui/styles.css` is the only stylesheet path you should reference. It is-self-contained — the SDK's own components are styled without any Tailwind setup on your side.+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.-It deliberately omits Tailwind preflight so it cannot clobber your app's base styles. The-`@import "tailwindcss"` line above is therefore for *your* styles, not the SDK's; drop it if-your app does not use Tailwind.+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 brings in markdown styles scoped to `.markdown-body`, plus the semantic-design tokens. Note that most tokens are applied as inline styles at runtime, so overriding them-from your own CSS will not work — change them through `theme.tokens` instead. See-[Theming](/ui-sdk/guides/theming#precedence).+The stylesheet also includes:++- Markdown styles scoped to .markdown-body+- Semantic design tokens++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.++See [Theming](/ui-sdk/guides/theming#precedence) for details.## 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"*.+`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>@@ -80,18 +76,13 @@ export default defineConfig({</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.+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.+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.+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">@@ -99,4 +90,4 @@ resolved height collapses the entire chat UI, which is the single most common ca</div>```-Next: [Quickstart](/ui-sdk/get-started/quickstart).+Next: [Quickstart](/ui-sdk/get-started/quickstart).\ No newline at end of filediff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdxindex 8153d4ddf..5c1f97d7c 100644--- a/docs/ui-sdk/get-started/quickstart.mdx+++ b/docs/ui-sdk/get-started/quickstart.mdx@@ -3,19 +3,19 @@ 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.+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.-Then pick a backend. The `server` prop takes one of three shapes, and everything else about the-component is identical between them.+Then pick a backend. The `server` prop takes one of three shapes, and everything else about the component is identical between them.<CardGroup cols={3}>- <Card title="TrueFoundry" icon="bolt" href="#truefoundry">- Zero config. Point at a control plane and go.+ <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>+<Card title="Custom" icon="wrench" href="#custom">Compose or implement the server yourself.</Card>@@ -23,8 +23,7 @@ component is identical between them.## 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.+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";@@ -47,8 +46,7 @@ export default function App() {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.+Because this config is resolved asynchronously, the SDK shows a brief loading indicator before the chat appears. The other two paths mount immediately.## TrueForge@@ -65,19 +63,14 @@ 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.+ 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.+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.+`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";@@ -110,15 +103,9 @@ export default function App() {}```-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.+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.-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).+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).## Where to go next@@ -126,13 +113,16 @@ any backend, not just TrueFoundry — see<Card title="Pick a layout" icon="table-columns" href="/ui-sdk/guides/layouts">Sidebar, drawer, dock, widget, or a layout you write yourself.</Card>+<Card title="Match your brand" icon="palette" href="/ui-sdk/guides/theming">Presets, semantic tokens, logo, and dark mode.</Card>+<Card title="Swap components" icon="puzzle-piece" href="/ui-sdk/guides/slot-overrides">Replace any built-in component via `overrides`.</Card>+<Card title="Server contract" icon="server" href="/ui-sdk/concepts/server-contract">Every interface a backend must satisfy.</Card>-</CardGroup>+</CardGroup>\ No newline at end of filediff --git a/docs/ui-sdk/index.mdx b/docs/ui-sdk/index.mdxindex b304df235..70799f86f 100644--- a/docs/ui-sdk/index.mdx+++ b/docs/ui-sdk/index.mdx@@ -3,42 +3,54 @@ title: "TrueForge UI SDK"description: "A themeable React SDK for building AI agent chat applications."----`@truefoundry/trueforge-ui` gives you a production-ready agent chat experience — streaming-responses, session history, tool calls with approvals, sub-agents, reasoning traces,-attachments, and an agent library — as a single React component you can drop into an-existing app. It is built on [assistant-ui](https://www.assistant-ui.com/) and follows-shadcn/ui conventions, so branding, layout, and individual components stay under your-control.+`@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+- Reasoning traces+- Model, MCP, Skill and Sandbox connector+- Configurable server - TrueForge, TrueFoundry or fully custom++The 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 feel<Frame caption="A TrueForge UI chat session — streaming response, agent steps, and tool calls.">- <img- src="/images/hero.png"- alt="The TrueForge UI SDK rendering an agent chat with an expandable agent-steps panel and a streamed response"- />+ </Frame><CardGroup cols={2}><Card title="Installation" icon="download" href="/ui-sdk/get-started/installation">Install the package, wire up the stylesheet, and satisfy the peer dependencies.</Card>+<Card title="Quickstart" icon="rocket" href="/ui-sdk/get-started/quickstart">A working chat UI in about fifteen lines of JSX.</Card>+<Card title="Architecture" icon="layer-group" href="/ui-sdk/concepts/architecture">How atoms, containers, layouts, and slots fit together.</Card>+<Card title="API reference" icon="code" href="/ui-sdk/reference/trueforge-ui">Every export, prop, and type.</Card></CardGroup>-## What you get+## Interactive Controls & Code Examples++The hosted webapp provides an interactive interface for exploring and configuring all available controls and properties.++You can:++- Configure and preview component properties+- Override default settings+- Generate a code snippet based on your configuration-The SDK ships one entry component, `TrueforgeUI`, which mounts its own provider stack and-renders either one of four built-in layouts or a layout you write. Everything below that is-prop-driven: pick a server, pick a layout, optionally pass a theme and a set of slot overrides.+This provides a simple way to experiment with configurations and quickly integrate the resulting setup into your application.-Backends are pluggable. Point the SDK at a TrueFoundry control plane, or implement the-`AgentUIServer` interface yourself and hand the object straight to the component. A third-option, `type: "trueforge"` for the harness adapter, is typed but not yet implemented. The-[quickstart](/ui-sdk/get-started/quickstart) covers all three.+[https://ui.trueforge.dev/](https://ui.trueforge.dev/)\ No newline at end of file