The open-source agent harness - the runtime layer that turns an LLM into a working agent.
server docs (#208)
Govinda Vashishtha22735efb8f24
diff --git a/docs/docs.json b/docs/docs.jsonindex 59d7f6135..ceda1c93e 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -98,9 +98,9 @@{"group": "Setup Custom Server","pages": [- "ui-sdk/setup-custom-servers/server-contract",+ "ui-sdk/setup-custom-servers/connect-with-truefoundry","ui-sdk/setup-custom-servers/custom-server",- "ui-sdk/setup-custom-servers/connect-with-truefoundry"+ "ui-sdk/setup-custom-servers/server-contract"]},"ui-sdk/guides/troubleshooting"diff --git a/docs/ui-sdk/setup-custom-servers/connect-with-truefoundry.mdx b/docs/ui-sdk/setup-custom-servers/connect-with-truefoundry.mdxindex a59c6b9fe..6b6bf5721 100644--- a/docs/ui-sdk/setup-custom-servers/connect-with-truefoundry.mdx+++ b/docs/ui-sdk/setup-custom-servers/connect-with-truefoundry.mdx@@ -25,4 +25,76 @@ 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.\ No newline at end of file+Because this config is resolved asynchronously, the SDK shows a brief loading indicator before the chat appears. The other two paths mount immediately.++## Build the server yourself++If you need to hold the resolved `AgentUIServer` — to wrap it, log through it, or pass it around before mounting — build it with `createTrueFoundryAgentUIServer`. It returns a ready server (gateway chat plus the Control Plane builder lists) that you hand to `server` directly, so there is no async resolution and no loading indicator on mount.++```tsx App.tsx+import { useEffect, useState } from "react";+import { TrueforgeUI } from "@truefoundry/trueforge-ui";+import {+ createTrueFoundryAgentUIServer,+ type TrueFoundryAgentUIServer,+} from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";++export default function App() {+ const [server, setServer] = useState<TrueFoundryAgentUIServer | null>(null);++ useEffect(() => {+ createTrueFoundryAgentUIServer({+ apiKey: import.meta.env.VITE_TFY_API_KEY,+ cpURL: import.meta.env.VITE_TFY_CONTROL_PLANE_URL,+ }).then(setServer);+ }, []);++ if (server === null) {+ return null;+ }++ return (+ <div style={{ height: "100dvh" }}>+ <TrueforgeUI server={server} layout="sidebar" />+ </div>+ );+}+```++`gatewayURL` is optional — when omitted it is resolved from `cpURL`.++## TrueFoundry chat, your own builder++To keep TrueFoundry's hosted chat streaming but serve the builder surfaces — models, skills, connectors, and the agent library — from your own backend, compose the gateway chat port with your callbacks through `createTrueFoundryServer`. The stubs below return empty lists, which is enough to mount; fill them in as you add agent management.++```jsx App.tsx+import { TrueforgeUI, createTrueFoundryServer } from "@truefoundry/trueforge-ui";+import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";++const chatServer = createTrueFoundryChatServer({+ apiKey: import.meta.env.VITE_TFY_API_KEY,+ baseUrl: import.meta.env.VITE_TFY_GATEWAY_URL,+});++const server = createTrueFoundryServer({+ chatServer,+ getCapabilities: async () => ({+ data: { sandbox: { enabled: false }, skill: { enabled: false } },+ }),+ getModels: async () => [],+ getSkills: async () => [],+ getMcp: async () => [],+ searchAgents: async () => [],+ saveAgent: async () => ({}),+});++export default function App() {+ return (+ <div style={{ height: "100dvh" }}>+ <TrueforgeUI server={server} layout="sidebar" />+ </div>+ );+}+```++To own chat streaming as well — every call, including the `createTurn` event stream, served by your backend — implement the full interface instead: [Bring your own server](/ui-sdk/setup-custom-servers/custom-server).\ No newline at end of filediff --git a/docs/ui-sdk/setup-custom-servers/custom-server.mdx b/docs/ui-sdk/setup-custom-servers/custom-server.mdxindex ba6cc16c7..7c68afb20 100644--- a/docs/ui-sdk/setup-custom-servers/custom-server.mdx+++ b/docs/ui-sdk/setup-custom-servers/custom-server.mdx@@ -3,62 +3,22 @@ title: "Bring your own server"description: "Implement AgentUIServer and pass the object straight to the component."----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.--```jsx App.tsx-import { TrueforgeUI, createTrueFoundryServer } from "@truefoundry/trueforge-ui";-import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";--// this structure will most likely change. Govinda to update this-const chatServer = createTrueFoundryChatServer({- apiKey: import.meta.env.VITE_TFY_API_KEY,- baseUrl: import.meta.env.VITE_TFY_GATEWAY_URL,-});--const server = createTrueFoundryServer({- chatServer,- getCapabilities: async () => ({- data: { sandbox: { enabled: false }, skill: { enabled: false } },- }),- getModels: async () => [],- getSkills: async () => [],- getMcp: async () => [],- searchAgents: async () => [],- saveAgent: async () => ({}),-});--export default function App() {- return (- <div style={{ height: "100dvh" }}>- <TrueforgeUI server={server} layout="sidebar" />- </div>- );-}-```--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).+Use this when your backend owns the whole contract — sessions, chat streaming, and the agent builder. You implement `AgentUIServer` and pass the object straight to the component, with no `type` wrapper: every call the UI makes, including the `createTurn` event stream, hits your endpoints. Nothing here depends on TrueFoundry.Because `server` accepts an `AgentUIServer` directly, you can front any backend — including your own proxy that keeps API keys server-side. The object is used immediately, so there is no loading indicator on mount.+<Note>+ To keep TrueFoundry's hosted chat and supply only your own builder callbacks, use the composition helpers on [Connect with TrueFoundry](/ui-sdk/setup-custom-servers/connect-with-truefoundry#truefoundry-chat-your-own-builder) instead. This page assumes your backend serves everything.+</Note>+## Minimal implementationThe shape below is the smallest thing that mounts. Optional methods are omitted; required ones must exist even if they only throw in paths your UI never reaches.-List methods return a `PageResult`, which carries methods as well as data — so a small helper for the single-page case keeps the boilerplate in one place.+List methods return a `ListResult<T>` — a plain object of `{ data, nextPageToken? }`. There are no methods on it, so you can return a parsed JSON body directly as long as it carries those two fields.```ts title="server.ts"-import type { AgentUIServer, PageResult, Session } from "@truefoundry/trueforge-ui";--function onePage<T>(data: T[]): PageResult<T> {- return {- data,- response: undefined,- hasNextPage: () => false,- getNextPage: () => Promise.reject(new Error("no more pages")),- };-}+import type { AgentUIServer, Session } from "@truefoundry/trueforge-ui";const now = new Date().toISOString();const session: Session = {@@ -74,7 +34,7 @@ export const server: AgentUIServer = {return session;},async listSessions() {- return onePage([session]);+ return { data: [session] };},async getSession() {return session;@@ -96,13 +56,13 @@ export const server: AgentUIServer = {await fetch(`/api/sessions/${sessionId}/cancel`, { method: "POST" });},async listTurns() {- return onePage([]);+ return { data: [] };},async getTurn({ turnId }) {throw new Error(`unknown turn ${turnId}`);},async listEvents() {- return onePage([]);+ return { data: [] };},// builder@@ -110,7 +70,9 @@ export const server: AgentUIServer = {return { data: { sandbox: { enabled: false }, skill: { enabled: false } } };},async getModels() {- return [{ name: "my-model", provider: "my-provider" }];+ return [+ { id: "my-model", name: "My model", provider: { name: "my-provider" }, properties: {} },+ ];},async getSkills() {return [];@@ -183,22 +145,21 @@ Two things are easy to get wrong. Deltas carry the _increment_ rather than the a## Pagination-`PageResult<T, R>` carries `data` (the rows), `response` (your raw backend payload), and the methods `hasNextPage()` and `getNextPage()`. Page tokens travel the other way: requests accept a `pageToken`, so `getNextPage()` calls your backend again with the token you kept.+`ListResult<T>` is `{ data: T[]; nextPageToken?: string }`. Return the next cursor in `nextPageToken`; omit it (or leave it `undefined`) on the last page. Tokens travel the other way too — list requests accept a `pageToken`, which the SDK feeds back to fetch the following page.```tsasync listSessions({ pageToken, limit = 20 } = {}) {const res = await fetch(`/api/sessions?limit=${limit}&cursor=${pageToken ?? ""}`);const body = await res.json(); // { data, pagination }+ const token = body.pagination?.nextPageToken;return {data: body.data,- response: body,- hasNextPage: () => Boolean(body.pagination.nextPageToken),- getNextPage: () => this.listSessions({ pageToken: body.pagination.nextPageToken, limit }),+ ...(token === undefined ? {} : { nextPageToken: token }),};}```-Because the result carries methods, you cannot hand back a bare parsed JSON object — construct it, or reuse a helper like the `onePage` above.+Spreading `nextPageToken` in only when present keeps the result valid under `exactOptionalPropertyTypes`; assigning `undefined` to the optional field directly is rejected there.`listEvents` additionally accepts `lastTurnId`, used when hydrating history for an existing session.@@ -206,7 +167,7 @@ Because the result carries methods, you cannot hand back a bare parsed JSON obje<AccordionGroup><Accordion title="deleteSession / deleteAgent">- In a hand-written `AgentUIServer` like the one above, omitting these leaves the corresponding affordances unavailable rather than broken. (This differs from `createTrueFoundryServer`, where an omitted `deleteAgent` throws when called.)+ In a hand-written `AgentUIServer` like the one above, omitting these leaves the corresponding affordances unavailable rather than broken. (This differs from the [`createTrueFoundryServer` composition helper](/ui-sdk/setup-custom-servers/connect-with-truefoundry#truefoundry-chat-your-own-builder), where an omitted `deleteAgent` throws when called.)</Accordion><Accordion title="downloadSandboxFile">@@ -224,7 +185,7 @@ Because the result carries methods, you cannot hand back a bare parsed JSON obje## Widening the types-The interfaces are generic so you can carry backend-specific fields through the UI without casting. `AgentUIServer` takes the chat port, the builder port, and the catalog:+The interfaces are generic so you can carry backend-specific fields through the UI without casting. `AgentUIServer` itself is a plain alias, so compose the widened chat and builder ports directly:```tsinterface MyModel extends ModelSelection {@@ -234,15 +195,12 @@ interface MyModel extends ModelSelection {type MySkillMount = { fqn: string; preload: boolean };type MySpec = AgentSpec<Model, MySkillMount>;-const server: AgentUIServer<- AgentChatServer<MySpec>,- AgentBuilderServer<MySpec, MyModel>-> = {+const server: AgentChatServer<MySpec> & AgentBuilderServer<MySpec, MyModel> = {/* ... */};```-See [Widening the types](/ui-sdk/concepts/server-contract#widening-the-types) for the full set of parameters.+See [Widening the types](/ui-sdk/setup-custom-servers/server-contract#widening-the-types) for the full set of parameters.## Attachmentsdiff --git a/docs/ui-sdk/setup-custom-servers/server-contract.mdx b/docs/ui-sdk/setup-custom-servers/server-contract.mdxindex c06dfed53..76a7dca77 100644--- a/docs/ui-sdk/setup-custom-servers/server-contract.mdx+++ b/docs/ui-sdk/setup-custom-servers/server-contract.mdx@@ -39,7 +39,7 @@ The runtime calls these. All operations are keyed by a flat `sessionId`.```tsinterface AgentChatServer {createSession(req: CreateSessionRequest): Promise<Session>;- listSessions(req?: ListSessionsParams): Promise<PageResult<Session, ListSessionsResponse>>;+ listSessions(req?: ListSessionsParams): Promise<ListResult<Session>>;getSession(req: { sessionId: string }): Promise<Session>;updateSession(req: UpdateSessionRequest): Promise<Session>;@@ -47,6 +47,8 @@ interface AgentChatServer {sessionId: string;input?: TurnInputItem[];previousTurnId?: PreviousTurnIdInput;+ abortSignal?: AbortSignal;+ headers?: Record<string, string>;}): AsyncIterable<TurnStreamData>;cancelSession(req: { sessionId: string }): Promise<void>;@@ -56,7 +58,8 @@ interface AgentChatServer {sessionId: string;limit?: number;pageToken?: string;- }): Promise<PageResult<Turn, ListTurnsResponse>>;+ order?: ListSessionsOrder;+ }): Promise<ListResult<Turn>>;getTurn(req: { sessionId: string; turnId: string }): Promise<Turn>;listEvents(req: {@@ -64,12 +67,21 @@ interface AgentChatServer {pageToken?: string;lastTurnId?: string;limit?: number;- }): Promise<PageResult<SessionEventItem, ListSessionEventsResponse>>;+ }): Promise<ListResult<SessionEventItem>>;++ listTurnEvents?(req: {+ sessionId: string;+ turnId: string;+ limit?: number;+ pageToken?: string;+ order?: ListSessionsOrder;+ }): Promise<ListResult<TurnEvent>>;subscribeToTurn?(req: {sessionId: string;turnId: string;afterSequenceNumber?: number;+ abortSignal?: AbortSignal;}): AsyncIterable<TurnStreamData>;downloadSandboxFile?(req: {@@ -81,7 +93,7 @@ interface AgentChatServer {}```-Three methods are optional. `deleteSession` gates the delete control in the session list. `subscribeToTurn` lets a reconnecting client resume a stream from `afterSequenceNumber` rather than replaying it. `downloadSandboxFile` enables artifact downloads.+Four methods are optional. `deleteSession` gates the delete control in the session list. `listTurnEvents` hydrates the events of a single in-flight turn when your backend can serve them per turn. `subscribeToTurn` lets a reconnecting client resume a stream from `afterSequenceNumber` rather than replaying it — pass the same `abortSignal` you use on `createTurn` to tear it down. `downloadSandboxFile` enables artifact downloads.<Note>`downloadSandboxFile` receives both `turnId` and `sandboxId` because backends address sandboxes differently. If your download route is scoped to a turn, resolve the sandbox from `turnId` and ignore `sandboxId`; if you address sandboxes directly, use `sandboxId`.@@ -94,8 +106,8 @@ Three methods are optional. `deleteSession` gates the delete control in the sess```tsinterface Session {id: string;- title?: string;- agentName?: string;+ title?: string | null;+ agentName?: string | null;agentSpec?: AgentSpec;isMutable: boolean;createdAt: string;@@ -110,33 +122,28 @@ interface Session {## Pagination```ts-interface PageResult<T, R = unknown> {+interface ListResult<T> {data: T[];- response: R;- hasNextPage(): boolean;- getNextPage(): Promise<PageResult<T, R>>;+ nextPageToken?: string;}```-`PageResult` is an object with methods, not a plain DTO. `data` holds the rows, `response` carries your raw backend payload, and the two methods drive paging. Requests accept a `pageToken`, so `getNextPage()` is where you call your backend again with the token you held onto.--The `response` type parameter is the shape your endpoint returned — `ListSessionsResponse`, `ListTurnsResponse`, or `ListSessionEventsResponse`, each `{ data, pagination }` where `pagination` is a `TokenPagination` of `{ nextPageToken?, previousPageToken?, limit }`.+`ListResult` is a plain DTO — `data` holds the rows and `nextPageToken` carries the cursor for the next page, absent on the last page. Requests accept a matching `pageToken`, which the SDK feeds back on the following call.```tsasync listSessions({ pageToken, limit = 20 } = {}) {const res = await fetch(`/api/sessions?limit=${limit}&cursor=${pageToken ?? ""}`);const body = await res.json(); // { data, pagination }+ const token = body.pagination?.nextPageToken;return {data: body.data,- response: body,- hasNextPage: () => Boolean(body.pagination.nextPageToken),- getNextPage: () => this.listSessions({ pageToken: body.pagination.nextPageToken, limit }),+ ...(token === undefined ? {} : { nextPageToken: token }),};}```<Note>- Because `PageResult` carries methods, you cannot return a bare object literal parsed from JSON. Build it — or write a small helper — so `hasNextPage` and `getNextPage` are present.+ Because `ListResult` is a plain object, you can return a parsed JSON body directly as long as it exposes `data` and (optionally) `nextPageToken`.</Note>## Turn input@@ -174,7 +181,7 @@ A plain chat message arrives as `user.message`. Approving or rejecting a tool cainterface Turn {id: string;sessionId: string;- previousTurnId?: string;+ previousTurnId?: string | null;input?: TurnInputItem[];state: TurnState;createdAt: string;@@ -200,7 +207,7 @@ interface AgentBuilderServer {getSkills(): Promise<AgentSkill[]>;getMcp(): Promise<ConnectorState[]>;searchAgents(req?: SearchAgentsParams): Promise<AgentLibraryEntry[]>;- saveAgent(req: SaveAgentRequest): Promise<unknown>;+ saveAgent(req: SaveAgentRequest): Promise<SaveAgentResult>;deleteAgent?(req: { agentName: string }): Promise<void>;}```@@ -237,16 +244,18 @@ The remaining methods return the minimum each selector renders:| Type | Required | Optional || --- | --- | --- |-| `ModelSelection` | `name`, `provider` | `reasoningEfforts?: string[]` |+| `ModelSelection` | `id`, `name`, `provider`, `properties` | — || `AgentSkill` | `id`, `name` | `description` || `ConnectorState` | `id`, `name` | `description`, `requiresAuth`, `authenticated` |-| `AgentLibraryEntry` | `name`, `agentId` | `agentSpec` |+| `AgentLibraryEntry` | `name` | `agentId`, `agentSpec` |++`provider` is a `{ name; logo? }` object, and `properties` is a `{ reasoningEfforts?: string[] }` object — both are required on the row even when empty (`properties: {}`).<Note>- Return a non-empty `reasoningEfforts` on a `ModelSelection` and the UI shows a reasoning-effort picker beside the model selector. On `AgentLibraryEntry`, `agentId` is the stable identifier used for selection, history filtering, and session binding — it is required even when it matches the display `name`. Supply `agentSpec` to enable Edit; omit it for try-only agents.+ Return a non-empty `properties.reasoningEfforts` on a `ModelSelection` and the UI shows a reasoning-effort picker beside the model selector. On `AgentLibraryEntry`, `agentId` is the stable identifier used for selection, history filtering, and session binding; omit it and the row falls back to `name`. Supply `agentSpec` to enable Edit; omit it for try-only agents.</Note>-`SearchAgentsParams` is `{ query?, limit?, offset? }` — offset paging, since it backs a search box rather than an infinite list. `SaveAgentRequest` is `{ agentName, agentSpec, intent, sessionId? }`, where `intent` is `"create"` for a new agent and `"update"` when the chat is already bound to one, and its return value is passed through untyped.+`SearchAgentsParams` is `{ query?, limit?, offset? }` — offset paging, since it backs a search box rather than an infinite list. `SaveAgentRequest` is `{ agentName, agentSpec, intent, sessionId? }`, where `intent` is `"create"` for a new agent and `"update"` when the chat is already bound to one. It returns a `SaveAgentResult` of `{ agentId?, sessionUpdatedAt? }` — `agentId` is the id the host registry allocated, and `sessionUpdatedAt` is set when the active mutable session was updated in the same call.## AgentSpec@@ -256,15 +265,23 @@ interface AgentSpec {instructions?: string;skills?: SkillMount[];mcpServers?: McpServerMount[];+ config?: AgentRuntimeConfig;+ variables?: Record<string, string>;}interface Model {name: string;params?: { maxTokens?: number; reasoningEffort?: string };}++interface AgentRuntimeConfig {+ generativeUi?: { enabled?: boolean };+ dynamicSubAgents?: { enabled?: boolean };+ askUserQuestions?: { enabled?: boolean };+}```-Only `model` is required. `instructions` carries the system prompt.+Only `model` is required. `instructions` carries the system prompt. `config` toggles runtime features per agent (generative UI, dynamic sub-agents, ask-user questions), and `variables` holds string substitutions the backend interpolates.`SkillMount` and `McpServerMount` are typed as `object`. The runtime stores and forwards mounts without reading any field, and your backend owns their shape — so the base constrains only that a mount is an object, and you intersect your concrete type over it.@@ -281,7 +298,7 @@ interface MyModel extends ModelSelection {type MySkillMount = { fqn: string; preload: boolean };type MySpec = AgentSpec<Model, MySkillMount>;-const server: AgentUIServer<AgentChatServer<MySpec>, AgentBuilderServer<MySpec, MyModel>> = {+const server: AgentChatServer<MySpec> & AgentBuilderServer<MySpec, MyModel> = {/* ... */};```@@ -291,7 +308,7 @@ The UI keeps reading only the fields it knows about; your own components — sup## Next<CardGroup cols={2}>- <Card title="Worked implementation" icon="server" href="/ui-sdk/guides/custom-server">+ <Card title="Worked implementation" icon="server" href="/ui-sdk/setup-custom-servers/custom-server">A minimal `AgentUIServer` you can copy.</Card>