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.mdxindex 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.jsonindex 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.mdxindex 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.mdxnew file mode 100644index 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.