Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

docs: fix UI references, add feature screenshots, improve intuitiveness (#122)

shubhamagarwal-create7198ded23e4e
diff --git a/docs/api/agent-spec.mdx b/docs/api/agent-spec.mdx
index a4bbd1351..276a16027 100644
--- a/docs/api/agent-spec.mdx
+++ b/docs/api/agent-spec.mdx
@@ -65,7 +65,7 @@ Optional array. Each entry attaches a [configured MCP server](/mcp-servers) by n
| Field | Default | Description |
| ---------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `name` | — (required) | Name of a server registered under **Settings → MCP Servers**. |
+| `name` | — (required) | Name of a server registered under **Settings → Connectors**. |
| `enable_tools` | `["@all"]` | Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. |
| `disable_tools` | `[]` | Tools subtracted from the enabled set. |
| `preload_tools` | `[]` | Tools loaded eagerly into context while the rest stay deferred. |
diff --git a/docs/ask-user-questions.mdx b/docs/ask-user-questions.mdx
index ea9a6aebf..0cd688dcc 100644
--- a/docs/ask-user-questions.mdx
+++ b/docs/ask-user-questions.mdx
@@ -36,6 +36,10 @@ sequenceDiagram
The user selects one of the listed options or types a free-form answer. The agent receives the response as a regular tool result and continues from where it paused. The bundled chat UI renders questions and options natively.
+<Frame caption="The chat UI renders the question and its options as a selectable card.">
+ <img src="/images/ask-user-questions.png" alt="The chat UI showing an agent question with multiple-choice options and a Submit button" />
+</Frame>
+
<Note>
Only the root agent can call `ask_user_question`. [Subagents](/context-engineering/subagents) must resolve ambiguity
from the context the root agent provides them.
diff --git a/docs/context-engineering/subagents.mdx b/docs/context-engineering/subagents.mdx
index fba4eaf6f..0c305dbf8 100644
--- a/docs/context-engineering/subagents.mdx
+++ b/docs/context-engineering/subagents.mdx
@@ -16,15 +16,18 @@ Consider a task: _"Summarize the recent pull requests for every member of my tea
<Tabs>
<Tab title="Without subagents">
- 1. The agent looks up members of the team. 2. It works on each member **one by one**, fetching pull requests and
- summarizing each. 3. All intermediate tool calls and results stay in the context window. 4. The agent has to reason
- over a large, cluttered context to produce the final answer. 5. The bloat carries over to future turns in the
- session.
+ 1. The agent looks up members of the team.
+ 2. It works on each member **one by one**, fetching pull requests and summarizing each.
+ 3. All intermediate tool calls and results stay in the context window.
+ 4. The agent has to reason over a large, cluttered context to produce the final answer.
+ 5. The bloat carries over to future turns in the session.
</Tab>
<Tab title="With subagents">
- 1. The agent looks up members of the team. 2. It creates a subagent **per team member** — they run in parallel. 3.
- Each subagent fetches pull requests and produces a summary independently. 4. Subagents return only their summaries
- to the root agent. 5. The root agent combines the summaries — the raw data never enters its context.
+ 1. The agent looks up members of the team.
+ 2. It creates a subagent **per team member** — they run in parallel.
+ 3. Each subagent fetches pull requests and produces a summary independently.
+ 4. Subagents return only their summaries to the root agent.
+ 5. The root agent combines the summaries — the raw data never enters its context.
</Tab>
</Tabs>
@@ -92,6 +95,10 @@ Every execution — root and subagent — runs in its own **thread**, identified
Between the two, the subagent's own `model.message`, `tool.response`, and other events stream with its `thread_id` — so a client can render each subagent as its own collapsible trace while the root agent's events keep flowing on `"main"`. The bundled chat UI does exactly this.
+<Frame caption="The chat UI renders each subagent as its own collapsible trace as they run in parallel.">
+ <img src="/images/subagents.png" alt="The chat UI showing three parallel subagents — mcp-research, a2a-research, openui-research — as separate collapsible traces under Agent steps" />
+</Frame>
+
See [Turn events](/api/turn-events#thread-created) for the full schemas.
## Disabling
diff --git a/docs/generative-ui.mdx b/docs/generative-ui.mdx
index 5c87f00af..5182936cb 100644
--- a/docs/generative-ui.mdx
+++ b/docs/generative-ui.mdx
@@ -68,6 +68,10 @@ The highest traffic is on `gpt-4.1`, while `llama-3.1` has the highest error rat
The renderer turns the snippet above into a full dashboard — summary cards on top, a grouped bar chart in the middle, and a sortable data table at the bottom — all real React components, not markdown.
+<Frame caption="The chat UI renders the OpenUI snippet as a live dashboard — summary cards, a bar chart, and a table.">
+ <img src="/images/generative-ui.png" alt="A rendered Generative UI dashboard with summary cards, a grouped bar chart, and a table" />
+</Frame>
+
## Available components
The OpenUI built-in library covers the patterns most agents need:
diff --git a/docs/human-in-the-loop.mdx b/docs/human-in-the-loop.mdx
index 3acbb8790..9fb3a2247 100644
--- a/docs/human-in-the-loop.mdx
+++ b/docs/human-in-the-loop.mdx
@@ -85,6 +85,10 @@ To deny, send `{ "status": "deny", "reason": "..." }` — the agent receives the
The bundled chat UI handles all of this automatically: it pauses the run, shows the tool name and request payload with **Approve / Deny** buttons, and resumes on your decision.
+<Frame caption="The chat UI pauses on a sensitive tool call and shows the request with Approve / Deny buttons.">
+ <img src="/images/hitl.png" alt="The chat UI pausing on a tool call, showing the request payload and Approve / Deny buttons" />
+</Frame>
+
## When to use approvals
Use approvals for tool calls that change state, are irreversible, or affect production — mutating data, modifying infrastructure, sending external communications, or triggering expensive operations. The `@write` / `@destructive` defaults cover this when the MCP server annotates its tools correctly.
diff --git a/docs/images/add-custom-model-provider.png b/docs/images/add-custom-model-provider.png
new file mode 100644
index 000000000..906dbb420
Binary files /dev/null and b/docs/images/add-custom-model-provider.png differ
diff --git a/docs/images/add-sandbox.png b/docs/images/add-sandbox.png
new file mode 100644
index 000000000..82249b307
Binary files /dev/null and b/docs/images/add-sandbox.png differ
diff --git a/docs/images/add-skill.png b/docs/images/add-skill.png
new file mode 100644
index 000000000..be0f7b1f5
Binary files /dev/null and b/docs/images/add-skill.png differ
diff --git a/docs/images/ask-user-questions.png b/docs/images/ask-user-questions.png
new file mode 100644
index 000000000..8a133cdc5
Binary files /dev/null and b/docs/images/ask-user-questions.png differ
diff --git a/docs/images/generative-ui.png b/docs/images/generative-ui.png
new file mode 100644
index 000000000..aede05b14
Binary files /dev/null and b/docs/images/generative-ui.png differ
diff --git a/docs/images/getting-started-chat.png b/docs/images/getting-started-chat.png
new file mode 100644
index 000000000..45791a3f8
Binary files /dev/null and b/docs/images/getting-started-chat.png differ
diff --git a/docs/images/getting-started-connectors.png b/docs/images/getting-started-connectors.png
new file mode 100644
index 000000000..b73624f77
Binary files /dev/null and b/docs/images/getting-started-connectors.png differ
diff --git a/docs/images/getting-started-sandbox.png b/docs/images/getting-started-sandbox.png
new file mode 100644
index 000000000..a5dfaa9d6
Binary files /dev/null and b/docs/images/getting-started-sandbox.png differ
diff --git a/docs/images/getting-started-skills.png b/docs/images/getting-started-skills.png
new file mode 100644
index 000000000..cb90bbcd3
Binary files /dev/null and b/docs/images/getting-started-skills.png differ
diff --git a/docs/images/hitl.png b/docs/images/hitl.png
new file mode 100644
index 000000000..4b9e87b27
Binary files /dev/null and b/docs/images/hitl.png differ
diff --git a/docs/images/model-configure.png b/docs/images/model-configure.png
new file mode 100644
index 000000000..54c4d4da5
Binary files /dev/null and b/docs/images/model-configure.png differ
diff --git a/docs/images/model-pick.png b/docs/images/model-pick.png
new file mode 100644
index 000000000..eaca60191
Binary files /dev/null and b/docs/images/model-pick.png differ
diff --git a/docs/images/model-settings.png b/docs/images/model-settings.png
new file mode 100644
index 000000000..d43693118
Binary files /dev/null and b/docs/images/model-settings.png differ
diff --git a/docs/images/subagents.png b/docs/images/subagents.png
new file mode 100644
index 000000000..11b4c246c
Binary files /dev/null and b/docs/images/subagents.png differ
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index fe0ee1a03..71514ce66 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -38,6 +38,10 @@ You choose a model, connect MCP servers, add skills, and write instructions. Tru
It scales down and up: run a single process backed by SQLite with `npx @truefoundry/trueforge`, or run multiple replicas backed by Postgres and Redis behind a load balancer.
+<Frame caption="The bundled chat UI — streaming responses, an expandable agent-steps panel, and tool calls.">
+ <img src="/images/getting-started-chat.png" alt="The TrueForge chat UI showing an agent response with an agent-steps panel and tool calls" />
+</Frame>
+
## Capabilities
<CardGroup cols={2}>
@@ -106,6 +110,10 @@ flowchart LR
Interaction with an agent follows a strict hierarchy: **one Agent → many Sessions → many Turns → many Events**.
+<Frame caption="One agent serves many sessions; each session has many turns; each turn emits many events.">
+ <img src="/images/agent-session-hierarchy.png" alt="Hierarchy diagram: one Agent contains many Sessions, each Session many Turns, each Turn many Events" />
+</Frame>
+
| Concept | What it is |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| **Agent** | A saved definition — model, instructions, MCP servers, skills, and runtime config. See [Agent spec](/api/agent-spec). |
diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdx
index c0552592e..0267d97f7 100644
--- a/docs/mcp-servers.mdx
+++ b/docs/mcp-servers.mdx
@@ -6,7 +6,7 @@ description: 'Connect remote MCP servers to give your agent tools — with heade
MCP servers are how your agent reaches real systems: SaaS apps, internal APIs, data platforms, ticketing tools, and infrastructure controls.
-In TrueForge, MCP servers are registered once — in the UI under **Settings → MCP Servers** or via the settings API — and agents reference them by name. Credentials live in the server configuration, never in agent definitions.
+In TrueForge, MCP servers are registered once — in the UI under **Settings → Connectors** or via the settings API — and agents reference them by name. Credentials live in the server configuration, never in agent definitions.
## Registering an MCP server
diff --git a/docs/models.mdx b/docs/models.mdx
index 6f1d68970..d0d144c18 100644
--- a/docs/models.mdx
+++ b/docs/models.mdx
@@ -4,7 +4,7 @@ sidebarTitle: 'Models'
description: 'Configure model providers once, then reference models by name in any agent — switching models is a config change, not a code change.'
---
-TrueForge works with the major model providers and any OpenAI-compatible endpoint. Provider credentials are configured once — in the UI under **Settings → Model Providers** or via the settings API — and agents reference models by name. Agent definitions never contain API keys.
+TrueForge works with the major model providers and any OpenAI-compatible endpoint. Provider credentials are configured once — in the UI under **Settings → Models** or via the settings API — and agents reference models by name. Agent definitions never contain API keys.
## Supported providers
@@ -22,6 +22,10 @@ TrueForge works with the major model providers and any OpenAI-compatible endpoin
The shipped catalog (`GET /api/v1/settings/model-providers/catalog`) contains ready-to-fill templates for each provider. Use the `custom` type to connect vLLM, Ollama, a corporate gateway, or any other OpenAI-compatible API.
+<Frame caption="Adding a custom OpenAI-compatible provider (vLLM, Ollama, a gateway) with base URL, API key, and model IDs.">
+ <img src="/images/add-custom-model-provider.png" alt="The Add Custom Provider dialog with name, base URL, API key, and model fields" />
+</Frame>
+
## Configuring a provider
<Tabs>
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index e1f2e0150..4e7df0dd6 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -70,47 +70,72 @@ description: 'Run TrueForge with one command, configure a model provider, and ha
TrueForge ships with a catalog of model providers. Configure one before your first chat:
<Steps>
- <Step title="Open Settings">In the UI, open **Settings → Models**.</Step>
+ <Step title="Open Settings">
+ In the UI, open **Settings → Models**.
+
+ <Frame>
+ <img src="/images/model-settings.png" alt="The Settings → Models page listing configured and available providers" />
+ </Frame>
+ </Step>
<Step title="Pick a provider">
Choose a provider from the catalog — OpenAI, Anthropic, Google Gemini, or an OpenAI-compatible endpoint — and paste
your API key.
+
+ <Frame>
+ <img src="/images/model-configure.png" alt="Configuring a provider — pasting the API key and clicking Create" />
+ </Frame>
</Step>
<Step title="Select a model">
Back in the chat, pick a model. Models are addressed as `provider/model`, for example `anthropic/claude-sonnet-4-6`.
+
+ <Frame>
+ <img src="/images/model-pick.png" alt="Selecting a model from the chat composer's model picker" />
+ </Frame>
</Step>
</Steps>
Everything you can do in Settings is also available through the API — see `GET /api/v1/settings/model-providers/catalog` and `PUT /api/v1/settings/model-providers` in the interactive API docs at `/api/v1/docs`.
-<div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.75", padding: "40px 0" }}>
- <iframe
- src="https://app.supademo.com/embed/cmsk7202v01l51t0jkq022fjk?embed_v=2&utm_source=embed"
- loading="lazy"
- title="Configure a model provider in TrueForge"
- allow="clipboard-write"
- allowFullScreen
- style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}
- />
-</div>
-
## Start chatting
Send your first message. Out of the box the agent supports multi-turn conversations with streaming. To give it more capabilities:
-- **Connect tools** — add [MCP servers](/mcp-servers) under **Settings → MCP Servers**.
-- **Enable the sandbox** — configure a [sandbox provider](/sandbox) so the agent can run code and use [skills](/skills).
-- **Add skills** — register [git-backed skills](/skills) under **Settings → Skills**.
-
-<div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.46", padding: "40px 0" }}>
- <iframe
- src="https://app.supademo.com/embed/cmsk13xio00k81p0j1wj6amj6?embed_v=2&utm_source=embed"
- loading="lazy"
- title="Chat with an agent in TrueForge"
- allow="clipboard-write"
- allowFullScreen
- style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}
- />
-</div>
+<Steps>
+ <Step title="Connect tools">
+ Add [MCP servers](/mcp-servers) under **Settings → Connectors**.
+
+ <Frame>
+ <img src="/images/getting-started-connectors.png" alt="The Connectors settings page listing connected and available MCP servers" />
+ </Frame>
+ </Step>
+ <Step title="Enable the sandbox">
+ Configure a [sandbox provider](/sandbox) under **Settings → Sandbox providers** so the agent can run code and use [skills](/skills).
+
+ <Frame>
+ <img src="/images/getting-started-sandbox.png" alt="The Sandbox providers settings page with Daytona connected" />
+ </Frame>
+ </Step>
+ <Step title="Add skills">
+ Register [git-backed skills](/skills) under **Settings → Skills**.
+
+ <Frame>
+ <img src="/images/getting-started-skills.png" alt="The Skills settings page with a selected skill" />
+ </Frame>
+ </Step>
+</Steps>
+
+<Frame caption="Composing an agent — pick a model, add connectors and skills, then save it to the library.">
+ <div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.46", padding: "40px 0" }}>
+ <iframe
+ src="https://app.supademo.com/embed/cmsk13xio00k81p0j1wj6amj6?embed_v=2&utm_source=embed"
+ loading="lazy"
+ title="Chat with an agent in TrueForge"
+ allow="clipboard-write"
+ allowFullScreen
+ style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}
+ />
+ </div>
+</Frame>
## Call the API
diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
index 496a417b3..aeeb54479 100644
--- a/docs/sandbox.mdx
+++ b/docs/sandbox.mdx
@@ -30,7 +30,7 @@ This design has several consequences:
## Configuring a sandbox provider
-TrueForge delegates sandbox compute to a provider. Configure it once — in the UI under **Settings → Sandbox** or via `PUT /api/v1/settings/sandbox-providers`. Today the supported provider is [Daytona](https://www.daytona.io):
+TrueForge delegates sandbox compute to a provider. Configure it once — in the UI under **Settings → Sandbox providers** or via `PUT /api/v1/settings/sandbox-providers`. Today the supported provider is [Daytona](https://www.daytona.io):
```json
{
diff --git a/docs/ui-sdk/concepts/agent-modes.mdx b/docs/ui-sdk/concepts/agent-modes.mdx
index 9d02cc3aa..8b583a6d2 100644
--- a/docs/ui-sdk/concepts/agent-modes.mdx
+++ b/docs/ui-sdk/concepts/agent-modes.mdx
@@ -39,16 +39,18 @@ The default is `{ mode: "AgentLibraryWithComposer" }`.
Users assemble an ad-hoc agent — model, skills, MCP servers — without browsing a
library, and can save it back to the library.
- <div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.46", padding: "40px 0" }}>
- <iframe
- src="https://app.supademo.com/embed/cmsk13xio00k81p0j1wj6amj6?embed_v=2&utm_source=embed"
- loading="lazy"
- title="Compose an agent in TrueForge"
- allow="clipboard-write"
- allowFullScreen
- style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}
- />
- </div>
+ <Frame caption="Composing an agent — pick a model, add connectors and skills, then save it to the library.">
+ <div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.46", padding: "40px 0" }}>
+ <iframe
+ src="https://app.supademo.com/embed/cmsk13xio00k81p0j1wj6amj6?embed_v=2&utm_source=embed"
+ loading="lazy"
+ title="Compose an agent in TrueForge"
+ allow="clipboard-write"
+ allowFullScreen
+ style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}
+ />
+ </div>
+ </Frame>
</Accordion>
<Accordion title="AgentLibraryWithComposer">
Both surfaces, and the default. Users can pick an existing agent or author a new one.
diff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdx
index 5c1f97d7c..359cdcc83 100644
--- a/docs/ui-sdk/get-started/quickstart.mdx
+++ b/docs/ui-sdk/get-started/quickstart.mdx
@@ -48,6 +48,10 @@ 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.
+<Frame caption="What `TrueforgeUI` renders — a full agent chat with streaming, history, and tool calls.">
+ <img src="/images/getting-started-chat.png" alt="The TrueforgeUI component rendering an agent chat with an agent-steps panel and a streamed response" />
+</Frame>
+
## TrueForge
Typed for hosts adopting the harness adapter.
diff --git a/docs/ui-sdk/reference/catalog.mdx b/docs/ui-sdk/reference/catalog.mdx
index d71011c70..f522e138a 100644
--- a/docs/ui-sdk/reference/catalog.mdx
+++ b/docs/ui-sdk/reference/catalog.mdx
@@ -68,6 +68,10 @@ never returned.
`supportedReasoningEfforts` lists the effort levels the provider's models accept, which the
custom-provider form offers when configuring a model. `logo` is an optional image for the
provider card.
+
+ <Frame caption="The custom-provider form these types back, in the Models settings panel.">
+ <img src="/images/add-custom-model-provider.png" alt="The Add Custom Provider dialog with name, base URL, API key, and model fields" />
+ </Frame>
</Accordion>
<Accordion title="Connectors (MCP servers)">
@@ -169,6 +173,10 @@ never returned.
There is no `updateSkill` — skills are created and deleted rather than edited. Deletion is
asymmetric between the two kinds: removing a registry skill returns it to the catalog as
selectable again, while removing a GitHub-imported skill is permanent.
+
+ <Frame caption="Importing a skill from a GitHub repository in the Skills settings panel.">
+ <img src="/images/add-skill.png" alt="The Import from GitHub skill dialog with name, description, repository URL, path, and ref fields" />
+ </Frame>
</Accordion>
<Accordion title="Sandbox providers">
@@ -206,6 +214,10 @@ never returned.
`UpdateSandboxProviderRequest` takes `id` plus the config, with an **optional** `apiKey` —
omit it to keep the existing key, send one to rotate. That is the one place a catalog write
is not a straight full replace.
+
+ <Frame caption="Configuring a sandbox provider (Daytona) in the Sandbox providers settings panel.">
+ <img src="/images/add-sandbox.png" alt="The sandbox provider configuration dialog with snapshot name, timeouts, lifecycle intervals, and API key" />
+ </Frame>
</Accordion>
</AccordionGroup>