Server contract

The server prop accepts either a built-in config object or an object implementing AgentUIServer.

type TrueForgeServerConfig =
  | {
      type: "trueforge";
      baseUrl?: string;
      token?: string;
      fetch?: typeof fetch;
      catalog?: CatalogServer;
      permissions?: PermissionsServer;
    }
  | AgentUIServer;

An AgentUIServer object is used immediately. The built-in trueforge config resolves asynchronously, so the SDK renders a loading indicator (role="status") for a moment first. It loads plugins/trueforge-agent-server-adapter and composes a full Harness AgentUIServer — see Quickstart. catalog and permissions optionally override the adapter’s built-in ports. A custom AgentUIServer can expose the same optional ports directly.

The composed contract

type AgentUIServer = AgentChatServer & AgentBuilderServer & { catalog?: CatalogServer };

Chat and session operations, agent-builder operations, and an optional settings catalog. Only the first two are required. Every interface is generic. The SDK’s types constrain only the fields the UI itself reads, so when your backend returns richer objects you widen the type parameters rather than casting or stripping fields. See widening below.

AgentChatServer

The runtime calls these. All operations are keyed by a flat sessionId.

interface AgentChatServer {
  createSession(req: CreateSessionRequest): Promise<Session>;
  listSessions(req?: ListSessionsParams): Promise<ListResult<Session>>;
  getSession(req: { sessionId: string }): Promise<Session>;
  updateSession(req: UpdateSessionRequest): Promise<Session>;

  createTurn(req: {
    sessionId: string;
    input?: TurnInputItem[];
    previousTurnId?: PreviousTurnIdInput;
    abortSignal?: AbortSignal;
    headers?: Record<string, string>;
  }): AsyncIterable<TurnStreamData>;

  cancelSession(req: { sessionId: string }): Promise<void>;
  deleteSession?(req: { sessionId: string }): Promise<void>;
  renameSession?(req: { sessionId: string; title: string }): Promise<void>;

  listTurns(req: {
    sessionId: string;
    limit?: number;
    pageToken?: string;
    order?: ListSessionsOrder;
  }): Promise<ListResult<Turn>>;
  getTurn(req: { sessionId: string; turnId: string }): Promise<Turn>;

  listEvents(req: {
    sessionId: string;
    pageToken?: string;
    lastTurnId?: string;
    limit?: number;
  }): 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: {
    sessionId: string;
    turnId: string;
    sandboxId: string;
    path: string;
  }): Promise<Blob>;
}

deleteSession and renameSession are optional. Presence gates Delete and Rename in the session list; renameSession persists { sessionId, title }. TrueForge implements both. TrueFoundry Gateway does not persist titles and should omit renameSession. 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.

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.

createTurn and subscribeToTurn yield TurnStreamData, an envelope of { sequenceNumber, event }. The event protocol is documented in Streaming events.

Sessions

interface Session {
  id: string;
  title?: string | null;
  agentName?: string | null;
  agentSpec?: AgentSpec;
  isMutable: boolean;
  createdAt: string;
  updatedAt: string;
}

id, isMutable, createdAt, and updatedAt are required; timestamps are ISO strings. Set isMutable: true while the agent spec may still be edited. renameSession must work for named and inline sessions. CreateSessionRequest is { agentName?, agentSpec?, title? }; UpdateSessionRequest is { sessionId, agentSpec?, title? }.

Pagination

interface ListResult<T> {
  data: T[];
  nextPageToken?: string;
}

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.

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,
    ...(token === undefined ? {} : { nextPageToken: token }),
  };
}

Because ListResult is a plain object, you can return a parsed JSON body directly as long as it exposes data and (optionally) nextPageToken.

Turn input

What the UI sends into createTurn:

type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent;

interface UserMessage {
  type: "user.message";
  content: UserMessageContent;
}

interface UserToolApprovalEvent {
  type: "user.tool_approval";
  threadId: string;
  toolCallId: string;
  approval: { status: "allow" } | { status: "deny"; reason?: string };
}

interface UserToolResponseEvent {
  type: "user.tool_response";
  threadId: string;
  toolCallId: string;
  content: string;
}

A plain chat message arrives as user.message. Approving or rejecting a tool call, and answering a prompt the agent raised, arrive as the other two — all three through the same createTurn entry point, so branch on type.

Turn state

interface Turn {
  id: string;
  sessionId: string;
  previousTurnId?: string | null;
  input?: TurnInputItem[];
  state: TurnState;
  createdAt: string;
}

type TurnState =
  | { status: "running" }
  | { status: "done"; output?: unknown; requiredActions?: unknown[]; completedAt: string }
  | { status: "cancelled"; reason: string; completedAt: string }
  | { status: "error"; message: string; completedAt: string };

A turn ends in one of three terminal states, each carrying completedAt. A done turn may still carry requiredActions — that is how a turn signals it is waiting on the user, such as a tool approval, rather than being finished outright. The user’s reply arrives on the next createTurn call as a user.tool_approval or user.tool_response input item.

AgentBuilderServer

Powers the agent library and the draft composer.

interface AgentBuilderServer {
  getCapabilities(): Promise<AgentBuilderCapabilitiesResponse>;
  getModels(): Promise<ModelSelection[]>;
  getSkills(): Promise<AgentSkill[]>;
  getMcp(): Promise<ConnectorState[]>;
  searchAgents(req?: SearchAgentsParams): Promise<AgentLibraryEntry[]>;
  saveAgent(req: SaveAgentRequest): Promise<SaveAgentResult>;
  deleteAgent?(req: { agentName: string }): Promise<void>;
}

deleteAgent is the only optional method here — the rest must be implemented.

Capabilities

getCapabilities tells the UI which optional features your backend supports, so it can hide what you do not offer rather than surfacing controls that fail.

interface AgentBuilderCapabilitiesResponse {
  data: {
    sandbox: { enabled: boolean };
    skill: { enabled: boolean; reason?: string };
    settings?: { enabled: boolean };
  };
}

It is fetched once when the server resolves. skill.reason is shown to the user when skills are disabled, so use it to explain why — for example that no skill registry is configured. Setting settings.enabled to false hides the settings control even when a catalog is attached; omitting settings leaves it visible.

async getCapabilities() {
  return { data: { sandbox: { enabled: false }, skill: { enabled: true } } };
}

Read the resolved value anywhere in your own components with useServerCapabilities().

Picker rows

The remaining methods return the minimum each selector renders:

Type	Required	Optional
`ModelSelection`	`id`, `name`, `provider`, `properties`	—
`AgentSkill`	`id`, `name`	`description`
`ConnectorState`	`id`, `name`	`description`, `requiresAuth`, `authenticated`
`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: {}).

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.

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

interface AgentSpec {
  model: Model;
  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. 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.

Widening the types

Every interface takes type parameters defaulting to the SDK-minimal shapes. Supply your own to carry extra fields through the UI without casting:

interface MyModel extends ModelSelection {
  modelId: string;
  pricePerMillionTokens: number;
}

type MySkillMount = { fqn: string; preload: boolean };
type MySpec = AgentSpec<Model, MySkillMount>;

const server: AgentChatServer<MySpec> & AgentBuilderServer<MySpec, MyModel> = {
  /* ... */
};

The UI keeps reading only the fields it knows about; your own components — supplied through slot overrides — can read the rest.

Worked implementation

A minimal AgentUIServer you can copy.

Streaming events

The event protocol createTurn yields.

Settings catalog

The optional catalog port behind the settings UI.

Type reference

Every exported server type.

Getting Started

TrueForge Harness

SDK

UI Chat

Project

The composed contract

AgentChatServer

Sessions

Turn input

Turn state

AgentBuilderServer

Capabilities

Picker rows

AgentSpec

Widening the types

Next

Worked implementation

Streaming events

Settings catalog

Type reference

​The composed contract

​AgentChatServer

​Sessions

​Pagination

​Turn input

​Turn state

​AgentBuilderServer

​Capabilities

​Picker rows

​AgentSpec

​Widening the types

​Next

Worked implementation

Streaming events

Settings catalog

Type reference

The composed contract

AgentChatServer

Sessions

Pagination

Turn input

Turn state

AgentBuilderServer

Capabilities

Picker rows

AgentSpec

Widening the types

Next