The open-source agent harness - the runtime layer that turns an LLM into a working agent.
docs: refresh docs for the new UI and add Sessions and Schedules pages (#748)
shubhamagarwal-create5c3fd1dd09d1
diff --git a/README.md b/README.mdindex c91a8122f..974a6a453 100644--- a/README.md+++ b/README.md@@ -87,6 +87,8 @@ To work on TrueForge from this repository, see [CONTRIBUTING.md](CONTRIBUTING.md| [Quickstart](https://trueforge.dev/quickstart) | Run local or hosted, build your first agent || [Initial Setup](https://trueforge.dev/harness/initial-setup) | Models, MCP, skills, sandbox - catalogs and overrides || [Create an Agent](https://trueforge.dev/create-agent/overview) | Select resources; tool approval, questions, Generative UI |+| [Sessions](https://trueforge.dev/sessions) | Inspect past runs: turns, tool calls, subagents, tokens, timing |+| [Schedules](https://trueforge.dev/schedules) | Run a saved agent on a recurring cadence, unattended || [Harness Capabilities](https://trueforge.dev/key-features/overview) | Sandbox-as-tool, subagents, deferred tools, Code Mode, compaction || [Setup Login](https://trueforge.dev/authentication/overview) | Optional OIDC for shared deployments || [Benchmarking](https://trueforge.dev/benchmarking) | Cost/accuracy vs Claude Managed Agents and deepagents |diff --git a/docs/agent-library.mdx b/docs/agent-library.mdxindex 88b59aff9..87ad2422d 100644--- a/docs/agent-library.mdx+++ b/docs/agent-library.mdx@@ -4,17 +4,17 @@ sidebarTitle: 'Agents'description: 'Browse, edit, and try saved agents from one place.'----**Agents** is where saved agents live. Open it from the chat UI to search agents, edit their configuration, or start a conversation with **Try**.+**Agents** is where saved agents live. Open it from the sidebar to search saved agents, start a conversation with **Try**, or manage an agent from its row menu. Each row summarizes the agent's model, skills, and connectors.-<Frame caption="Agents — search, edit, and try saved agents.">- <img src="/images/agents-library.png" alt="Agents modal listing saved agents with Edit and Try actions" />+<Frame caption="Agents: search saved agents and start a chat with Try.">+ <img src="/images/agents-library.png" alt="The Agents page listing a saved agent with its model and tool summary, a Created by column, and a Try action" /></Frame>-From the library you can:+From the page you can:- **Search** agents by name-- **Edit** an agent's model, connectors, skills, and instructions- **Try** an agent to open a chat session with it+- Open the row menu to edit an agent (its model, tools, skills, and instructions in Build Agent) or manage it## Visibility and access (hosted mode)diff --git a/docs/api/overview.mdx b/docs/api/overview.mdxindex bf1447930..2103d9f9a 100644--- a/docs/api/overview.mdx+++ b/docs/api/overview.mdx@@ -82,6 +82,8 @@ Jane's follow-ups about the refund stay in `sess-7f2a9c1b`. Bob's question runsPersist the session `id` so Jane can come back tomorrow and pick up where she left off. Only one turn runs in a session at a time.+Every session you run this way is also recorded in the [Sessions](/sessions) view, where you can inspect its turns, tool calls, subagents, and timing.+### TurnA **turn** is one request in the conversation: a single back-and-forth between your app and the agent. Each time Jane sends a message (or your app sends an approval), you create a new turn. Turns in a session **chain automatically** (`previous_turn_id` defaults to `"auto"`), so the agent sees every earlier turn without you resending history.diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdxindex cadb0cd54..c7f5ebb04 100644--- a/docs/api/use-agent.mdx+++ b/docs/api/use-agent.mdx@@ -1029,6 +1029,113 @@ for turn in client.sessions.list_turns(session_id="sess-abc123"):```</CodeGroup>+## Schedules++A **schedule** runs a saved agent on a recurring cadence, unattended. Each run sends the schedule's `task` to the agent and is recorded as a [session](/sessions). Manage them through `client.schedules`; the [Schedules guide](/schedules) covers the same feature in the UI.++### Create a schedule++<CodeGroup>+```typescript TypeScript+const { data: schedule } = await client.schedules.create({+ agentName: 'web-research-brief',+ name: 'morning-brief',+ manifest: {+ task: 'Summarize the most important AI news from the last 24 hours and list the top five items with links.',+ cron: '0 9 * * *', // 09:00 every day, evaluated in `timezone`+ timezone: 'Asia/Kolkata', // IANA time zone+ status: 'active', // or 'paused'+ },+});+```++```python Python+schedule = client.schedules.create(+ agent_name="web-research-brief",+ name="morning-brief",+ manifest={+ "task": "Summarize the most important AI news from the last 24 hours and list the top five items with links.",+ "cron": "0 9 * * *", # 09:00 every day, evaluated in `timezone`+ "timezone": "Asia/Kolkata", # IANA time zone+ "status": "active", # or "paused"+ },+)+```+</CodeGroup>++The `cron` is a standard 5-field expression evaluated in `timezone`. The shortest interval is one hour.++### List, get, update, and delete++Update replaces the whole manifest, so pass every field you want to keep.++<CodeGroup>+```typescript TypeScript+for await (const schedule of await client.schedules.list()) {+ console.log(schedule.name, schedule.manifest.cron);+}++const { data: schedule } = await client.schedules.get('sched-abc123');++await client.schedules.update('sched-abc123', {+ name: 'morning-brief',+ manifest: {+ task: 'Summarize the most important AI news from the last 24 hours and list the top five items with links.',+ cron: '0 8 * * 1-5', // now weekdays at 08:00+ timezone: 'Asia/Kolkata',+ status: 'paused',+ },+});++await client.schedules.delete('sched-abc123');+```++```python Python+for schedule in client.schedules.list():+ print(schedule.name, schedule.manifest.cron)++schedule = client.schedules.get("sched-abc123").data++client.schedules.update(+ "sched-abc123",+ name="morning-brief",+ manifest={+ "task": "Summarize the most important AI news from the last 24 hours and list the top five items with links.",+ "cron": "0 8 * * 1-5", # now weekdays at 08:00+ "timezone": "Asia/Kolkata",+ "status": "paused",+ },+)++client.schedules.delete("sched-abc123")+```+</CodeGroup>++### Runs++<CodeGroup>+```typescript TypeScript+// Trigger a run now, without waiting for the next scheduled time.+await client.schedules.createRun({ scheduleId: 'sched-abc123' });++// Review recent runs.+for await (const run of await client.schedules.listRuns('sched-abc123')) {+ console.log(run.scheduledFor, run.status); // 'scheduled' | 'triggered' | 'failed'+}+```++```python Python+# Trigger a run now, without waiting for the next scheduled time.+client.schedules.create_run(schedule_id="sched-abc123")++# Review recent runs.+for run in client.schedules.list_runs("sched-abc123"):+ print(run.scheduled_for, run.status) # "scheduled" | "triggered" | "failed"+```+</CodeGroup>++Each run executes as a [session](/sessions), so open it there or through the session APIs above to read the transcript.+## Turn events referenceField-level schemas for every event streamed while a turn runs. The recipes above link here for the exact shape of each event they handle.diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdxindex 996a13400..507f5f4a7 100644--- a/docs/authentication/overview.mdx+++ b/docs/authentication/overview.mdx@@ -215,7 +215,7 @@ Each signed-in person maps to exactly one role, decided by the role claim in the<Note>Two current limitations:- **Session history is owner-only** — admins are not global session superusers today.- - **The [Agent Library](/agent-library) is shared** — agents created by anyone are visible to everyone on the instance.+ - **[Agents](/agent-library) are shared** — agents created by anyone are visible to everyone on the instance.</Note>To call the HTTP API or SDK against a server with login enabled, pass an ID token — see [Get a token and connect](/api/quickstart#get-a-token-and-connect).diff --git a/docs/chat-ui.mdx b/docs/chat-ui.mdxindex 12d91b88b..d78ef572e 100644--- a/docs/chat-ui.mdx+++ b/docs/chat-ui.mdx@@ -20,13 +20,13 @@ Key Features:When you run TrueForge ([Quickstart](/quickstart)), open the app URL (for example `http://localhost:8790`). You get:-- Agent composer and [Agent Library](/agent-library)+- The Build Agent page and [Agents](/agent-library)- Streaming chat with tool calls, approvals, and ask-user-questions- Settings for [models](/models), [connectors](/mcp-servers), [skills](/skills), and [sandbox](/sandbox)- [Generative UI](/create-agent/overview#whats-in-an-agent) rendering out of the box-<Frame caption="The bundled chat UI — a streaming response with an expanded agent-steps panel: reasoning, tool calls, and a subagent.">- <img src="/images/chat-ui.png" alt="TrueForge chat UI with an agent response and an expanded agent-steps panel including a subagent" />+<Frame caption="The bundled chat UI: an agent response with an expandable summary of its steps (tool calls and reasoning).">+ <img src="/images/chat-ui.png" alt="TrueForge chat UI with an agent response and a collapsed Agent steps summary of tool calls and thoughts" /></Frame>## What you can customizediff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdxindex c9c09d03a..89723ed87 100644--- a/docs/create-agent/overview.mdx+++ b/docs/create-agent/overview.mdx@@ -4,10 +4,10 @@ sidebarTitle: 'Create an Agent'description: 'Every option on an agent, what the UI covers today, and how to set the rest via the API.'----An agent is a saved, reusable definition: a model, instructions, the tools and skills it can use, and a set of runtime behaviors. You build one in the chat UI or via the [SDK](/api/overview) — either way, TrueForge stores the same **agent spec**, and any number of conversations can run against it.+An agent is a saved, reusable definition: a model, instructions, the tools and skills it can use, and a set of runtime behaviors. You build one on the **Build Agent** page or via the [SDK](/api/overview) — either way, TrueForge stores the same **agent spec**, and any number of conversations can run against it.- **[What's in an agent](#whats-in-an-agent)** — every option, explained.-- **[Create an agent via the UI](#create-an-agent-via-the-ui)** — the options available in the chat UI today.+- **[Create an agent via the UI](#create-an-agent-via-the-ui)** — the options available in the UI today.- **[Create an agent via the API](#create-an-agent-via-the-api)** — the full agent spec, with every field.## What's in an agent@@ -32,13 +32,13 @@ Each option below is part of the agent definition. The **Set in** line on each s<Accordion title="MCP servers (tools)" icon="plug">The [MCP servers](/mcp-servers) whose tools the agent can call, attached by name from **Settings → Connectors**. Credentials live in the connector, never in the agent. Prefer only the servers the agent actually needs.- Per server you can further control (via the API):+ Per server you can further control:- - **Which tools are enabled or disabled** — expose everything, only read-only tools, or a specific list.- - **Preload** — load a server's full tool definitions upfront, or (default) discover them on demand to keep context lean. See [Deferred Tool Loading](/key-features/deferred-tool-loading). The **preload** toggle is also in the UI.+ - **Which tools are enabled or disabled** — expose everything, only read-only tools, or a specific list. Choose these in **Select MCP Tools** when you attach the server, or via the API.+ - **Preload** — load a server's full tool definitions upfront, or (default) discover them on demand to keep context lean. See [Deferred Tool Loading](/key-features/deferred-tool-loading). Toggle it on the connector's chip in Build Agent, or via the API.- **Tool approval** — pause before sensitive tool calls until a human approves. See below.- **Set in:** UI (attach servers, preload toggle) · API (tool filters, approval policy)+ **Set in:** UI (attach servers, tool selection, preload toggle) · API (same, plus approval policy)</Accordion><Accordion title="Tool approval (API only)" icon="user-shield">@@ -66,16 +66,16 @@ Each option below is part of the agent definition. The **Set in** line on each s<Accordion title="Sandbox" icon="box">An isolated environment for running code, files, and shell commands, separate from the server. It's **off by default** and provisioned only when the agent needs it. Required for [skills](/skills) and [Code Mode](/key-features/code-mode).- Optional extras (API): allow clients to **download files** the agent produces.+ Optional extra: allow clients to **download files** the agent produces.- **Set in:** UI (on/off) · API (on/off + file downloads)+ **Set in:** UI (on/off + file downloads) · API (same)</Accordion><Accordion title="Generative UI" icon="chart-column">Lets the agent stream interactive components — charts, tables, cards, forms — that the chat UI renders as React. The agent embeds a small OpenUI snippet in its response; the client renders real, registered components as tokens stream in (no arbitrary code execution). On by default.<Frame caption="A Generative UI response with a chart rendered inline in chat.">- <img src="/images/generative-ui.png" alt="Rendered Generative UI response with an inline bar chart comparing options" />+ <img src="/images/generative-ui.png" alt="Rendered Generative UI response with an inline bar chart of the world's most spoken languages" /></Frame>| Use case | What the agent renders |@@ -106,22 +106,22 @@ Each option below is part of the agent definition. The **Set in** line on each sEnable the harness to spawn **subagents**. This lets the TrueForge harness solve complicated tasks by breaking them into smaller pieces and running them in parallel, then merging only their results — keeping the main agent's context clean. On by default. See [Subagents](/key-features/subagents) for how it works.<Frame caption="The agent fans out to parallel subagents, each shown as its own trace under Agent steps.">- <img src="/images/subagents.png" alt="Chat UI showing three parallel subagents — MCP research, Agent governance research, A2A protocol research — under Agent steps" />+ <img src="/images/subagents.png" alt="Chat UI showing three parallel subagents (notion-research, obsidian-research, evernote-research) under the Agent steps panel" /></Frame>**Set in:** UI + API</Accordion>- <Accordion title="Context management (API only)" icon="compress">- Keeps long runs efficient. **Compaction** summarizes older history once the context crosses a token threshold, and **large tool-response offloading** writes oversized tool outputs to a sandbox file and leaves a short preview in context. Both are on by default. See [Harness Capabilities](/key-features/overview#context-compaction) and [Large tool responses](/key-features/large-tool-responses).+ <Accordion title="Context management" icon="compress">+ Keeps long runs efficient. **Compaction** summarizes older history once the context crosses a token threshold, and **large tool-response offloading** writes oversized tool outputs to a sandbox file and leaves a short preview in context. Both are on by default, with the compaction threshold and both toggles in **Runtime Config**. See [Harness Capabilities](/key-features/overview#context-compaction) and [Large tool responses](/key-features/large-tool-responses).- **Set in:** API+ **Set in:** UI + API</Accordion>- <Accordion title="Iteration limit (API only)" icon="rotate">- A safety stop for how many agent-loop steps a single turn can take (1–1024, default 100). It halts runaway loops; it isn't a normal quality lever.+ <Accordion title="Iteration limit" icon="rotate">+ A safety stop for how many agent-loop steps a single turn can take (1–1024, default 100). It halts runaway loops; it isn't a normal quality lever. Set it in **Runtime Config**.- **Set in:** API+ **Set in:** UI + API</Accordion><Accordion title="Response format (API only)" icon="brackets-curly">@@ -139,22 +139,23 @@ Each option below is part of the agent definition. The **Set in** line on each s## Create an agent via the UI-1. Open TrueForge and use the chat UI to create or edit an agent.-2. **Select a model** from the providers you configured under Settings → Models.-3. **Attach connectors** (MCP servers) the agent should use — and set each server's **preload** toggle if you want its tools loaded upfront.-4. **Attach skills** if the agent should follow specialized procedures (requires [sandbox](/sandbox) enabled).-5. Write focused **instructions** — role, audience, and behavior.-6. Set the **Capabilities** toggles (all on by default): Generative UI, Ask clarifying questions, and Dynamic sub-agents.-7. **Save** the agent so it appears in the [Agent Library](/agent-library).+Open **Build Agent** from the sidebar. The **Agent Config** panel on the left is where you assemble the agent; the chat on the right lets you test it as you go.++1. **Select a model** from the providers you configured under **Settings → Models**, and set its reasoning effort.+2. Write focused **instructions** — role, audience, and behavior.+3. **Add MCP servers** — open **Select MCP Tools**, pick the servers the agent should use, and choose which of their tools to enable. Set a server's **preload** toggle on its chip to load its tools upfront.+4. **Add skills** if the agent should follow specialized procedures (requires [sandbox](/sandbox) enabled).+5. Open **Runtime Config** to review execution and context behavior — Dynamic sub-agents, Generative UI, Ask user questions, the sandbox, iteration limit, and context compaction (all on by default).+6. Click **Save Agent**, give it a name and description, and save. It then appears under [Agents](/agent-library).-<Frame caption="Save a reusable agent from the chat UI.">- <img src="/images/save-agent.png" alt="The Save agent dialog with a name, instructions, and a configuration summary of model, connectors, and skills" />+<Frame caption="Save a reusable agent from the Build Agent page.">+ <img src="/images/save-agent.png" alt="The Save agent dialog with an agent name and a description field" /></Frame>-Options available in the UI today: **model** (selection), **instructions**, **connectors** (attach + preload), **skills**, **sandbox** on/off, and the **Generative UI**, **Ask clarifying questions**, and **Dynamic sub-agents** toggles.+Available in the UI today: **model**, **instructions**, **MCP servers** (attach, tool selection, preload), **skills**, **sandbox** (on/off and file downloads), **iteration limit**, **context compaction**, and the **Dynamic sub-agents**, **Generative UI**, and **Ask user questions** toggles.<Note>- Everything else — model parameters, per-server tool filters, tool approval policy, iteration limit, context management, response format, seed messages, and sandbox extras — is [available via the API](#create-an-agent-via-the-api) today. These are deliberately kept out of the UI for now to keep it simple, and will be added to the UI in the future.+ A few options are still API only: model parameters (temperature, top_p, and so on), per-tool **approval** policy, response format, and seed messages. See [Create an agent via the API](#create-an-agent-via-the-api).</Note>## Create an agent via the APIdiff --git a/docs/docs.json b/docs/docs.jsonindex d640e374a..d7305f7ee 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -51,6 +51,8 @@},"create-agent/overview","agent-library",+ "sessions",+ "schedules",{"group": "Harness Capabilities","pages": [diff --git a/docs/images/add-custom-model-provider.png b/docs/images/add-custom-model-provider.pngindex a1f5fa50f..d912acaa1 100644Binary files a/docs/images/add-custom-model-provider.png and b/docs/images/add-custom-model-provider.png differdiff --git a/docs/images/agents-library.png b/docs/images/agents-library.pngindex be33b11aa..ab43438f6 100644Binary files a/docs/images/agents-library.png and b/docs/images/agents-library.png differdiff --git a/docs/images/ask-user-questions.png b/docs/images/ask-user-questions.pngindex c96a7ee6b..4cb003749 100644Binary files a/docs/images/ask-user-questions.png and b/docs/images/ask-user-questions.png differdiff --git a/docs/images/chat-ui.png b/docs/images/chat-ui.pngindex b0c7ba7ba..10894d43d 100644Binary files a/docs/images/chat-ui.png and b/docs/images/chat-ui.png differdiff --git a/docs/images/generative-ui.png b/docs/images/generative-ui.pngindex 6aaf15626..2d7074d23 100644Binary files a/docs/images/generative-ui.png and b/docs/images/generative-ui.png differdiff --git a/docs/images/hero.png b/docs/images/hero.pngindex b0c7ba7ba..10894d43d 100644Binary files a/docs/images/hero.png and b/docs/images/hero.png differdiff --git a/docs/images/hitl.png b/docs/images/hitl.pngindex 91327a640..3707ad4c8 100644Binary files a/docs/images/hitl.png and b/docs/images/hitl.png differdiff --git a/docs/images/mcp-connectors.png b/docs/images/mcp-connectors.pngindex 8abd5378d..0d983a113 100644Binary files a/docs/images/mcp-connectors.png and b/docs/images/mcp-connectors.png differdiff --git a/docs/images/mcp-in-chat-auth.png b/docs/images/mcp-in-chat-auth.pngindex 3773becdc..69eb3d8ec 100644Binary files a/docs/images/mcp-in-chat-auth.png and b/docs/images/mcp-in-chat-auth.png differdiff --git a/docs/images/preload-tools-off.png b/docs/images/preload-tools-off.pngindex e9d2cf352..47082c559 100644Binary files a/docs/images/preload-tools-off.png and b/docs/images/preload-tools-off.png differdiff --git a/docs/images/preload-tools-on.png b/docs/images/preload-tools-on.pngindex 920a75f6a..6a66b89e9 100644Binary files a/docs/images/preload-tools-on.png and b/docs/images/preload-tools-on.png differdiff --git a/docs/images/quickstart-agents-library.png b/docs/images/quickstart-agents-library.pngindex be33b11aa..ab43438f6 100644Binary files a/docs/images/quickstart-agents-library.png and b/docs/images/quickstart-agents-library.png differdiff --git a/docs/images/quickstart-build-agent.png b/docs/images/quickstart-build-agent.pngnew file mode 100644index 000000000..845102aa1Binary files /dev/null and b/docs/images/quickstart-build-agent.png differdiff --git a/docs/images/quickstart-build-runtime.png b/docs/images/quickstart-build-runtime.pngnew file mode 100644index 000000000..4e8f35274Binary files /dev/null and b/docs/images/quickstart-build-runtime.png differdiff --git a/docs/images/quickstart-build-skills.png b/docs/images/quickstart-build-skills.pngnew file mode 100644index 000000000..cb0518441Binary files /dev/null and b/docs/images/quickstart-build-skills.png differdiff --git a/docs/images/quickstart-build-tools.png b/docs/images/quickstart-build-tools.pngnew file mode 100644index 000000000..012d9ab58Binary files /dev/null and b/docs/images/quickstart-build-tools.png differdiff --git a/docs/images/quickstart-chat-result.png b/docs/images/quickstart-chat-result.pngdeleted file mode 100644index 5eddcecfd..000000000Binary files a/docs/images/quickstart-chat-result.png and /dev/null differdiff --git a/docs/images/quickstart-compose-capabilities.png b/docs/images/quickstart-compose-capabilities.pngdeleted file mode 100644index 0e7f84204..000000000Binary files a/docs/images/quickstart-compose-capabilities.png and /dev/null differdiff --git a/docs/images/quickstart-compose-connectors.png b/docs/images/quickstart-compose-connectors.pngdeleted file mode 100644index 4b0baece8..000000000Binary files a/docs/images/quickstart-compose-connectors.png and /dev/null differdiff --git a/docs/images/quickstart-compose-skills.png b/docs/images/quickstart-compose-skills.pngdeleted file mode 100644index 92244a950..000000000Binary files a/docs/images/quickstart-compose-skills.png and /dev/null differdiff --git a/docs/images/quickstart-connectors.png b/docs/images/quickstart-connectors.pngindex 8abd5378d..0d983a113 100644Binary files a/docs/images/quickstart-connectors.png and b/docs/images/quickstart-connectors.png differdiff --git a/docs/images/quickstart-model-configure.png b/docs/images/quickstart-model-configure.pngindex 4dc21a74f..73661b8fb 100644Binary files a/docs/images/quickstart-model-configure.png and b/docs/images/quickstart-model-configure.png differdiff --git a/docs/images/quickstart-models.png b/docs/images/quickstart-models.pngindex daa4cdc6e..782683b40 100644Binary files a/docs/images/quickstart-models.png and b/docs/images/quickstart-models.png differdiff --git a/docs/images/quickstart-sandbox-configure.png b/docs/images/quickstart-sandbox-configure.pngindex a609a7b6b..ce42b9332 100644Binary files a/docs/images/quickstart-sandbox-configure.png and b/docs/images/quickstart-sandbox-configure.png differdiff --git a/docs/images/quickstart-sandbox-connected.png b/docs/images/quickstart-sandbox-connected.pngindex 0f7b714f6..68971bc30 100644Binary files a/docs/images/quickstart-sandbox-connected.png and b/docs/images/quickstart-sandbox-connected.png differdiff --git a/docs/images/quickstart-skill.png b/docs/images/quickstart-skill.pngindex fe75eb7e4..9e5956e24 100644Binary files a/docs/images/quickstart-skill.png and b/docs/images/quickstart-skill.png differdiff --git a/docs/images/save-agent.png b/docs/images/save-agent.pngindex 896231941..dc1379b5e 100644Binary files a/docs/images/save-agent.png and b/docs/images/save-agent.png differdiff --git a/docs/images/schedules-create.png b/docs/images/schedules-create.pngnew file mode 100644index 000000000..3f331dd9cBinary files /dev/null and b/docs/images/schedules-create.png differdiff --git a/docs/images/schedules-list.png b/docs/images/schedules-list.pngnew file mode 100644index 000000000..d069515c7Binary files /dev/null and b/docs/images/schedules-list.png differdiff --git a/docs/images/sessions-detail.png b/docs/images/sessions-detail.pngnew file mode 100644index 000000000..b5af3eb9fBinary files /dev/null and b/docs/images/sessions-detail.png differdiff --git a/docs/images/sessions-list.png b/docs/images/sessions-list.pngnew file mode 100644index 000000000..abeb11856Binary files /dev/null and b/docs/images/sessions-list.png differdiff --git a/docs/images/subagents.png b/docs/images/subagents.pngindex 8e0522404..f0c01d7dd 100644Binary files a/docs/images/subagents.png and b/docs/images/subagents.png differdiff --git a/docs/introduction.mdx b/docs/introduction.mdxindex aa224781f..cf7614d74 100644--- a/docs/introduction.mdx+++ b/docs/introduction.mdx@@ -21,8 +21,8 @@ TrueForge is an **open-source agent harness** with three parts: a **core server*<GitHub.Repo repo="truefoundry/trueforge" />-<Frame caption="The bundled chat UI — a streaming response with the agent-steps panel expanded to show reasoning, tool calls, and a subagent.">- <img src="/images/chat-ui.png" alt="The TrueForge chat UI showing an agent response with the agent-steps panel expanded — reasoning, Exa tool calls, and a subagent" />+<Frame caption="The bundled chat UI: an agent answering on the right, with an expandable summary of its steps (tool calls and reasoning), next to the Agent Config panel where you shape the agent.">+ <img src="/images/chat-ui.png" alt="The TrueForge chat UI: an agent response about recent developments in agentic AI, with a collapsed Agent steps summary of tool calls and thoughts, beside the Agent Config panel showing model, instructions, runtime config, and MCP servers" /></Frame>### Key Components@@ -105,6 +105,12 @@ The agent features are identical in both modes — only the backend around the s<Card title="Create an Agent" icon="robot" href="/create-agent/overview">Select a model, attach connectors and skills, then save under Agents.</Card>+ <Card title="Sessions" icon="magnifying-glass" href="/sessions">+ Inspect past runs: turns, tool calls, subagents, tokens, and timing.+ </Card>+ <Card title="Schedules" icon="clock" href="/schedules">+ Run a saved agent on a recurring cadence, unattended.+ </Card><Card title="Harness Capabilities" icon="layer-group" href="/key-features/overview">Sandbox-as-tool, subagents, deferred tools, code mode, compaction, and human checkpoints.</Card>diff --git a/docs/key-features/deferred-tool-loading.mdx b/docs/key-features/deferred-tool-loading.mdxindex cba24f311..04e5b0d65 100644--- a/docs/key-features/deferred-tool-loading.mdx+++ b/docs/key-features/deferred-tool-loading.mdx@@ -8,21 +8,21 @@ When an agent is connected to many MCP servers, each with dozens of tools, the fBy default, **`preload` is `false`** — the agent only sees each MCP server's name and description at startup and loads individual tool schemas as needed. This keeps the context window lean while still giving the agent access to the full breadth of tools.-## Set it in the composer+## Set it in Build Agent-Each connector in the **Save Agent** dialog has a book-icon **preload toggle** — off by default. Hover it to see the tradeoff, click to switch it on.+Each connector's chip in Build Agent's **MCP Servers** section has a book-icon **preload toggle** — off by default. Hover it to see the tradeoff, click to switch it on.<Columns cols={2}><Frame caption="Off (default) — tools are discovered on demand."><imgsrc="/images/preload-tools-off.png"- alt="Save Agent dialog with a connector's preload toggle off; the tooltip reads Preload tools OFF — the agent discovers tools on demand, lighter context upfront"+ alt="A connector chip in Build Agent with its preload toggle off; the tooltip reads Preload tools OFF — the agent discovers tools on demand, lighter context upfront"/></Frame><Frame caption="On — tool definitions load into context upfront."><imgsrc="/images/preload-tools-on.png"- alt="Save Agent dialog with a connector's preload toggle on and highlighted; the tooltip reads Preload tools ON — tool definitions load into context upfront"+ alt="A connector chip in Build Agent with its preload toggle on and highlighted; the tooltip reads Preload tools ON — tool definitions load into context upfront"/></Frame></Columns>diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdxindex 9b92c279e..88335a039 100644--- a/docs/mcp-servers.mdx+++ b/docs/mcp-servers.mdx@@ -50,8 +50,8 @@ The catalog entries under **Settings → Connectors** (Linear, Notion, GitHub, aIf a server uses OAuth and the user has not yet authorized it, the turn pauses and the chat UI shows a **Connect** button. The user completes OAuth in a popup and continues the conversation — the agent does not fail.-<Frame caption="In-chat MCP authentication — the turn pauses with a Connect button until the user authorizes the server, then continues.">- <img src="/images/mcp-in-chat-auth.png" alt="The chat UI showing an MCP Authentication Required panel for the Notion server, with Connect and Continue buttons" />+<Frame caption="In-chat MCP authentication: the turn pauses with a Connect button until the user authorizes the server, then continues.">+ <img src="/images/mcp-in-chat-auth.png" alt="The chat UI showing an MCP Authentication Required panel for the linear server, with Connect and Continue buttons" /></Frame>## Next stepsdiff --git a/docs/models.mdx b/docs/models.mdxindex a5a9fa01d..5d5f66527 100644--- a/docs/models.mdx+++ b/docs/models.mdx@@ -41,8 +41,8 @@ The provider list comes from the shipped model catalog — see [Initial Setup](/Use the `custom` provider type for vLLM, Ollama, a corporate gateway, or any other OpenAI-compatible API. Custom providers are not in the catalog — you add them yourself with a base URL, API key, and the model IDs you want exposed.-<Frame caption="The Add custom provider dialog — connect any OpenAI-compatible endpoint with a base URL, an optional API key, and one or more models (each with its context length and max output tokens).">- <img src="/images/add-custom-model-provider.png" alt="The Add custom provider dialog filled for a Groq endpoint — name, base URL, an optional API key, a model with its ID and name, and Advanced context length and max output tokens" />+<Frame caption="The Add custom provider dialog: connect any OpenAI-compatible endpoint with a base URL, an optional API key, and one or more models (each with its context length and max output tokens).">+ <img src="/images/add-custom-model-provider.png" alt="The Add custom provider dialog filled for a Groq endpoint: name, base URL, an optional API key, a model with its ID and name, and Advanced context length and max output tokens" /></Frame><Note>diff --git a/docs/quickstart.mdx b/docs/quickstart.mdxindex b0acba70a..0a9a99e5b 100644--- a/docs/quickstart.mdx+++ b/docs/quickstart.mdx@@ -203,32 +203,41 @@ With TrueForge open in your browser, this walkthrough takes you from an empty woSee the [Sandbox guide](/sandbox) for provider setup details.</Step>- <Step title="Compose an agent and start chatting">- Back in the chat, assemble the agent for this conversation. Pick a model from the selector in the composer, then open the **Tools** menu and set three things:+ <Step title="Build the agent">+ Open **Build Agent** from the sidebar. It's a split view: assemble the agent in the **Agent Config** panel on the left, and test it in a live chat on the right as you go.- - **Connectors** — enable **Exa**.- - **Skills** — enable **web-artifacts-builder**.- - **Capabilities** — leave **Dynamic sub-agents** on (it's the default). This lets the agent research each item in parallel instead of one at a time.+ In the left panel, set:++ - **Model** — pick one from the selector at the top and choose a reasoning effort.+ - **Instructions** — define the agent's role and behavior. For this example:++ ```text wrap+ You are a web research assistant. Given a topic or question, use Exa to search the web and pull content from the most relevant, recent sources. When the request compares several items, research each one in parallel, then synthesize the findings into a clear one-page brief.+ ```++ - **MCP Servers** — open **Select MCP Tools**, choose **Exa**, and enable its tools.+ - **Skills** — open the **Skills** picker and enable **web-artifacts-builder**.+ - **Runtime Config** — open it to review execution and context settings. Keep **Dynamic sub-agents** on so the agent researches each item in parallel, and leave **Generative UI**, **Sandbox**, and **Context compaction** on.<Tabs>- <Tab title="Connectors">+ <Tab title="Tools"><Frame>- + </Frame></Tab><Tab title="Skills"><Frame>- + </Frame></Tab>- <Tab title="Capabilities">+ <Tab title="Runtime Config"><Frame>- + </Frame></Tab></Tabs>- Then send your first message. For example:+ Then test it in the chat on the right. For example:```text wrapResearch the current state of open-source vector databases. Compare Qdrant, Weaviate, and Milvus on performance, features, and licensing, then write a one-page brief with sources.@@ -236,31 +245,27 @@ With TrueForge open in your browser, this walkthrough takes you from an empty woThe agent searches with Exa, delegates each database to a parallel subagent, and uses **web-artifacts-builder** in the sandbox to render an interactive brief.- <Frame caption="The result — an interactive brief the agent built from its web research: a comparison, feature chips, and a strengths chart.">- + <Frame caption="The Build Agent page: Agent Config on the left, and on the right the interactive brief the agent produced, including a Generative UI radar chart of the databases' relative strengths.">+ </Frame></Step><Step title="Save it as an agent">- Happy with the setup? Click **Save Agent**, then in **Save agent** give it a name and instructions and click **Save changes** — this captures the model, connectors, skills, and prompt together as a reusable agent. For this example:+ Happy with the setup? Click **Save Agent** at the top right, give it a name and a short description, and click **Save changes**. This captures the model, instructions, tools, skills, and runtime settings together as a reusable agent. For this example:- - **Name** — `web-research-brief`- - **Instructions** —-- ```text wrap- You are a web research assistant. Given a topic or question, use Exa to search the web and pull content from the most relevant, recent sources. When the request compares several items, research each one in parallel, then synthesize the findings into a clear one-page brief.- ```+ - **Agent name** — `web-research-brief`+ - **Description** — `Web research brief agent`<Frame>- + </Frame></Step><Step title="Find it under Agents">- Open **Agents** from the sidebar. Your saved agent is there — click **Try** to start a fresh chat with the same setup, or **Edit** to tweak it. See [Agents](/agent-library) for shared-visibility notes in hosted mode.+ Open **Agents** from the sidebar. Your saved agent is listed with a summary of its model, skills, and connectors. Click **Try** to start a fresh chat with the same setup, or use the row's menu to manage it. See [Agents](/agent-library) for shared-visibility notes in hosted mode.<Frame>- + </Frame></Step></Steps>@@ -312,6 +317,12 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo<Card title="Create an Agent" icon="robot" href="/create-agent/overview">Select resources and configure approvals, questions, and Generative UI.</Card>+ <Card title="Sessions" icon="magnifying-glass" href="/sessions">+ Inspect the run you just made: turns, tool calls, subagents, tokens, and timing.+ </Card>+ <Card title="Schedules" icon="clock" href="/schedules">+ Run a saved agent on a recurring cadence, unattended.+ </Card><Card title="Harness Capabilities" icon="layer-group" href="/key-features/overview">Subagents, deferred tools, code mode, compaction, and more.</Card>diff --git a/docs/schedules.mdx b/docs/schedules.mdxnew file mode 100644index 000000000..af7ebb578--- /dev/null+++ b/docs/schedules.mdx@@ -0,0 +1,58 @@+---+title: 'Schedules'+sidebarTitle: 'Schedules'+description: 'Run a saved agent on a recurring cadence, unattended, and review each run.'+---++**Schedules** run a saved agent on a recurring cadence, unattended. Each run sends the agent the same task, executes on the server, and is recorded as a [session](/sessions) you can open later. Use them for recurring work such as a daily brief, a periodic report, or a regular check.++## Before you start++A schedule runs an existing **saved agent**, so [create an agent](/create-agent/overview) first. The agent receives the same task on every run, so its instructions and tools should already cover that work.++## Creating a schedule++Open **Schedules** from the sidebar and click **Create Schedule**. Fill in:++- **Agent**: the saved agent to run.+- **Name**: a label for the schedule.+- **Task**: the message sent to the agent on every run. Write it as you would the first message in a chat, for example: "Summarize the most important AI news from the last 24 hours and list the top five items with links."+- **Frequency**: **Hourly**, **Daily**, or **Weekly**, with the hour, minute, and **timezone** to run in. The form previews the result, such as "Daily 9:00 AM" in your timezone.++Click **Save**. The schedule becomes active and runs on that cadence.++<Frame caption="Creating a schedule: pick a saved agent, write the task, and set the cadence and timezone.">+ +</Frame>++<Note>+ The shortest interval is one hour. Times are evaluated in the timezone you choose, and daylight-saving shifts are handled for you.+</Note>++## How runs work++- Every run starts a fresh session, sends the agent the task, and ends when the agent completes it.+- Each run is recorded as a [session](/sessions), marked **Scheduled run**, so you can open it to read the transcript, tool calls, and result.+- The list shows the outcome of the **last five runs** for each schedule.+- Use **Run now** to trigger a run immediately, without waiting for the next scheduled time.++## Managing schedules++The **Scheduled Agents** page lists every schedule with its agent, cadence, status, and recent runs. From here you can:++- **Search** by name, or filter by **status** or **agent**.+- **Pause** a schedule to stop it from running, and resume it later. Paused schedules stay in the list.+- **Edit** a schedule's task, cadence, or timezone.+- **Delete** a schedule you no longer need.++<Frame caption="The Scheduled Agents list: each schedule with its agent, frequency, status, and last five runs.">+ +</Frame>++<Note>+ Schedules run on the server, so the server must be running for them to trigger. In hosted mode with [login](/authentication/overview) enabled, schedules are owner-scoped: each user sees only their own.+</Note>++## Via the SDK++You can create and manage schedules programmatically with `client.schedules`. See [Schedules in the SDK](/api/use-agent#schedules).diff --git a/docs/sessions.mdx b/docs/sessions.mdxnew file mode 100644index 000000000..d025b9a32--- /dev/null+++ b/docs/sessions.mdx@@ -0,0 +1,47 @@+---+title: 'Sessions'+sidebarTitle: 'Sessions'+description: 'Review past agent runs: turns, tool calls, subagents, tokens, and timing.'+---++**Sessions** records every conversation with an agent. Open it from the sidebar to see what an agent did on a run, how long each turn took, which tools and [subagents](/key-features/subagents) it used, and where something went wrong.++## The sessions list++Every session is listed newest first. Each row shows the opening message, when it ran, how many turns it took, and its total duration. Use the **agent** and **time window** filters at the top (the last 30 days by default) to narrow the list to recent activity or to a single agent.++Runs started by a [schedule](/schedules) appear here too, marked **Scheduled run** and showing the agent that ran.++<Frame caption="Agent Sessions: recent runs with their turn count and duration, filterable by agent and time window.">+ +</Frame>++## Session detail++Click a session to open it. The detail view has three parts.++### Summary metrics++A row of totals for the whole session: **Turns**, **Duration**, **Tokens**, **Context**, **Tool calls**, **Sub-agents**, and **Errors**. It summarizes the run at a glance.++### Event timeline++A timeline across the run, colored by event type, such as **System**, **User**, **Model**, **Tool call**, and **Sub-agent**. It shows how the run's time was spent, so a slow model call, a long-running tool, or parallel subagents are easy to spot.++### Turn-by-turn transcript++Below the timeline, each turn is listed with its own token count and duration, the user message, and an **Agent steps** entry you can expand to see the tool calls the agent made and how they resolved.++Together they make it easy to pinpoint where a run failed, whether a turn was cancelled, an [MCP server](/mcp-servers) errored, or a tool returned nothing useful.++<Frame caption="A session opened for inspection: summary metrics, the event timeline, and the turn-by-turn transcript.">+ +</Frame>++## Resuming a run++Each session carries a copyable **session ID**, and the detail header has a button to **resume** it, which reopens the conversation so you can continue it.++<Note>+ In hosted mode with [login](/authentication/overview) enabled, session history is owner-scoped: each user sees only their own sessions. In local mode there is a single shared identity, so all sessions belong to that one user.+</Note>