> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Search

# Web Search

The `web_search` tool searches the web using your configured provider and
returns results. Results are cached by query for 15 minutes (configurable).

> [!NOTE]
>
> `web_search` is a lightweight HTTP tool, not browser automation. For
> JS-heavy sites or logins, use the [Web Browser](https://agdiai-597e782f.mintlify.site/tools/browser.md). For
> fetching a specific URL, use [Web Fetch](https://agdiai-597e782f.mintlify.site/tools/web-fetch.md).

## Quick start

**1. Get an API key**

Pick a provider and get an API key. See the provider pages below for
sign-up links.

**2. Configure**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi configure --section web
```

This stores the key and sets the provider. You can also set an env var
(e.g. `BRAVE_API_KEY`) and skip this step.

**3. Use it**

The agent can now call `web_search`:

```javascript theme={"theme":{"light":"min-light","dark":"min-dark"}}
await web_search({ query: "Agdi plugin SDK" });
```

## Choosing a provider

> [card] [Brave Search](https://agdiai-597e782f.mintlify.site/tools/brave-search.md)
>
> Structured results with snippets. Supports `llm-context` mode, country/language filters. Free tier available.

> [card] [DuckDuckGo](https://agdiai-597e782f.mintlify.site/tools/duckduckgo-search.md)
>
> Key-free fallback. No API key needed. Unofficial HTML-based integration.

> [card] [Exa](https://agdiai-597e782f.mintlify.site/tools/exa-search.md)
>
> Neural + keyword search with content extraction (highlights, text, summaries).

> [card] [Firecrawl](https://agdiai-597e782f.mintlify.site/tools/firecrawl.md)
>
> Structured results. Best paired with `firecrawl_search` and `firecrawl_scrape` for deep extraction.

> [card] [Gemini](https://agdiai-597e782f.mintlify.site/tools/gemini-search.md)
>
> AI-synthesized answers with citations via Google Search grounding.

> [card] [Grok](https://agdiai-597e782f.mintlify.site/tools/grok-search.md)
>
> AI-synthesized answers with citations via xAI web grounding.

> [card] [Kimi](https://agdiai-597e782f.mintlify.site/tools/kimi-search.md)
>
> AI-synthesized answers with citations via Moonshot web search.

> [card] [Perplexity](https://agdiai-597e782f.mintlify.site/tools/perplexity-search.md)
>
> Structured results with content extraction controls and domain filtering.

> [card] [Tavily](https://agdiai-597e782f.mintlify.site/tools/tavily.md)
>
> Structured results with search depth, topic filtering, and `tavily_extract` for URL extraction.

### Provider comparison

| Provider | Result style | Filters | API key |
| - | - | - | - |
| [Brave](https://agdiai-597e782f.mintlify.site/tools/brave-search.md) | Structured snippets | Country, language, time, `llm-context` mode | `BRAVE_API_KEY` |
| [DuckDuckGo](https://agdiai-597e782f.mintlify.site/tools/duckduckgo-search.md) | Structured snippets | -- | None (key-free) |
| [Exa](https://agdiai-597e782f.mintlify.site/tools/exa-search.md) | Structured + extracted | Neural/keyword mode, date, content extraction | `EXA_API_KEY` |
| [Firecrawl](https://agdiai-597e782f.mintlify.site/tools/firecrawl.md) | Structured snippets | Via `firecrawl_search` tool | `FIRECRAWL_API_KEY` |
| [Gemini](https://agdiai-597e782f.mintlify.site/tools/gemini-search.md) | AI-synthesized + citations | -- | `GEMINI_API_KEY` |
| [Grok](https://agdiai-597e782f.mintlify.site/tools/grok-search.md) | AI-synthesized + citations | -- | `XAI_API_KEY` |
| [Kimi](https://agdiai-597e782f.mintlify.site/tools/kimi-search.md) | AI-synthesized + citations | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [Perplexity](https://agdiai-597e782f.mintlify.site/tools/perplexity-search.md) | Structured snippets | Country, language, time, domains, content limits | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
| [Tavily](https://agdiai-597e782f.mintlify.site/tools/tavily.md) | Structured snippets | Via `tavily_search` tool | `TAVILY_API_KEY` |

## Auto-detection

Provider lists in docs and setup flows are alphabetical. Auto-detection keeps a
separate precedence order:

If no `provider` is set, Agdi checks for API keys in this order and uses
the first one found:

1. **Brave** -- `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey`
2. **Gemini** -- `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey`
3. **Grok** -- `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
4. **Kimi** -- `KIMI_API_KEY` / `MOONSHOT_API_KEY` or `plugins.entries.moonshot.config.webSearch.apiKey`
5. **Perplexity** -- `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` or `plugins.entries.perplexity.config.webSearch.apiKey`
6. **Firecrawl** -- `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webSearch.apiKey`
7. **Tavily** -- `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey`

If no keys are found, it falls back to Brave (you will get a missing-key error
prompting you to configure one).

> [!NOTE]
>
> All provider key fields support SecretRef objects. In auto-detect mode,
> Agdi resolves only the selected provider key -- non-selected SecretRefs
> stay inactive.

## Config

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    web: {
      search: {
        enabled: true, // default: true
        provider: "brave", // or omit for auto-detection
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}
```

Provider-specific config (API keys, base URLs, modes) lives under
`plugins.entries.<plugin>.config.webSearch.*`. See the provider pages for
examples.

### Storing API keys

> [tab] Config file
>
> Run `agdi configure --section web` or set the key directly:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   plugins: {
>     entries: {
>       brave: {
>         config: {
>           webSearch: {
>             apiKey: "YOUR_KEY", // pragma: allowlist secret
>           },
>         },
>       },
>     },
>   },
> }
> ```

> [tab] Environment variable
>
> Set the provider env var in the Gateway process environment:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> export BRAVE_API_KEY="YOUR_KEY"
> ```
>
> For a gateway install, put it in `~/.agdi/.env`.
> See [Env vars](https://agdiai-597e782f.mintlify.site/help/faq.md#env-vars-and-env-loading).

## Tool parameters

| Parameter | Description |
| - | - |
| `query` | Search query (required) |
| `count` | Results to return (1-10, default: 5) |
| `country` | 2-letter ISO country code (e.g. "US", "DE") |
| `language` | ISO 639-1 language code (e.g. "en", "de") |
| `freshness` | Time filter: `day`, `week`, `month`, or `year` |
| `date_after` | Results after this date (YYYY-MM-DD) |
| `date_before` | Results before this date (YYYY-MM-DD) |
| `ui_lang` | UI language code (Brave only) |
| `domain_filter` | Domain allowlist/denylist array (Perplexity only) |
| `max_tokens` | Total content budget, default 25000 (Perplexity only) |
| `max_tokens_per_page` | Per-page token limit, default 2048 (Perplexity only) |

> [!WARNING]
>
> Not all parameters work with all providers. Brave `llm-context` mode
> rejects `ui_lang`, `freshness`, `date_after`, and `date_before`.
> Firecrawl and Tavily only support `query` and `count` through `web_search`
> \-- use their dedicated tools for advanced options.

## Examples

```javascript theme={"theme":{"light":"min-light","dark":"min-dark"}}
// Basic search
await web_search({ query: "Agdi plugin SDK" });

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

// Date range
await web_search({
  query: "climate research",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Domain filtering (Perplexity only)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});
```

## Tool profiles

If you use tool profiles or allowlists, add `web_search` or `group:web`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    allow: ["web_search"],
    // or: allow: ["group:web"]  (includes both web_search and web_fetch)
  },
}
```

## Related

* [Web Fetch](https://agdiai-597e782f.mintlify.site/tools/web-fetch.md) -- fetch a URL and extract readable content
* [Web Browser](https://agdiai-597e782f.mintlify.site/tools/browser.md) -- full browser automation for JS-heavy sites


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.