Skip to main content
TrueForge 0.185.0+ introduces breaking changes to turn lifecycle - turns now pause when waiting for user input. Click here to view the documentation for older versions.
The server prop accepts either a built-in config object or an object implementing 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

Chat and agent-builder operations are required. The optional ports add settings catalogs, agent detail/session views, schedules, sandbox environments, aggregate metrics, and resource permissions. getMe supplies the caller’s tenant identity for sharing. A custom server can attach these ports directly, or pass them to createTrueForgeServer. 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.
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 client reattach to a running or paused turn from an event id instead of replaying it, and is how the UI reads what happens after it answers a paused turn. Omit it and the UI still loads the turn as history, but shows it as unable to resume. 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 { event }. The event protocol is documented in Streaming events.

Sessions

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

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.
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:
createTurn only starts a new turn from a chat message, so input always holds a user.message. Approvals, answers, and MCP sign-in never arrive here - they go to sendTurnEvents on the turn that is waiting for them. previousTurnId places the turn in the conversation. The UI sends "none" for the first turn of a session and "auto" for a normal follow-up (continue from the latest turn). When the user edits or retries a message, it sends the id of the turn before that message (or "none" if it was the first), which starts a branch from there. A new turn can arrive while the previous one is still running or paused, for example when the user types instead of answering a prompt, or edits a message. The UI does not cancel the open turn first, so createTurn must end it, typically as cancelled with reason "cancelled-for-next-turn".

Answering a paused turn

When the agent needs the user, the turn pauses instead of finishing (see Turn state). The UI answers it with sendTurnEvents:
The UI offers the two policy choices only when it can tell which tool a call targets: a tool call whose toolInfo is { type: "mcp", serverName, name }, or a deferred call_tool call whose arguments carry mcp_server and tool_name. Implement sendTurnEvents with these rules:
  • Return what you stored. Persist each event and return it with the id and createdAt you assigned (TurnInboundEvent[]). The UI folds the returned events into the transcript straight away.
  • Do not resume inside the request. Sending an event only records the answer. Once every open request on the turn is answered, continue the turn yourself and announce it on the turn’s stream with turn.update { status: "running" }. A partial answer (one of two approvals) leaves the turn paused.
  • Deliver the rest of the turn to subscribeToTurn. The UI subscribes from the last event it applied before it sends, so everything you emit after the pause - the running update, new content, and the final turn.done - must reach that subscription.
  • Reject stale answers. Throw when an event names a call that is already settled or belongs to another thread, or when the turn has ended. The UI rolls back its optimistic state and reports the error.

Turn state

running and paused are the two active states; done, cancelled, and error are terminal and carry completedAt. A turn waiting on the user is paused, not done: it stays the same turn, and continues once the answers arrive through sendTurnEvents. getTurn and listTurns must report paused for such a turn so a reloaded page shows the pending prompt and reattaches with subscribeToTurn. Turn.input is typed as TurnInputItem[] so turns recorded by older servers, which carried approvals as turn input, still load. New turns only carry user.message.

AgentBuilderServer

Powers the agent library and the draft composer.
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.
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. Omit memory when your backend has no memory provider; the UI then hides every memory setting. With enabled: false, the agent builder’s Memory toggle is locked and shows reason. settings reports one entry per settings section rather than a single switch, so you can open the sections a caller may use and close the rest. A section you omit stays visible, which is what keeps servers written before this existed working. Set enabled: false on a section to hide it; the settings control itself disappears once every section is closed. Use manageProviders: false for a section whose providers your platform owns centrally - the section still opens, but the controls that add or edit providers do not render.
Read the resolved value anywhere in your own components with useServerCapabilities().

Picker rows

The remaining methods return the minimum each selector renders: 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?, pageToken? }. searchAgents returns { data, nextPageToken? }, using the same token pagination as the session lists; pass the returned token as pageToken for the next page. 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

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:
The UI keeps reading only the fields it knows about; your own components - supplied through slot overrides - can read the rest.

Next

Worked implementation

A minimal AgentUIServer you can copy.

Streaming events

The event protocol createTurn and subscribeToTurn yield.

Settings catalog

The optional catalog port behind the settings UI.

Type reference

Every exported server type.