|
| 1 | +--- |
| 2 | +title: Web Tools |
| 3 | +description: Configure server-side web search and URL fetching tools |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from "fumadocs-ui/components/callout"; |
| 7 | + |
| 8 | +The `[features.web_search]` and `[features.web_fetch]` sections configure server-side web tools used by the chat UI. Web search requires an external provider API key; web fetch works out of the box. |
| 9 | + |
| 10 | +## Web Search |
| 11 | + |
| 12 | +### Configuration Reference |
| 13 | + |
| 14 | +```toml |
| 15 | +[features.web_search] |
| 16 | +provider = "tavily" |
| 17 | +api_key = "${TAVILY_API_KEY}" |
| 18 | +max_results = 10 |
| 19 | +timeout_secs = 30 |
| 20 | +cost_microcents_per_request = 10000 |
| 21 | +``` |
| 22 | + |
| 23 | +| Key | Type | Default | Description | |
| 24 | +| ----------------------------- | ------- | ------- | -------------------------------------------------------- | |
| 25 | +| `provider` | string | — | Search provider: `"tavily"` or `"exa"` (required) | |
| 26 | +| `api_key` | string | — | Provider API key, supports `${ENV_VAR}` (required) | |
| 27 | +| `max_results` | integer | `10` | Maximum results per search (also caps per-request limit) | |
| 28 | +| `timeout_secs` | integer | `30` | Request timeout in seconds | |
| 29 | +| `cost_microcents_per_request` | integer | `10000` | Cost per request in microcents ($0.01 default) | |
| 30 | + |
| 31 | +<Callout type="info"> |
| 32 | + Omit the `[features.web_search]` section entirely to disable web search. There is no separate |
| 33 | + `enabled` flag — the presence of the section enables the feature. |
| 34 | +</Callout> |
| 35 | + |
| 36 | +### Provider Setup |
| 37 | + |
| 38 | +#### Tavily |
| 39 | + |
| 40 | +1. Sign up at [tavily.com](https://tavily.com) and obtain an API key |
| 41 | +2. Set the environment variable or inline the key: |
| 42 | + |
| 43 | +```toml |
| 44 | +[features.web_search] |
| 45 | +provider = "tavily" |
| 46 | +api_key = "${TAVILY_API_KEY}" |
| 47 | +``` |
| 48 | + |
| 49 | +#### Exa |
| 50 | + |
| 51 | +1. Sign up at [exa.ai](https://exa.ai) and obtain an API key |
| 52 | +2. Configure with the `exa` provider: |
| 53 | + |
| 54 | +```toml |
| 55 | +[features.web_search] |
| 56 | +provider = "exa" |
| 57 | +api_key = "${EXA_API_KEY}" |
| 58 | +``` |
| 59 | + |
| 60 | +Exa returns full-text content for each result rather than snippets. |
| 61 | + |
| 62 | +### Cost Tracking |
| 63 | + |
| 64 | +Each search request is logged with the configured `cost_microcents_per_request`. The default of `10000` represents $0.01 per search. Adjust to match your provider's actual pricing. |
| 65 | + |
| 66 | +## Web Fetch |
| 67 | + |
| 68 | +### Configuration Reference |
| 69 | + |
| 70 | +```toml |
| 71 | +[features.web_fetch] |
| 72 | +enabled = true |
| 73 | +max_response_bytes = 1048576 |
| 74 | +timeout_secs = 30 |
| 75 | +allowed_content_types = ["text/html", "text/plain", "application/json", "application/xml", "text/xml", "text/csv", "text/markdown"] |
| 76 | +cost_microcents_per_request = 0 |
| 77 | +``` |
| 78 | + |
| 79 | +| Key | Type | Default | Description | |
| 80 | +| ----------------------------- | -------- | ---------------- | ------------------------------------------------ | |
| 81 | +| `enabled` | boolean | `true` | Enable/disable the web fetch tool | |
| 82 | +| `max_response_bytes` | integer | `1048576` (1 MB) | Maximum response body size in bytes | |
| 83 | +| `timeout_secs` | integer | `30` | Request timeout in seconds | |
| 84 | +| `allowed_content_types` | string[] | See above | Content types to accept (prefix match) | |
| 85 | +| `cost_microcents_per_request` | integer | `0` | Cost per request in microcents (free by default) | |
| 86 | + |
| 87 | +<Callout type="info"> |
| 88 | + Omit the `[features.web_fetch]` section entirely to disable web fetch. When present, set `enabled |
| 89 | + = false` to temporarily disable without removing the configuration. |
| 90 | +</Callout> |
| 91 | + |
| 92 | +### Security |
| 93 | + |
| 94 | +Web fetch includes multiple layers of SSRF protection: |
| 95 | + |
| 96 | +| Protection | Description | |
| 97 | +| ----------------- | -------------------------------------------------------------- | |
| 98 | +| URL validation | Blocks private/loopback IPs by default | |
| 99 | +| DNS pinning | Resolves DNS once and pins the connection to prevent rebinding | |
| 100 | +| Redirect blocking | Rejects HTTP redirects to prevent SSRF via redirect chains | |
| 101 | +| Content filtering | Only fetches allowed content types | |
| 102 | +| Size limits | Truncates responses at `max_response_bytes` | |
| 103 | + |
| 104 | +To allow fetching from private/loopback addresses (development only): |
| 105 | + |
| 106 | +```toml |
| 107 | +[server] |
| 108 | +allow_loopback_urls = true |
| 109 | +allow_private_urls = true |
| 110 | +``` |
| 111 | + |
| 112 | +### Content Type Filtering |
| 113 | + |
| 114 | +The `allowed_content_types` list uses prefix matching. For example, `"text/html"` matches `"text/html; charset=utf-8"`. An empty list allows all content types (not recommended). |
| 115 | + |
| 116 | +## Complete Examples |
| 117 | + |
| 118 | +### Development |
| 119 | + |
| 120 | +```toml |
| 121 | +[features.web_search] |
| 122 | +provider = "tavily" |
| 123 | +api_key = "${TAVILY_API_KEY}" |
| 124 | +max_results = 5 |
| 125 | +timeout_secs = 10 |
| 126 | + |
| 127 | +[features.web_fetch] |
| 128 | +max_response_bytes = 524288 |
| 129 | +timeout_secs = 15 |
| 130 | +``` |
| 131 | + |
| 132 | +### Production |
| 133 | + |
| 134 | +```toml |
| 135 | +[features.web_search] |
| 136 | +provider = "tavily" |
| 137 | +api_key = "${TAVILY_API_KEY}" |
| 138 | +max_results = 10 |
| 139 | +timeout_secs = 30 |
| 140 | +cost_microcents_per_request = 10000 |
| 141 | + |
| 142 | +[features.web_fetch] |
| 143 | +max_response_bytes = 1048576 |
| 144 | +timeout_secs = 30 |
| 145 | +cost_microcents_per_request = 0 |
| 146 | +allowed_content_types = ["text/html", "text/plain", "application/json"] |
| 147 | +``` |
| 148 | + |
| 149 | +### Web Fetch Only |
| 150 | + |
| 151 | +```toml |
| 152 | +# No [features.web_search] — web search disabled |
| 153 | + |
| 154 | +[features.web_fetch] |
| 155 | +max_response_bytes = 2097152 |
| 156 | +timeout_secs = 60 |
| 157 | +``` |
| 158 | + |
| 159 | +## Next Steps |
| 160 | + |
| 161 | +- [Web Tools Feature Guide](/docs/features/web-tools) — How web tools work in the chat UI |
| 162 | +- [Frontend Tools](/docs/features/frontend-tools) — Client-side tools (Python, JS, SQL, charts) |
| 163 | +- [Authorization](/docs/features/authorization) — RBAC policies for tool access |
0 commit comments