Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

docs(ui-sdk): simplify quickstart and split frontend/server nav (#243)

Govinda Vashishthaf34b909b10c9
diff --git a/docs/docs.json b/docs/docs.json
index ceda1c93e..08e484bbe 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -89,23 +89,23 @@
"pages": ["ui-sdk/index", "ui-sdk/get-started/quickstart"]
},
{
- "group": "Guides",
+ "group": "Frontend Customisation",
"pages": [
"ui-sdk/guides/layouts",
"ui-sdk/guides/layouts-and-theme",
"ui-sdk/guides/agent-modes",
"ui-sdk/setup-custom-ui/custom-theme",
- {
- "group": "Setup Custom Server",
- "pages": [
- "ui-sdk/setup-custom-servers/connect-with-truefoundry",
- "ui-sdk/setup-custom-servers/custom-server",
- "ui-sdk/setup-custom-servers/server-contract"
- ]
- },
"ui-sdk/guides/troubleshooting"
]
},
+ {
+ "group": "Server Customisations",
+ "pages": [
+ "ui-sdk/setup-custom-servers/connect-with-truefoundry",
+ "ui-sdk/setup-custom-servers/custom-server",
+ "ui-sdk/setup-custom-servers/server-contract"
+ ]
+ },
{
"group": "API reference",
"pages": [
diff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdx
index 2b64f8f10..0dde55e85 100644
--- a/docs/ui-sdk/get-started/quickstart.mdx
+++ b/docs/ui-sdk/get-started/quickstart.mdx
@@ -21,21 +21,11 @@ yarn add @truefoundry/trueforge-ui @truefoundry/trueforge-sdk
</CodeGroup>
-`react` and `react-dom` are required peer dependencies and must be version 18 or 19.
+`react` and `react-dom` are required peer dependencies (version 18 or 19).
-`@truefoundry/trueforge-sdk` is the HTTP client used by the built-in Harness adapter
-(`type: "trueforge"`). It stays external to the UI bundle — install it alongside the UI package.
+## Render the UI
-## Connect with TrueForge Server
-
-Pass `server={{ type: "trueforge", … }}`. The SDK dynamically loads
-`@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter`, builds the HTTP client, and
-composes chat + builder + default settings catalogs into an `AgentUIServer`.
-
-Auth is host-owned: use a **Bearer `token`** for embeds / remote APIs, or inject **`fetch`** for
-same-origin cookie / OIDC sessions. `baseUrl` defaults to `'/'`.
-
-### Bearer token
+Point `TrueforgeUI` at your TrueForge server with a Bearer token:
```tsx App.tsx
import { TrueforgeUI } from "@truefoundry/trueforge-ui";
@@ -45,9 +35,7 @@ export default function App() {
<div style={{ height: "100dvh" }}>
<TrueforgeUI
server={{
- type: "trueforge",
- baseUrl: "http://localhost:8790", // optional; default '/'
- token: process.env.TRUEFORGE_TOKEN!,
+ type: "trueforge"
}}
layout="sidebar"
/>
@@ -56,75 +44,7 @@ export default function App() {
}
```
-### Cookie / same-origin hosts
-
-Omit `token` and pass a custom `fetch` (for example an auth-aware wrapper that follows OIDC cookies
-and redirects on HTTP 401):
-
-```tsx App.tsx
-import { TrueforgeUI } from "@truefoundry/trueforge-ui";
-
-export default function App({ authAwareFetch }: { authAwareFetch: typeof fetch }) {
- return (
- <div style={{ height: "100dvh" }}>
- <TrueforgeUI
- server={{
- type: "trueforge",
- baseUrl: "/",
- fetch: authAwareFetch,
- }}
- layout="sidebar"
- agentConfig={{
- mode: "AgentLibraryWithComposer",
- // Seed from your models list at boot when the composer needs a default.
- defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } },
- }}
- />
- </div>
- );
-}
-```
-
-Optional: pass `catalog` on the config to override the built-in settings catalogs.
-
-Because this config is resolved asynchronously (dynamic import of the adapter), the SDK shows a
-brief loading indicator before the chat appears.
-
-## Build the server yourself
-
-If you need the resolved `AgentUIServer` outside `<TrueforgeUI />` — to wrap it, log through it, or
-pass it around before mounting — use the plugin factory:
-
-```tsx
-import { createTrueForgeAgentUIServer } from "@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter";
-import { TrueforgeUI } from "@truefoundry/trueforge-ui";
-
-const server = createTrueForgeAgentUIServer({
- baseUrl: "http://localhost:8790",
- token: process.env.TRUEFORGE_TOKEN!,
-});
-
-export default function App() {
- return (
- <div style={{ height: "100dvh" }}>
- <TrueforgeUI server={server} layout="sidebar" />
- </div>
- );
-}
-```
-
-## Other backends
-
-| Path | Docs |
-| --- | --- |
-| TrueFoundry control plane (`type: "truefoundry"`) | [Connect with TrueFoundry](/ui-sdk/setup-custom-servers/connect-with-truefoundry) |
-| Bring your own `AgentUIServer` | [Custom server](/ui-sdk/setup-custom-servers/custom-server) |
-| Full `server` type union | [Server contract](/ui-sdk/setup-custom-servers/server-contract) |
-
-## Rendered UI
-
-When you run the app, you get a fully functional agent chat experience out of the box, with
-streaming responses, conversation history, and tool-call support.
+That is enough to get a full agent chat with streaming, history, and tool calls.
<Frame caption="What `TrueforgeUI` renders — a full agent chat with streaming, history, and tool calls.">
![The TrueforgeUI component rendering an agent chat with an agent-steps panel and a streamed response](/images/agent-composer-with-library.png)
diff --git a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
index ef8900b01..cc46312f0 100644
--- a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
+++ b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx
@@ -11,11 +11,26 @@ Pass design tokens on the theme object to override component styles. You can als
type ThemeConfig = {
...
tokens?: Partial<SemanticTokens>;
- icons?: IconMap;
...
};
```
+Pass the theme object on `TrueforgeUI`:
+
+```tsx App.tsx
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ theme={{
+ tokens: {
+ primaryButtonBg: "#6366F1",
+ userMessageBg: "#6366F1",
+ // ...other tokens
+ },
+ }}
+/>
+```
+
## The token object
Override individual design tokens to change colors and other visual properties: sidebar, page background, popups, buttons, inputs, and the rest of the surfaces listed below.
@@ -115,46 +130,3 @@ Those tokens map to CSS variables:
--composer-radius
```
Changing a few semantic tokens updates the UI consistently without writing component-specific CSS.
-
-## Styling rendered content
-
-`theme.classNames` (`ContentClassNames`) adds host CSS classes onto content renderers. Pass it through `theme` on `TrueforgeUI` (or `SlotsProvider`):
-
-```tsx
-<TrueforgeUI
- theme={{
- classNames: {
- markdown: "prose prose-sm",
- openui: { root: "my-openui" },
- },
- }}
- /* … */
-/>
-```
-
-```ts
-type ContentClassNames = {
- /** Root of the markdown renderer (joins `.aui-markdown`). */
- markdown?: string;
- /** Inline `` `code` `` spans inside markdown. */
- inlineCode?: string;
- syntaxHighlighter?: {
- root?: string; // joins `.aui-syntax-highlighter`
- pre?: string;
- code?: string;
- lineNumber?: string;
- };
- openui?: {
- root?: string; // joins `.aui-openui`
- scope?: string; // OpenUI theme scope (`.markdown-openui-scope`)
- };
- monaco?: {
- root?: string; // joins `.aui-monaco`
- editor?: string; // Monaco mount container
- /** Monaco theme name; when unset, follows light/dark mode. */
- monacoTheme?: string;
- };
-};
-```
-
-For CSS-only adjustments you can instead target the stable class names directly: `.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`, `.aui-monaco`.