Skip to content

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

2.8 KB
Raw Blame
---
title: "How it fits together"
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="Simply use TrueForgeUI">
    One component, a `server` and a `layout`. It mounts everything it needs internally.
  </Step>
  <Step title="Supply your own layout">
    Pass a component to `layout` and arrange the exported containers yourself.
  </Step>
  <Step title="Mount the providers yourself">
    Skip `TrueForgeUI` entirely and compose the providers directly.
  </Step>
</Steps>

## Containers and atoms

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.

**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/setup-custom-ui/slot-overrides).

## Provider stack

`TrueForgeUI` mounts this for you. You only need it when composing manually:

```tsx
<SlotsProvider overrides={overrides} theme={theme}>
  <ServerProvider server={server}>
    <ShellModeProvider agentConfig={{ mode: "AgentLibrary" }}>
      <TrueForgeChatProvider server={server}>
        <MyLayout />
      </TrueForgeChatProvider>
    </ShellModeProvider>
  </ServerProvider>
</SlotsProvider>
```

Order matters: `SlotsProvider` must be outside `TrueForgeChatProvider`.

<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 `TrueForgeChatProvider` 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.

For token-level changes, prefer [theming](/ui-sdk/setup-custom-ui/custom-theme) over CSS overrides.