Skip to content

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.mdx
index 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 fi
Two 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-over
Order 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 file
diff --git a/docs/ui-sdk/get-started/installation.mdx b/docs/ui-sdk/get-started/installation.mdx
index 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 file
diff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdx
index 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 file
diff --git a/docs/ui-sdk/index.mdx b/docs/ui-sdk/index.mdx
index 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"
- />
+ ![The TrueForge UI SDK rendering an agent chat with an expandable agent-steps panel and a streamed response](/images/hero.png)
</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