Skip to content

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.md
index 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.mdx
index 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 like
Turn 3 above.
</Note>
diff --git a/docs/api/turn-events.mdx b/docs/api/turn-events.mdx
index 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 threads
diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdx
index 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, the
The 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.
```typescript
import { 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.
```typescript
import { TrueForge, TrueForgeApi, isEventDelta, mergeEventDelta } from '@truefoundry/trueforge-sdk';
diff --git a/docs/assets/architecture-dark.svg b/docs/assets/architecture-dark.svg
new file mode 100644
index 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.svg
new file mode 100644
index 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.mdx
index 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.mdx
deleted file mode 100644
index 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.mdx
index 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.json
index 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.mdx
index 3e3f096cd..32f6ac159 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -58,7 +58,7 @@ flowchart LR
Runs 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 building
diff --git a/docs/key-features/code-mode.mdx b/docs/key-features/code-mode.mdx
index c735147a8..69ffc6241 100644
--- a/docs/key-features/code-mode.mdx
+++ b/docs/key-features/code-mode.mdx
@@ -55,7 +55,7 @@ sequenceDiagram
Code 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.mdx
index 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.mdx
index 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 compaction
When 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.mdx
index 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 root
agent. - **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 subagents
run 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.mdx
index 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.mdx
index 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 governance
diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
index 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: