The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Changes in docs (#287)
Abhishek Choudharyd337e2013190
diff --git a/README.md b/README.mdindex 6df749769..b6cd5956a 100644--- a/README.md+++ b/README.md@@ -56,29 +56,13 @@ To work on TrueForge from this repository, see [CONTRIBUTING.md](CONTRIBUTING.md## Architecture-```mermaid-flowchart LR- ui[Chat UI<br/>@truefoundry/trueforge-ui]- code[Your code<br/>trueforge-sdk]- subgraph server [TrueForge server]- api[HTTP API]- loop[Agent loop]- api --> loop- end- db[(SQLite / Postgres)]- subgraph byo [Bring your own]- llm[Model providers]- mcp[MCP servers]- sandbox[Sandbox provider]- end-- ui --> api- code --> api- loop --> db- loop --> llm- loop --> mcp- loop --> sandbox-```+<p align="center">+ <picture>+ <source srcset="./docs/assets/architecture-dark.svg" media="(prefers-color-scheme: dark)">+ <source srcset="./docs/assets/architecture-light.svg" media="(prefers-color-scheme: light)">+ <img src="./docs/assets/architecture-light.svg" alt="TrueForge architecture: Chat UI and SDK connect to the TrueForge server HTTP API and agent loop, which talks to SQLite or Postgres and bring-your-own models, MCP servers, and sandbox" width="920">+ </picture>+</p>| Mode | Best for | Storage | Extra infra | How to run || ------ | --------------------------- | -------- | ---------------- | ---------------------------- |diff --git a/docs/api/overview.mdx b/docs/api/overview.mdxindex 6c1b80a54..320771ae4 100644--- a/docs/api/overview.mdx+++ b/docs/api/overview.mdx@@ -36,7 +36,7 @@ flowchart TD### Agent-An **agent** is a definition, not a running process. You define it once (the model, instructions, tools, and config), and any number of conversations can use it. `support-bot` is a support assistant that looks up orders and processes refunds through an MCP server. Its [AgentSpec](/create-agent/agent-spec) looks like this:+An **agent** is a definition, not a running process. You define it once (the model, instructions, tools, and config), and any number of conversations can use it. `support-bot` is a support assistant that looks up orders and processes refunds through an MCP server. Its [AgentSpec](/create-agent/overview#create-an-agent-via-the-api) looks like this:```json support-bot AgentSpec{@@ -56,7 +56,7 @@ An **agent** is a definition, not a running process. You define it once (the mod}```-Save this spec as a named agent and reference it by name in every session, or pass it inline when you create a session. The [agent spec reference](/create-agent/agent-spec) lists every field.+Save this spec as a named agent and reference it by name in every session, or pass it inline when you create a session. The [agent spec reference](/create-agent/overview#create-an-agent-via-the-api) lists every field.### Session@@ -102,7 +102,7 @@ flowchart LR| **Turn 3** | Jane (or a support rep) | Approval: allow `process_refund` | Agent runs the refund and sends a confirmation. |<Note>- A turn can also pause when the agent asks a clarifying question ([`tool.response_required`](/create-agent/overview#ask-user-questions))+ A turn can also pause when the agent asks a clarifying question ([`tool.response_required`](/create-agent/overview#whats-in-an-agent))or needs MCP OAuth ([`mcp.auth_required`](/mcp-servers#in-chat-authentication)). You resume with a new turn, just likeTurn 3 above.</Note>diff --git a/docs/api/turn-events.mdx b/docs/api/turn-events.mdxindex 13f99da68..0b6da2178 100644--- a/docs/api/turn-events.mdx+++ b/docs/api/turn-events.mdx@@ -98,7 +98,7 @@ The result of a tool the harness executed, linked to its call by `tool_call_id`:### `tool.approval_required`-A tool call needs [human approval](/create-agent/overview#tool-approval) before it can run. The turn ends after this event; resume with a `user.tool_approval` input.+A tool call needs [human approval](/create-agent/overview#whats-in-an-agent) before it can run. The turn ends after this event; resume with a `user.tool_approval` input.| Field | Description || ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |@@ -106,7 +106,7 @@ A tool call needs [human approval](/create-agent/overview#tool-approval) before### `tool.response_required`-A client-side tool (e.g. [`ask_user_question`](/create-agent/overview#ask-user-questions)) needs a result from your app. Same shape as `tool.approval_required`; resume with a `user.tool_response` input.+A client-side tool (e.g. [`ask_user_question`](/create-agent/overview#whats-in-an-agent)) needs a result from your app. Same shape as `tool.approval_required`; resume with a `user.tool_response` input.## Subagent threadsdiff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdxindex 1a4ba3438..7d0ccf31e 100644--- a/docs/api/use-agent.mdx+++ b/docs/api/use-agent.mdx@@ -7,7 +7,7 @@ description: 'Run a saved agent with the TypeScript SDK: a complete example, theThe recipe book for running an agent with [`@truefoundry/trueforge-sdk`](https://www.npmjs.com/package/trueforge-sdk). For the mental model (Agent → Session → Turn → Event → Delta), start with [SDK Overview](/api/overview); for every event field, see [Turn events](/api/turn-events).<Note>-Prerequisite: a named agent in the registry, or an inline [agent spec](/create-agent/agent-spec) you pass when creating the session. The examples below run the **`web-research-brief`** agent from the [Quickstart](/quickstart); build it there first, or swap in your own agent name / inline spec.+Prerequisite: a named agent in the registry, or an inline [agent spec](/create-agent/overview#create-an-agent-via-the-api) you pass when creating the session. The examples below run the **`web-research-brief`** agent from the [Quickstart](/quickstart); build it there first, or swap in your own agent name / inline spec.</Note>Every snippet is self-contained and runnable. They all use the `client` from [Install and connect](#install-and-connect).@@ -177,8 +177,8 @@ Turn `input` accepts three item types (a single turn can't mix a `user.message`| `type` | Purpose || --- | --- || `user.message` | A message. `content` is a string, or an array of `text` / `file` parts (files as data URIs). |-| `user.tool_approval` | An [approval decision](/create-agent/overview#tool-approval) for a paused tool call. |-| `user.tool_response` | An [answer](/create-agent/overview#ask-user-questions) for a paused client-side tool call. |+| `user.tool_approval` | An [approval decision](/create-agent/overview#whats-in-an-agent) for a paused tool call. |+| `user.tool_response` | An [answer](/create-agent/overview#whats-in-an-agent) for a paused client-side tool call. |### Non-streaming turn@@ -287,7 +287,7 @@ For approvals and questions, each pending ref carries the `sourceEventId` of the### Tool approvals-A gated tool ([human approval](/create-agent/overview#tool-approval)) emits [`tool.approval_required`](/api/turn-events#tool-approval-required). Collect the pending events while streaming, then resume with one `user.tool_approval` per pending call, either allowing it or denying it with a reason.+A gated tool ([human approval](/create-agent/overview#whats-in-an-agent)) emits [`tool.approval_required`](/api/turn-events#tool-approval-required). Collect the pending events while streaming, then resume with one `user.tool_approval` per pending call, either allowing it or denying it with a reason.```typescriptimport { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/trueforge-sdk';@@ -337,7 +337,7 @@ for await (const { data: event } of resume.withMetadata()) console.log(event.typ### Agent questions-When the agent uses the built-in [`ask_user_question`](/create-agent/overview#ask-user-questions) tool, it emits [`tool.response_required`](/api/turn-events#tool-response-required); the pending call's `arguments` carry the `question` and `options`. Resume with one `user.tool_response` per pending call.+When the agent uses the built-in [`ask_user_question`](/create-agent/overview#whats-in-an-agent) tool, it emits [`tool.response_required`](/api/turn-events#tool-response-required); the pending call's `arguments` carry the `question` and `options`. Resume with one `user.tool_response` per pending call.```typescriptimport { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/trueforge-sdk';diff --git a/docs/assets/architecture-dark.svg b/docs/assets/architecture-dark.svgnew file mode 100644index 000000000..ea7d28d2a--- /dev/null+++ b/docs/assets/architecture-dark.svg@@ -0,0 +1,72 @@+<svg width="920" height="360" viewBox="0 0 920 360" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">+ <title id="title">TrueForge architecture</title>+ <desc id="desc">Chat UI and SDK connect to the TrueForge server HTTP API and agent loop, which talks to SQLite or Postgres and bring-your-own model providers, MCP servers, and sandbox.</desc>++ <defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">+ <path d="M1 1 L9 5 L1 9" fill="none" stroke="#64748B" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>+ </marker>+ </defs>++ <!-- Clients -->+ <g>+ <rect x="24" y="72" width="168" height="72" rx="12" fill="#111827" stroke="#334155"/>+ <text x="108" y="102" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="14" font-weight="600" fill="#F8FAFC">Chat UI</text>+ <text x="108" y="122" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="11" fill="#94A3B8">@truefoundry/trueforge-ui</text>+ </g>+ <g>+ <rect x="24" y="216" width="168" height="72" rx="12" fill="#111827" stroke="#334155"/>+ <text x="108" y="246" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="14" font-weight="600" fill="#F8FAFC">Your code</text>+ <text x="108" y="266" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="11" fill="#94A3B8">trueforge-sdk</text>+ </g>++ <!-- Server group -->+ <rect x="248" y="48" width="280" height="264" rx="16" fill="#0B1220" stroke="#334155"/>+ <text x="388" y="78" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="12" font-weight="600" letter-spacing="0.04em" fill="#A78BFA">TRUEFORGE SERVER</text>++ <g>+ <rect x="276" y="100" width="224" height="64" rx="12" fill="#111827" stroke="#6D58FB"/>+ <text x="388" y="138" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="15" font-weight="600" fill="#F8FAFC">HTTP API</text>+ </g>+ <g>+ <rect x="276" y="212" width="224" height="64" rx="12" fill="#111827" stroke="#6D58FB"/>+ <text x="388" y="250" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="15" font-weight="600" fill="#F8FAFC">Agent loop</text>+ </g>++ <!-- Storage -->+ <g>+ <ellipse cx="620" cy="180" rx="64" ry="36" fill="#111827" stroke="#334155"/>+ <text x="620" y="176" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#F8FAFC">SQLite /</text>+ <text x="620" y="194" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#F8FAFC">Postgres</text>+ </g>++ <!-- BYO group -->+ <rect x="720" y="48" width="176" height="264" rx="16" fill="transparent" stroke="#475569" stroke-dasharray="5 4"/>+ <text x="808" y="78" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="12" font-weight="600" letter-spacing="0.04em" fill="#94A3B8">BRING YOUR OWN</text>++ <g>+ <rect x="740" y="100" width="136" height="48" rx="10" fill="#111827" stroke="#334155"/>+ <text x="808" y="129" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#F8FAFC">Models</text>+ </g>+ <g>+ <rect x="740" y="168" width="136" height="48" rx="10" fill="#111827" stroke="#334155"/>+ <text x="808" y="197" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#F8FAFC">MCP servers</text>+ </g>+ <g>+ <rect x="740" y="236" width="136" height="48" rx="10" fill="#111827" stroke="#334155"/>+ <text x="808" y="265" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#F8FAFC">Sandbox</text>+ </g>++ <!-- Edges: clients → API → loop -->+ <path d="M192 108 H240 V132 H276" stroke="#64748B" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M192 252 H240 V132" stroke="#64748B" stroke-width="1.75"/>+ <path d="M388 164 V212" stroke="#64748B" stroke-width="1.75" marker-end="url(#arrow)"/>++ <!-- Edges: loop → storage + BYO bus -->+ <path d="M500 244 H556 V216" stroke="#64748B" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M500 244 H700" stroke="#64748B" stroke-width="1.75"/>+ <path d="M700 124 V260" stroke="#64748B" stroke-width="1.75"/>+ <path d="M700 124 H740" stroke="#64748B" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M700 192 H740" stroke="#64748B" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M700 260 H740" stroke="#64748B" stroke-width="1.75" marker-end="url(#arrow)"/>+</svg>diff --git a/docs/assets/architecture-light.svg b/docs/assets/architecture-light.svgnew file mode 100644index 000000000..e89c9c03a--- /dev/null+++ b/docs/assets/architecture-light.svg@@ -0,0 +1,75 @@+<svg width="920" height="360" viewBox="0 0 920 360" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">+ <title id="title">TrueForge architecture</title>+ <desc id="desc">Chat UI and SDK connect to the TrueForge server HTTP API and agent loop, which talks to SQLite or Postgres and bring-your-own model providers, MCP servers, and sandbox.</desc>++ <defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">+ <path d="M1 1 L9 5 L1 9" fill="none" stroke="#94A3B8" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>+ </marker>+ <filter id="shadow" x="-8%" y="-8%" width="116%" height="124%">+ <feDropShadow dx="0" dy="1" stdDeviation="2" flood-color="#05090E" flood-opacity="0.06"/>+ </filter>+ </defs>++ <!-- Clients -->+ <g filter="url(#shadow)">+ <rect x="24" y="72" width="168" height="72" rx="12" fill="#FFFFFF" stroke="#E2E8F0"/>+ <text x="108" y="102" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="14" font-weight="600" fill="#05090E">Chat UI</text>+ <text x="108" y="122" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="11" fill="#64748B">@truefoundry/trueforge-ui</text>+ </g>+ <g filter="url(#shadow)">+ <rect x="24" y="216" width="168" height="72" rx="12" fill="#FFFFFF" stroke="#E2E8F0"/>+ <text x="108" y="246" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="14" font-weight="600" fill="#05090E">Your code</text>+ <text x="108" y="266" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="11" fill="#64748B">trueforge-sdk</text>+ </g>++ <!-- Server group -->+ <rect x="248" y="48" width="280" height="264" rx="16" fill="#F8FAFC" stroke="#E2E8F0"/>+ <text x="388" y="78" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="12" font-weight="600" letter-spacing="0.04em" fill="#6D58FB">TRUEFORGE SERVER</text>++ <g filter="url(#shadow)">+ <rect x="276" y="100" width="224" height="64" rx="12" fill="#FFFFFF" stroke="#DDD6FE"/>+ <text x="388" y="138" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="15" font-weight="600" fill="#05090E">HTTP API</text>+ </g>+ <g filter="url(#shadow)">+ <rect x="276" y="212" width="224" height="64" rx="12" fill="#FFFFFF" stroke="#DDD6FE"/>+ <text x="388" y="250" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="15" font-weight="600" fill="#05090E">Agent loop</text>+ </g>++ <!-- Storage -->+ <g filter="url(#shadow)">+ <ellipse cx="620" cy="180" rx="64" ry="36" fill="#FFFFFF" stroke="#E2E8F0"/>+ <text x="620" y="176" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#05090E">SQLite /</text>+ <text x="620" y="194" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#05090E">Postgres</text>+ </g>++ <!-- BYO group -->+ <rect x="720" y="48" width="176" height="264" rx="16" fill="#FFFFFF" stroke="#CBD5E1" stroke-dasharray="5 4"/>+ <text x="808" y="78" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="12" font-weight="600" letter-spacing="0.04em" fill="#64748B">BRING YOUR OWN</text>++ <g filter="url(#shadow)">+ <rect x="740" y="100" width="136" height="48" rx="10" fill="#FFFFFF" stroke="#E2E8F0"/>+ <text x="808" y="129" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#05090E">Models</text>+ </g>+ <g filter="url(#shadow)">+ <rect x="740" y="168" width="136" height="48" rx="10" fill="#FFFFFF" stroke="#E2E8F0"/>+ <text x="808" y="197" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#05090E">MCP servers</text>+ </g>+ <g filter="url(#shadow)">+ <rect x="740" y="236" width="136" height="48" rx="10" fill="#FFFFFF" stroke="#E2E8F0"/>+ <text x="808" y="265" text-anchor="middle" font-family="ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" font-size="13" font-weight="600" fill="#05090E">Sandbox</text>+ </g>++ <!-- Edges: clients → API → loop -->+ <path d="M192 108 H240 V132 H276" stroke="#94A3B8" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M192 252 H240 V132" stroke="#94A3B8" stroke-width="1.75"/>+ <path d="M388 164 V212" stroke="#94A3B8" stroke-width="1.75" marker-end="url(#arrow)"/>++ <!-- Edges: loop → storage + BYO bus -->+ <path d="M500 244 H556 V216" stroke="#94A3B8" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M500 244 H700" stroke="#94A3B8" stroke-width="1.75"/>+ <path d="M700 124 V260" stroke="#94A3B8" stroke-width="1.75"/>+ <path d="M700 124 H740" stroke="#94A3B8" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M700 192 H740" stroke="#94A3B8" stroke-width="1.75" marker-end="url(#arrow)"/>+ <path d="M700 260 H740" stroke="#94A3B8" stroke-width="1.75" marker-end="url(#arrow)"/>+</svg>diff --git a/docs/chat-ui.mdx b/docs/chat-ui.mdxindex fcd71a43b..14ad9b74d 100644--- a/docs/chat-ui.mdx+++ b/docs/chat-ui.mdx@@ -22,7 +22,7 @@ When you run TrueForge ([Quickstart](/quickstart)), open the app URL (for exampl- Agent composer and [Agent Library](/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#generative-ui) rendering out of the box+- [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" />diff --git a/docs/create-agent/agent-spec.mdx b/docs/create-agent/agent-spec.mdxdeleted file mode 100644index 4864ffd17..000000000--- a/docs/create-agent/agent-spec.mdx+++ /dev/null@@ -1,128 +0,0 @@-----title: 'Agent Spec Reference'-sidebarTitle: 'Agent Spec'-description: 'Every field on the AgentSpec — model, instructions, MCP servers, skills, and runtime config.'------An `AgentSpec` is the complete definition of an agent. You assemble most of it in the [composer](/create-agent/overview) — model, connectors, skills, instructions, and the capability toggles — and set the remaining runtime config via the [SDK](/api/overview). Saving an agent in the UI stores a spec; with the SDK you pass the same spec inline or reference a saved agent by name. All fields are `snake_case`.--The **Set via** column on each table shows where a field is configurable — **UI** (the composer / Save Agent dialog), **API** (SDK/HTTP), or both.--```json A complete example-{- "model": {- "name": "anthropic/claude-sonnet-4-6",- "params": { "max_tokens": 4096, "temperature": 0.2 }- },- "instructions": "You help customers with orders. Always confirm before processing refunds.",- "mcp_servers": [- {- "name": "orders-api",- "enable_tools": ["@all"],- "require_approval_for_tools": ["process_refund"],- "preload": false- }- ],- "skills": [{ "name": "customer-support" }],- "config": {- "iteration_limit": 50,- "sandbox": { "enabled": true },- "dynamic_sub_agents": { "enabled": true },- "ask_user_questions": { "enabled": true },- "generative_ui": { "enabled": true },- "context_management": {- "compaction": { "enabled": true },- "large_tool_response": { "enabled": true }- }- }-}-```--## `model`--The only required field.--| Field | Type | Required | Set via | Description |-| -------- | ------ | -------- | -------- | -------------------------------------------------------------------------- |-| `name` | string | Yes | UI + API | Model FQN: `provider/model`, e.g. `openai/gpt-5.2`. See [Models](/models). |-| `params` | object | No | API | Model call parameters, passed through to the provider. |--`model.params` recognizes `max_tokens`, `temperature`, `top_p`, `top_k`, `parallel_tool_calls` (boolean), and `reasoning_effort` (string). Extra keys are allowed and forwarded to the provider as-is.--## `instructions`--**Set via:** UI + API--Optional string. The agent's system prompt — its role, behavior, and constraints. The harness appends its own guidance for enabled capabilities (sandbox, subagents, etc.), so keep this focused on _your_ agent. See [Harness Capabilities](/key-features/overview) for how context is managed at runtime.--## `messages`--**Set via:** API--Optional array of seed messages injected at the start of every session:--```json-{ "messages": [{ "type": "user.message", "content": "Introduce yourself briefly." }] }-```--## `mcp_servers`--Optional array. Each entry attaches a [configured MCP server](/mcp-servers) by name:--| Field | Default | Set via | Description |-| ---------------------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |-| `name` | — (required) | UI + API | Name of a server registered under **Settings → Connectors**. |-| `enable_tools` | `["@all"]` | API | Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. |-| `disable_tools` | `[]` | API | Tools subtracted from the enabled set. |-| `preload_tools` | `[]` | API | Tools loaded eagerly into context while the rest stay deferred. |-| `require_approval_for_tools` | `["@write", "@destructive"]` | API | Tools that pause for [human approval](/create-agent/overview#tool-approval): `@all`, `@write`, `@destructive`, or literal names. |-| `preload` | `false` | UI + API | Load all tool schemas upfront instead of [on demand](/key-features/deferred-tool-loading). |--The `@read-only`, `@write`, and `@destructive` selectors are resolved from the tool annotations published by the MCP server.--## `response_format`--**Set via:** API--Optional. Constrains the agent's final output: `{ "type": "text" }` (default), `{ "type": "json_object" }`, or `{ "type": "json_schema", "json_schema": { ... } }`.--## `skills`--**Set via:** UI + API--Optional array of name-only references to [configured skills](/skills):--```json-{ "skills": [{ "name": "customer-support" }] }-```--Skill names may contain letters, numbers, `.`, `_`, and `-` (max 64 characters). Attaching skills requires `config.sandbox.enabled: true`.--## `config`--Runtime behavior. Every field has a default, so `config` can be omitted entirely.--| Field | Default | Set via | Description |-| -------------------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |-| `iteration_limit` | `100` | API | Max agent-loop iterations per turn (1–1024). A safety stop for runaway loops. |-| `sandbox` | `{ "enabled": false }` | UI + API | [Sandbox](/sandbox) for code execution, files, and skills. |-| `dynamic_sub_agents` | `{ "enabled": true }` | UI + API | [Subagents](/key-features/subagents). |-| `context_management` | all enabled | API | [Compaction](/key-features/overview#context-compaction) and [large tool response offloading](/key-features/large-tool-responses). |-| `generative_ui` | `{ "enabled": true }` | UI + API | [Generative UI](/create-agent/overview#generative-ui) (OpenUI blocks). |-| `ask_user_questions` | `{ "enabled": true }` | UI + API | The [`ask_user_question`](/create-agent/overview#ask-user-questions) tool. |--### `config.sandbox`--| Field | Default | Set via | Description |-| ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `enabled` | `false` | UI + API | Give the agent a sandbox. Required for skills and Code Mode. |-| `file_downloads` | `true` | API | Allow clients to download files the agent produces in the sandbox. |-| `network_policy.auth_inject` | — | API | Up to one rule injecting git basic-auth credentials for exact hosts: `{ "type": "git", "match": { "hosts": ["github.com"] }, "auth_data": { "type": "basic", "username": "...", "password": "..." } }`. |--### `config.context_management`--| Field | Default | Set via | Description |-| ---------------------------------------- | ------- | ------- | ----------------------------------------------------- |-| `compaction.enabled` | `true` | API | Summarize older history when context grows too large. |-| `compaction.compaction_threshold_tokens` | `50000` | API | Context size (tokens) that triggers compaction. |-| `large_tool_response.enabled` | `true` | API | Offload oversized tool responses to a sandbox file. |diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdxindex d1922ea1d..54b27d3f7 100644--- a/docs/create-agent/overview.mdx+++ b/docs/create-agent/overview.mdx@@ -1,93 +1,283 @@---title: 'Create an Agent'-sidebarTitle: 'Overview'-description: 'Pick a model, attach MCP servers and skills, write instructions, and save a reusable agent.'+sidebarTitle: 'Create an Agent'+description: 'Every option on an agent, what the UI covers today, and how to set the rest via the API.'----After [initial setup](/harness/initial-setup), build an agent in the chat UI composer (or via the [SDK](/api/overview)).+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 combination of:+- **[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 API](#create-an-agent-via-the-api)** — the full agent spec, with every field.-1. **Model** — which LLM runs the loop-2. **MCP servers** — which tools it can call-3. **Skills** — which procedures it can load-4. **Instructions** — the system prompt for this agent's role-5. **Configuration** — runtime capabilities in the composer, plus finer controls in the [agent spec](/create-agent/agent-spec)+## What's in an agent-## Build it in the UI+Each option below is part of the agent definition. The **Set in** line on each shows where you can configure it today — the chat **UI**, the **API**, or both.-1. Open TrueForge and use the composer to create or edit an agent.-2. **Select a model** from the providers you configured under Settings → Models. Switching it later is a one-click change — no new API keys in the agent definition.-3. **Attach connectors** (MCP servers) the agent should use. Prefer only the servers it needs.-4. **Attach skills** if the agent should follow specialized procedures (requires [sandbox](/sandbox) enabled on the agent).-5. Write focused **instructions** — role, audience, and behavior. Put long playbooks in skills, not the prompt.-6. **Save** the agent so it appears in the [Agent Library](/agent-library).+<AccordionGroup>+ <Accordion title="Model" icon="microchip">+ The LLM that runs the agent loop. Pick any model from the providers you configured under **Settings → Models**; switching later is a one-click change, with no new API keys in the agent definition.-<Frame caption="Save a reusable agent from the composer.">+ Via the API you can also pass **model parameters** — `temperature`, `max_tokens`, `top_p`, `top_k`, `reasoning_effort`, and more — which are forwarded to the provider as-is.++ **Set in:** UI (which model) · API (model + parameters)+ </Accordion>++ <Accordion title="Instructions" icon="message-lines">+ The system prompt for this agent's role — what it does, who it's for, and how it should behave. The harness appends its own guidance for enabled capabilities (sandbox, subagents, and so on), so keep this focused on _your_ agent and move long playbooks into [skills](/skills) instead of the prompt.++ **Set in:** UI + API+ </Accordion>++ <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):++ - **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.+ - **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)+ </Accordion>++ <Accordion title="Tool approval (API only)" icon="user-shield">+ Some tool calls shouldn't run without a human's sign-off. **Tool approval** pauses the agent before such a call, shows the tool name and arguments, and resumes only after the user chooses **Allow** or **Deny** in the chat UI.++ By default, the harness decides what to gate from the tool's own **MCP annotation**: if the server marks a tool as destructive, the agent pauses for approval before running it. Read-only tools run autonomously.++ <Frame caption="The chat UI pauses on a sensitive tool call with Allow / Deny.">+ <img src="/images/hitl.png" alt="Chat UI pausing on a tool call, showing the request payload with Allow and Deny buttons" />+ </Frame>++ You can override which tools require approval — gate a specific list, or every tool — but that is configured **per MCP server via the API only** ([`require_approval_for_tools`](#mcp_servers)).++ **Set in:** API+ </Accordion>++ <Accordion title="Skills" icon="book">+ [Skills](/skills) are git-backed `SKILL.md` instruction packs that teach the agent specialized procedures — querying a database, following an escalation playbook, drafting release notes. Attach them by name; the agent loads the full skill only when it decides the skill is relevant.++ Attaching skills requires the agent's **sandbox** to be enabled.++ **Set in:** UI + API+ </Accordion>++ <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, and **inject git credentials** so the sandbox can clone private repos without the agent ever seeing the secret.++ **Set in:** UI (on/off) · API (on/off + file downloads + git auth injection)+ </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" />+ </Frame>++ | Use case | What the agent renders |+ | --- | --- |+ | Dashboards | KPI cards, charts, comparison tables |+ | Tables | Sortable logs, resources, result sets |+ | Charts | Bar, line, pie patterns faster than prose |+ | Forms | Guided inputs for the next action |++ Skip it for short explanations, bullet lists, or code where markdown is enough.++ **Set in:** UI + API+ </Accordion>++ <Accordion title="Ask user questions" icon="circle-question">+ Lets the agent pause at a decision it shouldn't guess — which environment to deploy to, which of several matches the user meant, an ambiguous required field — show a multiple-choice prompt, and resume with the chosen answer. On by default.++ <Frame caption="The chat UI renders the question and options as a selectable card.">+ <img src="/images/ask-user-questions.png" alt="Chat UI showing an agent question with multiple-choice options and a Submit button" />+ </Frame>++ Good for disambiguating matches, filling required fields the user didn't specify, or picking a strategy before a destructive step. Skip it when the agent can confidently infer the answer — over-asking turns the agent into a form.++ **Set in:** UI + API+ </Accordion>++ <Accordion title="Dynamic sub-agents" icon="diagram-project">+ Enable 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" />+ </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).++ **Set in:** 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.++ **Set in:** API+ </Accordion>++ <Accordion title="Response format (API only)" icon="brackets-curly">+ Constrains the agent's final output. The default is free-form text; you can require a JSON object, or a JSON value matching a schema you provide.++ **Set in:** API+ </Accordion>++ <Accordion title="Seed messages (API only)" icon="comments">+ Optional starter messages added to the top of **every new conversation** with this agent, before the user says anything. Use them to prime the agent each time — for example, an opening line it should greet with, or standing context every session should begin from. They apply at the start of each session, not just once.++ **Set in:** API+ </Accordion>+</AccordionGroup>++## 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).++<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>-Each connector also has a **preload** toggle — leave it off to keep context lean, or turn it on to load that server's tool definitions upfront. See [Deferred Tool Loading](/key-features/deferred-tool-loading).+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.-## Configure capabilities+<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.+</Note>-The composer's **Capabilities** tab has three toggles, all on by default: **Generative UI**, **Ask clarifying questions**, and **Dynamic sub-agents**. A few other behaviors are set in the agent spec instead; see [Set in the agent spec](#set-in-the-agent-spec) at the end.+## Create an agent via the API-<Frame caption="The composer's Capabilities tab: Generative UI, Dynamic sub-agents, and Ask clarifying questions, all on by default.">- <img src="/images/create-agent-capabilities.png" alt="The composer Capabilities tab with Generative UI, Dynamic sub-agents, and Ask clarifying questions toggled on" />-</Frame>+The [SDK](/api/overview) exposes **every** option through the agent spec. Save the spec as a named agent and reference it by name, or pass it inline when you create a session. All fields are `snake_case`, and every field except `model` has a default.-### Ask user questions+```json A complete example+{+ "model": {+ "name": "anthropic/claude-sonnet-4-6",+ "params": { "max_tokens": 4096, "temperature": 0.2 }+ },+ "instructions": "You help customers with orders. Always confirm before processing refunds.",+ "mcp_servers": [+ {+ "name": "orders-api",+ "enable_tools": ["@all"],+ "require_approval_for_tools": ["process_refund"],+ "preload": false+ }+ ],+ "skills": [{ "name": "customer-support" }],+ "config": {+ "sandbox": { "enabled": true },+ "generative_ui": { "enabled": true },+ "ask_user_questions": { "enabled": true },+ "dynamic_sub_agents": { "enabled": true },+ "context_management": {+ "compaction": { "enabled": true },+ "large_tool_response": { "enabled": true }+ },+ "iteration_limit": 50+ }+}+```-Agents often hit decision points they shouldn't guess — which environment to deploy to, which of several matches the user meant, or what an ambiguous required field should be. **Ask User Questions** pauses the agent, shows a multiple-choice prompt, and resumes with the chosen answer. It's on by default; toggle it in the composer's **Capabilities** tab.+The **Set via** column on each table below marks where a field is configurable today — **UI**, **API**, or both.-<Frame caption="The chat UI renders the question and options as a selectable card.">- <img src="/images/ask-user-questions.png" alt="Chat UI showing an agent question with multiple-choice options and a Submit button" />-</Frame>+### `model`-Good for: choosing a target environment or account, disambiguating multiple matches, filling required fields the user didn't specify, or picking a strategy before a destructive step. Skip it when the agent can confidently infer the answer — over-asking turns the agent into a form.+The only required field.-### Generative UI+| Field | Type | Required | Set via | Description |+| -------- | ------ | -------- | -------- | -------------------------------------------------------------------------- |+| `name` | string | Yes | UI + API | Model FQN: `provider/model`, e.g. `openai/gpt-5.2`. See [Models](/models). |+| `params` | object | No | API | Model call parameters, passed through to the provider. |-For dashboards, comparisons, and structured data, **Generative UI** lets the agent stream interactive components — charts, tables, cards, forms — that the chat UI renders as React. It's on by default; toggle it in the composer's **Capabilities** tab. The agent embeds a small OpenUI snippet in its response; the client renders real components as tokens stream in — no arbitrary code execution, only registered components.+`model.params` recognizes `max_tokens`, `temperature`, `top_p`, `top_k`, `parallel_tool_calls` (boolean), and `reasoning_effort` (string). Extra keys are allowed and forwarded to the provider as-is.-<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" />-</Frame>+### `instructions`-| Use case | What the agent renders |-| --- | --- |-| Dashboards | KPI cards, charts, comparison tables |-| Tables | Sortable logs, resources, result sets |-| Charts | Bar, line, pie patterns faster than prose |-| Forms | Guided inputs for the next action |+**Set via:** UI + API-Skip it for short explanations, bullet lists, or code blocks where markdown is enough.+Optional string. The agent's system prompt — its role, behavior, and constraints.-### Dynamic sub-agents+### `mcp_servers`-For multi-step work across several sources, the agent can delegate focused subtasks to parallel **subagents** and merge only their results — keeping its own context clean. On by default. See [Subagents](/key-features/subagents) for how it works.+Optional array. Each entry attaches a [configured MCP server](/mcp-servers) by name:-<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" />-</Frame>+| Field | Default | Set via | Description |+| ---------------------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |+| `name` | — (required) | UI + API | Name of a server registered under **Settings → Connectors**. |+| `enable_tools` | `["@all"]` | API | Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. |+| `disable_tools` | `[]` | API | Tools subtracted from the enabled set. |+| `preload_tools` | `[]` | API | Tools loaded eagerly into context while the rest stay deferred. |+| `require_approval_for_tools` | `["@write", "@destructive"]` | API | Tools that pause for [human approval](#whats-in-an-agent): `@all`, `@write`, `@destructive`, or literal names. |+| `preload` | `false` | UI + API | Load all tool schemas upfront instead of [on demand](/key-features/deferred-tool-loading). |-## Set in the agent spec+The `@read-only`, `@write`, and `@destructive` selectors are resolved from the tool annotations published by the MCP server.-The composer covers the common setup. A few behaviors aren't in the composer yet: you set them in the [agent spec](/create-agent/agent-spec) through the [SDK](/api/overview), and the chat UI still shows them at runtime.+### `skills`-### Tool approval+**Set via:** UI + API-Some actions, like deploying, deleting data, or sending a refund, shouldn't run without a human's sign-off. **Tool approval** (human in the loop) pauses the agent before a sensitive MCP tool call, shows the tool name and arguments, and resumes only after the user approves or denies. Safe read-only tools stay autonomous.+Optional array of name-only references to [configured skills](/skills):-You set the policy **per MCP server** in the spec ([`mcp_servers`](/create-agent/agent-spec#mcp_servers)), not in the composer. The default gates write and destructive tools (anything the server doesn't mark read-only); you can also list specific tools or gate every tool. At runtime, the chat UI shows the pause with **Allow / Deny**.+```json+{ "skills": [{ "name": "customer-support" }] }+```-<Frame caption="The chat UI pauses on a sensitive tool call with Allow / Deny.">- <img src="/images/hitl.png" alt="Chat UI pausing on a tool call, showing the request payload with Allow and Deny buttons" />-</Frame>+Skill names may contain letters, numbers, `.`, `_`, and `-` (max 64 characters). Attaching skills requires `config.sandbox.enabled: true`.++### `config`++Runtime behavior. Every field has a default, so `config` can be omitted entirely.++| Field | Default | Set via | Description |+| -------------------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |+| `sandbox` | `{ "enabled": false }` | UI + API | [Sandbox](/sandbox) for code execution, files, and skills. |+| `generative_ui` | `{ "enabled": true }` | UI + API | [Generative UI](#whats-in-an-agent) (OpenUI blocks). |+| `ask_user_questions` | `{ "enabled": true }` | UI + API | The [`ask_user_question`](#whats-in-an-agent) tool. |+| `dynamic_sub_agents` | `{ "enabled": true }` | UI + API | [Subagents](/key-features/subagents). |+| `context_management` | all enabled | API | [Compaction](/key-features/overview#context-compaction) and [large tool response offloading](/key-features/large-tool-responses). |+| `iteration_limit` | `100` | API | Max agent-loop iterations per turn (1–1024). A safety stop for runaway loops. |++#### `config.sandbox`++| Field | Default | Set via | Description |+| ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `enabled` | `false` | UI + API | Give the agent a sandbox. Required for skills and Code Mode. |+| `file_downloads` | `true` | API | Allow clients to download files the agent produces in the sandbox. |+| `network_policy.auth_inject` | — | API | Up to one rule injecting git basic-auth credentials for exact hosts: `{ "type": "git", "match": { "hosts": ["github.com"] }, "auth_data": { "type": "basic", "username": "...", "password": "..." } }`. |++#### `config.context_management`++| Field | Default | Set via | Description |+| ---------------------------------------- | ------- | ------- | ----------------------------------------------------- |+| `compaction.enabled` | `true` | API | Summarize older history when context grows too large. |+| `compaction.compaction_threshold_tokens` | `50000` | API | Context size (tokens) that triggers compaction. |+| `large_tool_response.enabled` | `true` | API | Offload oversized tool responses to a sandbox file. |++### `response_format`++**Set via:** API++Optional. Constrains the agent's final output: `{ "type": "text" }` (default), `{ "type": "json_object" }`, or `{ "type": "json_schema", "json_schema": { ... } }`.++### `messages`-Use approvals for state changes, irreversible actions, production impact, external communications, or expensive operations. Skip them for safe reads (list, fetch, search). Approval doesn't replace authorization; it only decides whether a pending call should proceed.+**Set via:** API-### Other spec settings+Optional array of seed messages injected at the start of every session:-A few more controls live in the spec rather than the composer: which tools are enabled or disabled per server, the iteration limit, context management (compaction and large tool-response offloading), a structured `response_format`, and seed `messages`. The [Agent Spec reference](/create-agent/agent-spec) lists every field, and its **Set via** column marks each one UI, API, or both.+```json+{ "messages": [{ "type": "user.message", "content": "Introduce yourself briefly." }] }+```diff --git a/docs/docs.json b/docs/docs.jsonindex 724c1b840..ee62ce348 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -2,9 +2,10 @@"$schema": "https://mintlify.com","theme": "mint","redirects": [- { "source": "/create-agent/tool-approval", "destination": "/create-agent/overview#tool-approval" },- { "source": "/create-agent/ask-user-questions", "destination": "/create-agent/overview#ask-user-questions" },- { "source": "/create-agent/generative-ui", "destination": "/create-agent/overview#generative-ui" }+ { "source": "/create-agent/tool-approval", "destination": "/create-agent/overview#whats-in-an-agent" },+ { "source": "/create-agent/ask-user-questions", "destination": "/create-agent/overview#whats-in-an-agent" },+ { "source": "/create-agent/generative-ui", "destination": "/create-agent/overview#whats-in-an-agent" },+ { "source": "/create-agent/agent-spec", "destination": "/create-agent/overview#create-an-agent-via-the-api" }],"name": "TrueForge","logo": {@@ -47,10 +48,7 @@"group": "Initial Setup","pages": ["harness/initial-setup", "models", "mcp-servers", "skills", "sandbox"]},- {- "group": "Create an Agent",- "pages": ["create-agent/overview", "create-agent/agent-spec"]- },+ "create-agent/overview","agent-library",{"group": "Harness Capabilities",diff --git a/docs/introduction.mdx b/docs/introduction.mdxindex 3e3f096cd..32f6ac159 100644--- a/docs/introduction.mdx+++ b/docs/introduction.mdx@@ -58,7 +58,7 @@ flowchart LRRuns the agent loop. When a user sends a message, the server:- Plans the turn, calls the model, and executes tools — streaming every step back-- Pauses for [human approval](/create-agent/overview#tool-approval) on sensitive actions+- Pauses for [human approval](/create-agent/overview#whats-in-an-agent) on sensitive actions- Keeps context lean on long tasks with [harness capabilities](/key-features/overview) like subagents and compaction- Persists sessions, so conversations survive reconnects and restarts@@ -91,20 +91,13 @@ A ready-made interface for the agents you create:The agent features are identical in both modes — only the backend around the server changes. The [Quickstart](/quickstart) has run instructions for each.-### Local mode — a personal productivity tool--Like Claude Desktop, but on your terms: one process on your machine, started with `npx @truefoundry/trueforge`.--- UI and backend run locally; sessions are stored in a local SQLite file-- No database server, Redis, or other infrastructure to set up--### Hosted mode — a shared deployment for your team--Like Claude's managed agents: one deployment the whole company uses, via Docker Compose or the Helm chart.--- Multiple server replicas run behind a load balancer-- **Postgres** replaces SQLite as durable storage shared by all replicas-- **Redis** peers the replicas — it hands off turn event streams and cancellation signals, so a client can reconnect to any replica and still resume a turn running on another one+| | Local | Hosted |+| --- | --- | --- |+| **Best for** | Personal use — one process on your machine, like Claude Desktop | A shared deployment for your team, like Claude's managed agents |+| **How to run** | `npx @truefoundry/trueforge` | Docker Compose or Helm |+| **Storage** | SQLite | Postgres, shared by all replicas |+| **Extra infra** | None | Postgres + Redis |+| **Replicas** | Single process | Multiple replicas behind a load balancer. Redis peers them so streams and cancellations follow the client across replicas. |## Start buildingdiff --git a/docs/key-features/code-mode.mdx b/docs/key-features/code-mode.mdxindex c735147a8..69ffc6241 100644--- a/docs/key-features/code-mode.mdx+++ b/docs/key-features/code-mode.mdx@@ -55,7 +55,7 @@ sequenceDiagramCode Mode is available whenever the agent's [sandbox](/sandbox) is enabled. The agent decides at runtime whether a task is worth running in code or whether a single direct tool call is enough. Before writing a script, it can call [`get_tool_output_schema`](/key-features/deferred-tool-loading#how-it-works) so it knows the exact shape of a tool's response instead of guessing keys from raw JSON.<Note>- [Approval policies](/create-agent/overview#tool-approval) still apply in Code Mode — a script that calls a tool matching+ [Approval policies](/create-agent/overview#whats-in-an-agent) still apply in Code Mode — a script that calls a tool matching`require_approval_for_tools` pauses for user approval just like a direct tool call.</Note>diff --git a/docs/key-features/large-tool-responses.mdx b/docs/key-features/large-tool-responses.mdxindex f17fcb63f..9100e3f75 100644--- a/docs/key-features/large-tool-responses.mdx+++ b/docs/key-features/large-tool-responses.mdx@@ -30,28 +30,118 @@ In every case the offloaded content remains accessible — the agent can read, `## Example-1. The user asks: _"List the MCP servers I have access to."_-2. The agent calls `list_mcp_servers`. The response is a 180-item JSON array — far over the threshold. The harness writes it to a sandbox file and returns only a preview:-- ```text- Tool response too large — full result saved to /tmp/tool-id-xyz-output- Use the sandbox to read parts of the file or extract data.-- Preview (first and last 100 chars):- {"data":[{"id":"v3sgnimki67gd1do5vkcv9wz","name":"test-realtime-global", ... "total":180}- ```--3. The agent inspects the file's structure, then writes a small script to extract just the names:-- ```python- import json- with open('/tmp/tool-id-xyz-output') as f:- data = json.load(f)- for item in data['data']:- print(item['name'])- ```--4. It answers with the list of names. The 180 full records never entered the model's context.+<Steps>++<Step title="User" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#4f46e5"/><circle cx="14" cy="10" r="3.5" fill="#fff"/><path d="M7 23c0-3.3 3.1-6 7-6s7 2.7 7 6" fill="#fff"/></svg>} noAnchor>+ Can you please list the mcp servers I have access to+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ Let me get more information about the user.++ <AccordionGroup>+ <Accordion title="get_me" icon="wrench">+ **Tool Call**+ ```json lines+ {}+ ```++ **Tool Response**+ ```json lines+ {+ "id": "cm1fa35mt009e0trd11v5831p",+ "subjectSlug": "[email protected]",+ ...+ }+ ```+ </Accordion>+ </AccordionGroup>+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ Let me list the MCP servers you have access to.++ <Warning>+ **Tool response blocked** — `list_mcp_servers` returned too much data. The full result was not sent to the model; it was saved to disk and only a preview was returned.+ </Warning>++ <AccordionGroup>+ <Accordion title="list_mcp_servers" icon="wrench" defaultOpen>+ **Tool Call**+ ```json lines+ {+ createdBySubjectSlug: "[email protected]",+ }+ ```++ **Tool Response (blocked)** — Full result saved to `/tmp/tool-id-xyz-output`+ ```+ Use sandbox to read parts of the file or extract data.+ Use sandbox-schema-infer to understand the schema++ Preview (first and last 100 chars):+ {"data":[{"id":"v3sgnimki67gd1do5vkcv9wz","name":"test-realtime-global","fqn":"truefoundry:google-ve ... 51.458Z","updatedAt":"2026-05-19T13:23:46.269Z","createdBy":"[email protected]"}],"total":180}+ ```+ </Accordion>+ </AccordionGroup>+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ Let me get a preview of the data and print the schema.++ <AccordionGroup>+ <Accordion title="sandbox" icon="cube" defaultOpen>+ **Tool Call**+ ```shell lines+ head -c 200 /tmp/tool-id-xyz-output && echo \"==\" && genson /tmp/tool-id-xyz-output+ ```++ **Tool Response**+ ```text lines+ {"$schema":"http://json-schema.org/schema#","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"createdBySubject":{"type":"object","properties":{"subjectSlug":{"type":"string"}},"required":["subjectSlug"]}},"required":["id","name","createdBySubject"]}},"total":{"type":"integer"}},"required":["data","total"]}+ ```+ </Accordion>+ </AccordionGroup>+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ Now I understand the schema of the MCP servers output file. Let me write code to parse the MCP server names.++ <AccordionGroup>+ <Accordion title="sandbox" icon="cube">+ **Tool Call**+ ```shell lines+ cat << 'EOF' > /tmp/parse_mcp_servers.py+ import json+ with open('/tmp/tool-id-xyz-output', 'r') as f:+ data = json.load(f)+ for item in data['data']:+ print(item['name'])+ EOF+ python3 /tmp/parse_mcp_servers.py+ ```++ **Tool Response**+ ```text lines+ test-realtime-global+ slack-mcp+ google-calendar-mcp+ ...+ ```+ </Accordion>+ </AccordionGroup>+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ Hey John, here are the MCP servers you have access to:++ * test-realtime-global+ * slack-mcp+ * google-calendar-mcp+ * ...+</Step>++</Steps>## Configuration@@ -67,4 +157,4 @@ Turn offloading on or off per agent:}```-The thresholds themselves default to **6,000 tokens** per response, **10,000 tokens** combined, and a **100-character** preview. See [`config.context_management`](/create-agent/agent-spec#config) in the agent spec reference.+The thresholds themselves default to **6,000 tokens** per response, **10,000 tokens** combined, and a **100-character** preview. See [`config.context_management`](/create-agent/overview#config) in the agent spec reference.diff --git a/docs/key-features/overview.mdx b/docs/key-features/overview.mdxindex ff141e01b..5656796c9 100644--- a/docs/key-features/overview.mdx+++ b/docs/key-features/overview.mdx@@ -10,9 +10,9 @@ TrueForge is more than model + tools. These harness features keep long agent run| --- | --- || [Sandbox as a tool](/sandbox) | Isolated code/file execution without putting secrets or the agent loop inside the sandbox || [Context engineering](#what-is-context-engineering) | Progressive skills, deferred tools, subagents, offloading, Code Mode, compaction |-| [Tool approval](/create-agent/overview#tool-approval) | Pause before write/destructive MCP tools |-| [Ask User Questions](/create-agent/overview#ask-user-questions) | Structured clarification mid-run |-| [Generative UI](/create-agent/overview#generative-ui) | Charts, tables, and cards streamed into chat |+| [Tool approval](/create-agent/overview#whats-in-an-agent) | Pause before write/destructive MCP tools |+| [Ask User Questions](/create-agent/overview#whats-in-an-agent) | Structured clarification mid-run |+| [Generative UI](/create-agent/overview#whats-in-an-agent) | Charts, tables, and cards streamed into chat || [In-chat MCP OAuth](/mcp-servers#in-chat-authentication) | Connect button when a connector needs authorization |## Sandbox as a tool@@ -111,6 +111,40 @@ Runtime context is where most of the **context bloat problem** happens. A single</Card></CardGroup>+### Subagents — context isolation++Subagents isolate heavy work. When the root agent spawns a subagent:++- The subagent runs with its **own fresh context** — instructions and tools, but no shared message history.+- It executes autonomously, makes its own tool calls, and produces a final result.+- Only the **final result** returns to the root agent. Intermediate tool calls, large search results, and reasoning steps never enter the root's context.++This is especially valuable for tasks that touch many entities or require many tool calls. For example, summarizing PRs across a 10-person team can fan out to 10 subagents in parallel — the root agent collects 10 short summaries instead of 10 sets of raw tool output. See [Subagents](/key-features/subagents).++### Large result offloading++Sometimes a single tool call returns far more data than the agent needs to reason about — a large JSON list, a long file, a detailed search response. Offloading keeps that data out of context:++```mermaid+flowchart LR+ Tool[Tool executes] --> Check{Result size > threshold?}+ Check -->|No| Full[Full result enters context]+ Check -->|Yes| Save[Save to sandbox file]+ Save --> Preview[Replace with file path + short preview]+ Preview --> Continue[Agent reads parts on demand via sandbox]+```++The agent can then use sandbox tools to inspect the file, infer its schema, extract specific fields, or filter the data — all without the raw payload ever entering the conversation. See [Large Result Offloading](/key-features/large-tool-responses).++### Code Mode — process tool output in code++For tasks that involve **aggregating, filtering, or transforming** tool output (counts, group-bys, joins across multiple tool calls), [Code Mode](/key-features/code-mode) lets the agent run a Python script in the sandbox that calls MCP tools directly. The script processes the data in code and prints only the summary.++This avoids two failure modes at once:++- **Context bloat** — raw tool output never enters context, only the printed result.+- **Hallucinated arithmetic** — counts, sums, and group-bys are computed in code, not inferred from prose.+### Context compactionWhen the conversation grows longer than offloading alone can manage, the harness triggers **compaction**. Compaction is enabled by default and kicks in when the active context crosses a token threshold (default **50,000 tokens**, configurable per agent).@@ -156,11 +190,3 @@ In practice, these strategies stack. A single agent run might:4. Use **Code Mode** to aggregate the offloaded data into a small summary.5. Return the summary to the root agent — keeping the root's runtime context clean.6. **Compact** the root agent's history later if a long conversation crosses the threshold.--## Best practices--1. **Start with input context discipline.** Keep instructions focused on the agent's role; move procedures into skills; leave preload off for large MCP servers.-2. **Let progressive disclosure do the work.** Default to deferred loading for both skills and MCP servers. Override only when a server is truly needed on every run.-3. **Delegate heavy work to subagents.** Multi-step research or tasks with large intermediate outputs belong in subagents.-4. **Use Code Mode for aggregation.** When the model needs to count, group, filter, or join tool output, Code Mode keeps raw data out of context entirely and avoids arithmetic hallucinations.-5. **Watch token usage.** Every `model.message` event carries `usage` with an `input_tokens_breakdown` (harness, skills, instructions, tool definitions, messages), so you can see exactly where context is going.diff --git a/docs/key-features/subagents.mdx b/docs/key-features/subagents.mdxindex 7deca87df..bffe7ddf7 100644--- a/docs/key-features/subagents.mdx+++ b/docs/key-features/subagents.mdx@@ -65,42 +65,164 @@ flowchart LR<Note>- **Shared tools and sandbox** — subagents have access to the same MCP tools and sandbox environment as the rootagent. - **No user interaction** — subagents cannot ask the user questions. Only the root agent talks to the user.- Subagent tool calls that require [approval](/create-agent/overview#tool-approval) still pause for the user, though. - **No nesting** —+ Subagent tool calls that require [approval](/create-agent/overview#whats-in-an-agent) still pause for the user, though. - **No nesting** —subagents cannot create other subagents. Delegation is one level deep. - **Parallel execution** — multiple subagentsrun concurrently. The root agent waits for all of them before continuing.</Note>-## Following subagents in the event stream--Every execution — root and subagent — runs in its own **thread**, identified by a `thread_id` on each event. The root agent is always `"main"`. Subagent lifecycle is marked by two events:--```json thread.created-{- "type": "thread.created",- "thread_id": "th-9f31",- "title": "bob-prs",- "parent": { "thread_id": "main", "tool_call_id": "call-sub-01" },- "agent_info": { "type": "dynamic", "name": "bob-prs", "input": "Search for pull requests merged by..." }-}-```--```json thread.done-{- "type": "thread.done",- "thread_id": "th-9f31",- "title": "bob-prs",- "state": { "status": "done", "output": { "type": "model.message", "content": "Bob merged 2 PRs..." } }-}-```--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.+## Example++In this example, the user asks for a summary of work merged by a team. The root agent looks up team members, then delegates PR research for each member to parallel subagents.++<Steps>++<Step title="User" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#4f46e5"/><circle cx="14" cy="10" r="3.5" fill="#fff"/><path d="M7 23c0-3.3 3.1-6 7-6s7 2.7 7 6" fill="#fff"/></svg>} noAnchor>+ Can you please give me a summary of work merged by "agent" team in agent-runtime in last 7 days?+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ <AccordionGroup>+ <Accordion title="get_team_members" icon="wrench">+ **Tool Call**+ ```json lines+ {+ "org": "truefoundry",+ "team_slug": "agent"+ }+ ```++ **Tool Response**+ ```json lines+ [+ "alice",+ "bob"+ ]+ ```+ </Accordion>+ </AccordionGroup>+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ <Note>+ These subagents run in parallel and return their final assistant messages to the main agent.+ The main agent waits for all the subagents to finish and then combines the results to produce the final answer.+ </Note>++ The agent team has 2 members. The date is 2026-05-22, so I need PRs merged in the last 7 days (since 2026-05-15). Let me now fetch merged PRs for each team member in parallel using sub-agents!++ <AccordionGroup>+ <Accordion title="Subagent: bob-prs" icon="robot">+ <Steps>+ <Step title="System" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#f59e0b"/><path d="M16 4L9 15h5l-2 9 7-11h-5l2-9z" fill="#fff"/></svg>} noAnchor>+ <Note>+ These instructions are generated by the main agent for the subagent to execute.+ </Note>+ Search for pull requests merged by GitHub user "bob" in the repository "agent-runtime" owned by "truefoundry" since 2026-05-15 (last 7 days, today is 2026-05-22).+ Use the search_pull_requests tool with:+ - query: "repo:truefoundry/agent-runtime author:bob is:merged merged:>=2026-05-15"++ For each PR found, provide:+ 1. PR number and title+ 2. Merged date+ 3. A brief 1-2 sentence description of what the PR does (infer from the title or any available description)++ Return a concise structured summary of all PRs found. If none found, say "No PRs merged in the last 7 days."+ </Step>+ <Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ <AccordionGroup>+ <Accordion title="search_pull_requests" icon="wrench" defaultOpen>+ **Tool Call**+ ```json lines+ {+ "query": "repo:truefoundry/agent-runtime author:bob is:merged merged:>=2026-05-15"+ }+ ```++ **Tool Response**+ ```json lines+ {+ "total_count": 2,+ "incomplete_results": false,+ "items": [+ {+ "id": 4475054266,+ "title": "misc: add responseUpdatedAt to agent response store"+ },+ {+ "id": 4454608143,+ "title": "fix: Sandbox: update instruction on agent to invoke mcp_client.py script directly, not via python"+ }+ ]+ }+ ```+ </Accordion>+ </AccordionGroup>+ </Step>+ <Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ - Merged: 2026-05-20+ Description: Adds a new responseUpdatedAt timestamp field to ResponseInStore ...++ - Merged: 2026-05-19+ Description: Fixes sandbox initialization by symlinking the uploaded mcp_client.py as mcp-client+ </Step>+ </Steps>+ </Accordion>+ <Accordion title="Subagent: alice-prs" icon="robot">+ <Steps>+ <Step title="System" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#f59e0b"/><path d="M16 4L9 15h5l-2 9 7-11h-5l2-9z" fill="#fff"/></svg>} noAnchor>+ <Note>+ These instructions are generated by the main agent for the subagent to execute.+ </Note>+ Search for pull requests merged by GitHub user "alice" in the repository "agent-runtime" owned by "truefoundry" since 2026-05-15 (last 7 days, today is 2026-05-22).+ Use the search_pull_requests tool with:+ - query: "repo:truefoundry/agent-runtime author:alice is:merged merged:>=2026-05-15"++ For each PR found, provide:+ 1. PR number and title+ 2. Merged date+ 3. A brief 1-2 sentence description of what the PR does (infer from the title or any available description)++ Return a concise structured summary of all PRs found. If none found, say "No PRs merged in the last 7 days."+ </Step>+ <Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ <AccordionGroup>+ <Accordion title="search_pull_requests" icon="wrench" defaultOpen>+ **Tool Call**+ ```json lines+ {+ "query": "repo:truefoundry/agent-runtime author:alice is:merged merged:>=2026-05-15"+ }+ ```++ **Tool Response**+ ```json lines+ {+ "total_count": 0,+ "incomplete_results": false,+ "items": []+ }+ ```+ </Accordion>+ </AccordionGroup>+ </Step>+ <Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ No PRs merged by alice in the last 7 days.+ </Step>+ </Steps>+ </Accordion>+ </AccordionGroup>+</Step>++<Step title="Assistant" icon={<svg viewBox="0 0 28 28"><rect width="28" height="28" rx="6" fill="#10b981"/><rect x="8" y="11" width="12" height="10" rx="2" fill="#fff"/><circle cx="12" cy="15" r="1.5" fill="#10b981"/><circle cx="16" cy="15" r="1.5" fill="#10b981"/><rect x="13" y="5" width="2" height="6" rx="1" fill="#fff"/><circle cx="14" cy="4.5" r="1.5" fill="#fff"/></svg>} noAnchor>+ Here is a summary of work merged by the agent team in the last 7 days:++ - Alice: No PRs merged in the last 7 days.+ - Bob: 2 PRs merged in the last 7 days. The theme of work is around sandbox initialization and responseUpdatedAt ...+ ...+</Step>++</Steps>## Disabling-Set `config.dynamic_sub_agents.enabled: false` on the agent. See [`config.dynamic_sub_agents`](/create-agent/agent-spec#config) in the agent spec reference.+Set `config.dynamic_sub_agents.enabled: false` on the agent. See [`config.dynamic_sub_agents`](/create-agent/overview#config) in the agent spec reference.diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdxindex e7440be95..4cef9b3ce 100644--- a/docs/mcp-servers.mdx+++ b/docs/mcp-servers.mdx@@ -57,5 +57,5 @@ If a server uses OAuth and the user has not yet authorized it, the turn pauses a## Next steps- Attach MCP servers when you [create an agent](/create-agent/overview).-- Configure which tools need [approval](/create-agent/overview#tool-approval) (API today).+- Configure which tools need [approval](/create-agent/overview#whats-in-an-agent) (API today).- Keep tool schemas lean with [deferred loading](/key-features/deferred-tool-loading) in Harness Capabilities.diff --git a/docs/roadmap.mdx b/docs/roadmap.mdxindex 3d6ea891f..088258f26 100644--- a/docs/roadmap.mdx+++ b/docs/roadmap.mdx@@ -21,7 +21,7 @@ This page tracks the major directions we're investing in. It is directional, not## Agent authoring and management-- **More flexible agent saving** — expose every agent option in the UI layer, including sandbox configuration, security policies, and the rest of the [agent spec](/create-agent/agent-spec).+- **More flexible agent saving** — expose every agent option in the UI layer, including sandbox configuration, security policies, and the rest of the [agent spec](/create-agent/overview#create-an-agent-via-the-api).## Approvals and governancediff --git a/docs/sandbox.mdx b/docs/sandbox.mdxindex 422b8ed1e..fc7f37895 100644--- a/docs/sandbox.mdx+++ b/docs/sandbox.mdx@@ -46,7 +46,7 @@ The provider presets come from the shipped sandbox catalog — see [Initial Setu## Enabling the sandbox on an agent-The sandbox is **off by default** per agent. Turn it on in the agent builder when you need code execution, skills, or Code Mode. You can also set `config.sandbox.enabled` in the [agent spec](/create-agent/agent-spec) when creating agents via the SDK.+The sandbox is **off by default** per agent. Turn it on in the agent builder when you need code execution, skills, or Code Mode. You can also set `config.sandbox.enabled` in the [agent spec](/create-agent/overview#config) when creating agents via the SDK.Optional controls: