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.mdxindex 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.mdxindex ea9a6aebf..0cd688dcc 100644--- a/docs/ask-user-questions.mdx+++ b/docs/ask-user-questions.mdx@@ -36,6 +36,10 @@ sequenceDiagramThe 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 ambiguityfrom the context the root agent provides them.diff --git a/docs/context-engineering/subagents.mdx b/docs/context-engineering/subagents.mdxindex 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**, identifiedBetween 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.## Disablingdiff --git a/docs/generative-ui.mdx b/docs/generative-ui.mdxindex 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 ratThe 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 componentsThe 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.mdxindex 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 theThe 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 approvalsUse 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.pngnew file mode 100644index 000000000..906dbb420Binary files /dev/null and b/docs/images/add-custom-model-provider.png differdiff --git a/docs/images/add-sandbox.png b/docs/images/add-sandbox.pngnew file mode 100644index 000000000..82249b307Binary files /dev/null and b/docs/images/add-sandbox.png differdiff --git a/docs/images/add-skill.png b/docs/images/add-skill.pngnew file mode 100644index 000000000..be0f7b1f5Binary files /dev/null and b/docs/images/add-skill.png differdiff --git a/docs/images/ask-user-questions.png b/docs/images/ask-user-questions.pngnew file mode 100644index 000000000..8a133cdc5Binary files /dev/null and b/docs/images/ask-user-questions.png differdiff --git a/docs/images/generative-ui.png b/docs/images/generative-ui.pngnew file mode 100644index 000000000..aede05b14Binary files /dev/null and b/docs/images/generative-ui.png differdiff --git a/docs/images/getting-started-chat.png b/docs/images/getting-started-chat.pngnew file mode 100644index 000000000..45791a3f8Binary files /dev/null and b/docs/images/getting-started-chat.png differdiff --git a/docs/images/getting-started-connectors.png b/docs/images/getting-started-connectors.pngnew file mode 100644index 000000000..b73624f77Binary files /dev/null and b/docs/images/getting-started-connectors.png differdiff --git a/docs/images/getting-started-sandbox.png b/docs/images/getting-started-sandbox.pngnew file mode 100644index 000000000..a5dfaa9d6Binary files /dev/null and b/docs/images/getting-started-sandbox.png differdiff --git a/docs/images/getting-started-skills.png b/docs/images/getting-started-skills.pngnew file mode 100644index 000000000..cb90bbcd3Binary files /dev/null and b/docs/images/getting-started-skills.png differdiff --git a/docs/images/hitl.png b/docs/images/hitl.pngnew file mode 100644index 000000000..4b9e87b27Binary files /dev/null and b/docs/images/hitl.png differdiff --git a/docs/images/model-configure.png b/docs/images/model-configure.pngnew file mode 100644index 000000000..54c4d4da5Binary files /dev/null and b/docs/images/model-configure.png differdiff --git a/docs/images/model-pick.png b/docs/images/model-pick.pngnew file mode 100644index 000000000..eaca60191Binary files /dev/null and b/docs/images/model-pick.png differdiff --git a/docs/images/model-settings.png b/docs/images/model-settings.pngnew file mode 100644index 000000000..d43693118Binary files /dev/null and b/docs/images/model-settings.png differdiff --git a/docs/images/subagents.png b/docs/images/subagents.pngnew file mode 100644index 000000000..11b4c246cBinary files /dev/null and b/docs/images/subagents.png differdiff --git a/docs/introduction.mdx b/docs/introduction.mdxindex 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. TruIt 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 LRInteraction 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.mdxindex 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 headeMCP 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 serverdiff --git a/docs/models.mdx b/docs/models.mdxindex 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 endpoinThe 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.mdxindex 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 haTrueForge 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 pasteyour 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 chattingSend 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 APIdiff --git a/docs/sandbox.mdx b/docs/sandbox.mdxindex 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.mdxindex 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 alibrary, 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.mdxindex 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>+## TrueForgeTyped for hosts adopting the harness adapter.diff --git a/docs/ui-sdk/reference/catalog.mdx b/docs/ui-sdk/reference/catalog.mdxindex 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 thecustom-provider form offers when configuring a model. `logo` is an optional image for theprovider 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 isasymmetric between the two kinds: removing a registry skill returns it to the catalog asselectable 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 writeis 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>