Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

docs: document the web search provider settings and built-in tools (#1079)

Am I Satoshi643e8fce5a43
diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdx
index f0caa3619..f1f1680f9 100644
--- a/docs/create-agent/overview.mdx
+++ b/docs/create-agent/overview.mdx
@@ -166,7 +166,7 @@ Open **Build Agent** from the sidebar. The **Agent Config** panel on the left is
<img src="/images/save-agent.png" alt="The Save agent dialog with an agent name and a description field" />
</Frame>
-Available in the UI today: **model**, **instructions**, **MCP servers** (attach, tool selection, tool approval, preload), **skills**, **sandbox** (on/off and file downloads), **iteration limit**, **context compaction**, and the **Dynamic sub-agents**, **Generative UI**, and **Ask user questions** toggles.
+Available in the UI today: **model**, **instructions**, **MCP servers** (attach, tool selection, tool approval, preload), **skills**, **sandbox** (on/off and file downloads), **web search**, **iteration limit**, **context compaction**, and the **Dynamic sub-agents**, **Generative UI**, and **Ask user questions** toggles.
<Note>
A few options are still API only: model parameters (temperature, top_p, and so on), response format, and seed messages. See [Create an agent via the API](#create-an-agent-via-the-api).
@@ -385,6 +385,7 @@ 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. |
+| `web_search` | `{ "enabled": false }` | UI + API | Built-in [`web_search` and `web_fetch` tools](/web-search) backed by the configured provider. |
| `generative_ui` | `{ "enabled": true }` | UI + API | [Generative UI](#generative-ui) (OpenUI blocks). |
| `ask_user_questions` | `{ "enabled": true }` | UI + API | The [`ask_user_question`](#ask-clarifying-questions) tool. |
| `dynamic_sub_agents` | `{ "enabled": true }` | UI + API | [Subagents](/key-features/subagents). |
diff --git a/docs/docs.json b/docs/docs.json
index b3a073b78..5354eff9a 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -47,7 +47,7 @@
"pages": [
{
"group": "Initial Setup",
- "pages": ["harness/initial-setup", "models", "mcp-servers", "skills", "sandbox"]
+ "pages": ["harness/initial-setup", "models", "mcp-servers", "web-search", "skills", "sandbox"]
},
"create-agent/overview",
"agent-library",
diff --git a/docs/harness/initial-setup.mdx b/docs/harness/initial-setup.mdx
index 7347dab16..d1c80a381 100644
--- a/docs/harness/initial-setup.mdx
+++ b/docs/harness/initial-setup.mdx
@@ -1,7 +1,7 @@
---
title: 'Initial Setup'
sidebarTitle: 'Overview'
-description: 'Configure models, MCP servers, skills, and a sandbox provider once — then reuse them across every agent.'
+description: 'Configure models, MCP servers, web search, skills, and a sandbox provider once — then reuse them across every agent.'
---
Before you build agents, configure the shared resources TrueForge orchestrates. You do this once in **Settings**; agents then pick from what you have connected.
@@ -10,6 +10,7 @@ Before you build agents, configure the shared resources TrueForge orchestrates.
| --- | --- | --- | --- |
| [Models](/models) | **Settings → Models** | Provider credentials and available model IDs | [`model-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/trueforge/catalog/model-catalog.yaml) |
| [MCP servers](/mcp-servers) | **Settings → Connectors** | Tools and data from external systems | [`mcp-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/trueforge/catalog/mcp-catalog.yaml) |
+| [Web search](/web-search) | **Settings → Web search** | Live web search and page fetching for agents | [`web-search-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/trueforge/catalog/web-search-catalog.yaml) |
| [Skills](/skills) | **Settings → Skills** | Git-backed procedures the agent can load on demand | [`skill-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/trueforge/catalog/skill-catalog.yaml) |
| [Sandbox](/sandbox) | **Settings → Sandbox providers** | Isolated compute for code, files, and skill execution | [`sandbox-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/trueforge/catalog/sandbox-catalog.yaml) |
@@ -31,6 +32,7 @@ If you self-host TrueForge and want a different preset list (add internal MCP se
| --- | --- |
| `MODEL_CATALOG_PATH` | Model provider presets |
| `MCP_CATALOG_PATH` | MCP server presets |
+| `WEB_SEARCH_CATALOG_PATH` | Web search provider presets |
| `SKILL_CATALOG_PATH` | Skill presets |
| `SANDBOX_CATALOG_PATH` | Sandbox provider presets |
@@ -42,4 +44,4 @@ With [login / OIDC](/authentication/overview) enabled, only users with the **adm
## Next step
-Once models (and any connectors, skills, or sandbox you need) are configured, [create an agent](/create-agent/overview).
+Once models (and any connectors, web search, skills, or sandbox you need) are configured, [create an agent](/create-agent/overview).
diff --git a/docs/web-search.mdx b/docs/web-search.mdx
new file mode 100644
index 000000000..c6c7d093b
--- /dev/null
+++ b/docs/web-search.mdx
@@ -0,0 +1,51 @@
+---
+title: 'Setup Web Search'
+sidebarTitle: 'Web Search'
+description: 'Connect a web search provider so agents can search the web and fetch pages with the built-in tools.'
+---
+
+TrueForge ships two built-in tools for live web access: `web_search` finds pages, and `web_fetch` extracts their content as text for the model. Both stay off until a provider is configured under **Settings → Web search** and an agent enables them.
+
+## Supported providers
+
+| Provider type | Notes |
+| ------------- | ----------------------------------------- |
+| `parallel` | [Parallel](https://parallel.ai). Requires an API key. |
+
+The list comes from the shipped [`web-search-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/trueforge/catalog/web-search-catalog.yaml). Self-hosted deployments can [override the catalog](/harness/initial-setup#changing-what-the-ui-offers).
+
+## Configure a provider
+
+1. Open **Settings → Web search** and choose the Parallel preset.
+2. Paste your Parallel API key and save.
+
+One provider is active at a time. API and UI reads redact the key, so when you update the provider later, leave the API key blank to keep the stored value, or enter a new key to rotate it.
+
+## Enable web search on an agent
+
+| Where | How |
+| ----- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| UI | **Build Agent → Runtime Config → Web search**, or the **Web search** row under **Built-in** in the composer's connectors picker |
+| API | `config.web_search.enabled` |
+
+Once a provider is configured, the UI turns the toggle on for new agents. Agents created through the API keep the schema default, `{ "enabled": false }`, until you set the field.
+
+<Note>Until a provider is configured, the composer's **Web search** row stays disabled.</Note>
+
+## What the agent gets
+
+- `web_search` takes up to 5 keyword queries per call plus an optional objective, and returns ranked hits with titles, URLs, and snippets. Search operators such as `site:` and `filetype:` may work when the provider supports them.
+- `web_fetch` extracts up to 5 URLs as markdown or text, without a summarization step.
+
+The harness adds guidance to the system prompt about when to search and when to fetch. Both tools run on the server through the configured provider; agent definitions never contain the API key.
+
+## Search through MCP instead
+
+An MCP server with search tools works as well, and the [Quickstart](/quickstart) connects Exa that way. The built-in tools are independent of MCP: every agent with `config.web_search.enabled` gets them, with no per-tool selection.
+
+## Manage the provider through the API
+
+- `GET /api/v1/settings/web-search-providers` reads the provider, with the key redacted.
+- `PUT /api/v1/settings/web-search-providers` creates, replaces, or rotates the key.
+- `GET /api/v1/catalogs/web-search-providers` lists the presets.
+- `GET /api/v1/capabilities` reports whether web search is available.