Skip to content

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.json
index 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.mdx
index 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 file
diff --git a/docs/ui-sdk/setup-custom-servers/custom-server.mdx b/docs/ui-sdk/setup-custom-servers/custom-server.mdx
index 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 implementation
The 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.
```ts
async 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:
```ts
interface 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.
## Attachments
diff --git a/docs/ui-sdk/setup-custom-servers/server-contract.mdx b/docs/ui-sdk/setup-custom-servers/server-contract.mdx
index 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`.
```ts
interface 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
```ts
interface 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.
```ts
async 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 ca
interface 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>