The open-source agent harness - the runtime layer that turns an LLM into a working agent.
docs: describe optional server ports and public context hooks (#1035)
Rudy Mizrahi Celeklic1fabca4a148
diff --git a/docs/ui-sdk/reference/server.mdx b/docs/ui-sdk/reference/server.mdxindex 972d838cb..2d5366644 100644--- a/docs/ui-sdk/reference/server.mdx+++ b/docs/ui-sdk/reference/server.mdx@@ -9,10 +9,12 @@ description: "Server factory, context hooks, shell mode, and contract types."createTrueForgeServer(options: CreateTrueForgeServerOptions): TrueForgeServer;```-Options: `{ chatServer, getCapabilities, getModels, getSkills, getMcp, searchAgents, saveAgent, deleteAgent?, catalog? }`.+Required options: `{ chatServer, getCapabilities, getModels, getSkills, getMcp, searchAgents, saveAgent }`.Combines a chat server with your agent-management callbacks into a complete `AgentUIServer`.-`deleteAgent` and `catalog` are the only optional entries; if you omit `deleteAgent`, calling it-throws.+Optional callbacks are `getMcpConnector`, `getMcpTools`, `deleteAgent`, and `getMe`.+Optional ports are `catalog`, `sessions`, `metrics`, `schedules`, `sandboxEnvironments`, and+`permissions`; the factory attaches each supplied port to the resulting server.+If you omit `deleteAgent`, calling it throws.## Context@@ -24,6 +26,10 @@ throws.| `useServerCapabilities()` | Resolved `getCapabilities()` data, or `null` while loading or on failure. || `useCatalogServer()` | `server.catalog`; **throws** when absent. || `useOptionalCatalogServer()` | `server.catalog`, or `null` when there is none. |+| `useAgentSessionsServer()` / `useOptionalAgentSessionsServer()` | `server.sessions`; the required hook throws when absent, the optional hook returns `null`. |+| `useAgentMetricsServer()` / `useOptionalAgentMetricsServer()` | `server.metrics`; the required hook throws when absent, the optional hook returns `null`. |+| `useScheduleServer()` / `useOptionalScheduleServer()` | `server.schedules`; the required hook throws when absent, the optional hook returns `null`. |+| `useOptionalPermissionsServer()` | `server.permissions`, or `null` when absent. |## Shell modediff --git a/docs/ui-sdk/setup-custom-servers/server-contract.mdx b/docs/ui-sdk/setup-custom-servers/server-contract.mdxindex 92602527b..805be10c5 100644--- a/docs/ui-sdk/setup-custom-servers/server-contract.mdx+++ b/docs/ui-sdk/setup-custom-servers/server-contract.mdx@@ -29,10 +29,21 @@ asynchronously, so the SDK renders a loading indicator (`role="status"`) for a m## The composed contract```ts-type AgentUIServer = AgentChatServer & AgentBuilderServer & { catalog?: CatalogServer };+type AgentUIServer = AgentChatServer & AgentBuilderServer & {+ catalog?: CatalogServer;+ sessions?: AgentSessionsServer;+ schedules?: ScheduleServer;+ sandboxEnvironments?: SandboxEnvironmentServer;+ metrics?: AgentMetricsServer;+ permissions?: PermissionsServer;+ getMe?: () => Promise<{ tenantId: string }>;+};```-Chat and session operations, agent-builder operations, and an optional settings catalog. Only the first two are required.+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](#widening-the-types) below.