The open-source agent harness - the runtime layer that turns an LLM into a working agent.
docs: preload toggle in Deferred Tool Loading + agent-spec 'Set via' column + refreshed Save Agent screenshot (#280)
shubhamagarwal-create2cb6f30bdbd0
diff --git a/docs/create-agent/agent-spec.mdx b/docs/create-agent/agent-spec.mdxindex 5c1230de5..4864ffd17 100644--- a/docs/create-agent/agent-spec.mdx+++ b/docs/create-agent/agent-spec.mdx@@ -4,7 +4,9 @@ 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 — everything you assemble in the [composer](/create-agent/overview) (model, connectors, skills, instructions) plus the runtime config that today is set 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`.+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{@@ -40,19 +42,23 @@ An `AgentSpec` is the complete definition of an agent — everything you assemblThe only required field.-| Field | Type | Required | Description |-| -------- | ------ | -------- | -------------------------------------------------------------------------- |-| `name` | string | Yes | Model FQN: `provider/model`, e.g. `openai/gpt-5.2`. See [Models](/models). |-| `params` | object | No | Model call parameters, passed through to the provider. |+| 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@@ -63,23 +69,27 @@ Optional array of seed messages injected at the start of every session:Optional array. Each entry attaches a [configured MCP server](/mcp-servers) by name:-| Field | Default | Description |-| ---------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |-| `name` | — (required) | Name of a server registered under **Settings → Connectors**. |-| `enable_tools` | `["@all"]` | Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. |-| `disable_tools` | `[]` | Tools subtracted from the enabled set. |-| `preload_tools` | `[]` | Tools loaded eagerly into context while the rest stay deferred. |-| `require_approval_for_tools` | `["@write", "@destructive"]` | Tools that pause for [human approval](/create-agent/overview#tool-approval): `@all`, `@write`, `@destructive`, or literal names. |-| `preload` | `false` | Load all tool schemas upfront instead of [on demand](/key-features/deferred-tool-loading). |+| 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@@ -92,27 +102,27 @@ Skill names may contain letters, numbers, `.`, `_`, and `-` (max 64 characters).Runtime behavior. Every field has a default, so `config` can be omitted entirely.-| Field | Default | Description |-| -------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |-| `iteration_limit` | `100` | Max agent-loop iterations per turn (1–1024). A safety stop for runaway loops. |-| `sandbox` | `{ "enabled": false }` | [Sandbox](/sandbox) for code execution, files, and skills. |-| `dynamic_sub_agents` | `{ "enabled": true }` | [Subagents](/key-features/subagents). |-| `context_management` | all enabled | [Compaction](/key-features/overview#context-compaction) and [large tool response offloading](/key-features/large-tool-responses). |-| `generative_ui` | `{ "enabled": true }` | [Generative UI](/create-agent/overview#generative-ui) (OpenUI blocks). |-| `ask_user_questions` | `{ "enabled": true }` | The [`ask_user_question`](/create-agent/overview#ask-user-questions) tool. |+| 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 | Description |-| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `enabled` | `false` | Give the agent a sandbox. Required for skills and Code Mode. |-| `file_downloads` | `true` | Allow clients to download files the agent produces in the sandbox. |-| `network_policy.auth_inject` | — | Up to one rule injecting git basic-auth credentials for exact hosts: `{ "type": "git", "match": { "hosts": ["github.com"] }, "auth_data": { "type": "basic", "username": "...", "password": "..." } }`. |+| 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 | Description |-| ---------------------------------------- | ------- | ----------------------------------------------------- |-| `compaction.enabled` | `true` | Summarize older history when context grows too large. |-| `compaction.compaction_threshold_tokens` | `50000` | Context size (tokens) that triggers compaction. |-| `large_tool_response.enabled` | `true` | Offload oversized tool responses to a sandbox file. |+| 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 ac7a90544..b53386abc 100644--- a/docs/create-agent/overview.mdx+++ b/docs/create-agent/overview.mdx@@ -24,9 +24,11 @@ An agent is a saved combination of:6. **Save** the agent so it appears in the [Agent Library](/agent-library).<Frame caption="Save a reusable agent from the composer.">- <img src="/images/create-agent-save.png" alt="The Save agent dialog with a name, instructions, and a configuration summary of model, connectors, and skills" />+ <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).+## Configure capabilitiesBeyond model, tools, and skills, you can tune how the agent behaves at runtime. **Generative UI**, **Ask clarifying questions**, and **Dynamic sub-agents** are toggles in the composer's **Capabilities** tab — all on by default. **Tool approval** is a per-tool policy (below).diff --git a/docs/images/create-agent-save.png b/docs/images/create-agent-save.pngdeleted file mode 100644index cb0d6c5cd..000000000Binary files a/docs/images/create-agent-save.png and /dev/null differdiff --git a/docs/images/preload-tools-off.png b/docs/images/preload-tools-off.pngnew file mode 100644index 000000000..e9d2cf352Binary files /dev/null and b/docs/images/preload-tools-off.png differdiff --git a/docs/images/preload-tools-on.png b/docs/images/preload-tools-on.pngnew file mode 100644index 000000000..920a75f6aBinary files /dev/null and b/docs/images/preload-tools-on.png differdiff --git a/docs/images/quickstart-save-agent.png b/docs/images/quickstart-save-agent.pngdeleted file mode 100644index cb0d6c5cd..000000000Binary files a/docs/images/quickstart-save-agent.png and /dev/null differdiff --git a/docs/images/save-agent.png b/docs/images/save-agent.pngnew file mode 100644index 000000000..896231941Binary files /dev/null and b/docs/images/save-agent.png differdiff --git a/docs/key-features/deferred-tool-loading.mdx b/docs/key-features/deferred-tool-loading.mdxindex e58141ecb..cba24f311 100644--- a/docs/key-features/deferred-tool-loading.mdx+++ b/docs/key-features/deferred-tool-loading.mdx@@ -8,6 +8,25 @@ 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++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.++<Columns cols={2}>+ <Frame caption="Off (default) — tools are discovered on demand.">+ <img+ src="/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"+ />+ </Frame>+ <Frame caption="On — tool definitions load into context upfront.">+ <img+ src="/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"+ />+ </Frame>+</Columns>+## The problem- Each tool definition — name, description, input schema, output schema — consumes tokens from the available context window.diff --git a/docs/quickstart.mdx b/docs/quickstart.mdxindex 6ae39be2f..590f81d82 100644--- a/docs/quickstart.mdx+++ b/docs/quickstart.mdx@@ -167,7 +167,7 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo```<Frame>- + </Frame></Step>