Skip to content

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

6.0 KB
Raw Blame

Public API

Curated exports from @truefoundry/trueforge-ui. Design-system primitives (CenteredModal, Switch, …) are owned in this package. Low-level controls like Button / IconButton are styled via theme tokens / CSS (not SlotsProvider slots); their prop types (ButtonProps, IconButtonProps, …) are exported for hosts that build around those contracts. Component values appear below only when they are part of the public surface.

Quick start

Export Notes
TrueForgeUI Slots + runtime + built-in layout
TrueForgeUIProps, ChatLayout Props / layout union
TrueForgeServerConfig server prop: type: "trueforge" or ready AgentUIServer

Built-in servers

server config What the SDK does
{ type: 'trueforge', baseUrl?, token?, fetch?, catalog? } Dynamic-imports plugins/trueforge-agent-server-adapter → full Harness AgentUIServer
Ready AgentUIServer Passthrough (host-composed or createTrueForgeServer)

TrueForge hosts need @truefoundry/trueforge-sdk. Cookie apps pass fetch; embeds usually pass token.

// Harness / TrueForge
<TrueForgeUI
  server={{ type: 'trueforge', baseUrl: '/', token: process.env.TRUEFORGE_TOKEN }}
  layout="sidebar"
/>

// Or same-origin cookies:
<TrueForgeUI server={{ type: 'trueforge', fetch: authAwareFetch }} layout="sidebar" />

Factory without <TrueForgeUI />:

import { createTrueForgeAgentUIServer } from '@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter';

const server = createTrueForgeAgentUIServer({ baseUrl: '/', token });

The Harness factory includes the optional AgentMetricsServer port used by the agent-detail Metrics tab. Custom servers can provide metrics with getCharts, getMeters, and getChartData; access it with useAgentMetricsServer / useOptionalAgentMetricsServer. The default visual surface is split across the AgentMetrics, AgentMetricsView, AgentMetricsTimeRangeFilter, AgentMetricCard, and AgentMetricChart slots.

The built-in TrueForge config enables permissions automatically through the Harness endpoint and accepts an explicit PermissionsServer override. Custom servers remain permissive unless they provide the optional port. useResourcePermissions reads USE, MANAGE, and DELETE grants, while PermissionGuard keeps denied actions visible and explained.

Compose

Export Notes
TrueForgeChatProvider Named-agent runtime + toasts
TrueForgeChatProviderProps client XOR apiKey+baseUrl
Thread Full thread + composer
ThreadContainer, ComposerContainer, ThreadListContainer Building blocks
ToasterProvider, useToaster, useToasterOptional Success and error toasts
AnalyticsProvider, useTrackAnalytics Host product-analytics sink
AnalyticsEvents, AnalyticsConfig, TrackAnalytics Event catalog + types
Other *Container exports Advanced message / tool wiring

Slots / theme

Export Notes
SlotsProvider, useSlot, defaultSlots Override registry
SlotOverrides, AtomSlots, ThemeMode Types
useTheme, useThemeMode Theme mode
Feature atoms (WelcomeScreen, ComposerShell, bubbles, toasts, …) Defaults + override targets

Chrome / runtime

Export Notes
useAui, useAuiState, AssistantState Also @truefoundry/trueforge-ui/assistant-ui
AgentSessionClient Gateway client
useTrueForgeAgentRuntime, trueForgeAttachmentAdapter, other useTrueForge* Runtime hooks

Types for overrides

Export Notes
ButtonProps, ButtonSize, IconButtonProps Prop contracts for in-package primitives (tokens/CSS, not slots)
Atom *Props types Per-atom override shapes

Styles

Export path Notes
@truefoundry/trueforge-ui/styles.css Tokens + utilities + OpenUI (optional; auto-injected)