> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-reference/ai-gateway/web-search.md).

# Web Search

## Overview

AI Generate can run a provider's native web search as part of a generation. The model searches the live web, grounds its answer in what it finds, and returns source URLs alongside the text. You enable it per request through a `providerTools` field on the AI Generate input, with no extra nodes.

`providerTools` works like `providerOptions`: you supply one block per provider namespace, and the executing [AI Route](/documentation-and-resources/components-and-data/ai-routes.md) reads only the block for the provider it runs. A single payload can carry search config for every provider, so search keeps working when a Route fails over from one provider to another.

### Benefits

* **One request field** - Turn on web search by adding `providerTools` to the input; no tool nodes to wire.
* **Provider-agnostic** - Set all provider blocks once; each Route uses the one that applies.
* **Failover-safe** - A payload with every namespace stays valid across [AI Route](/documentation-and-resources/components-and-data/ai-routes.md) fallbacks; each provider applies the settings it supports and ignores the rest.
* **Normalized result** - A `providerToolActivity` field reports the search the same way across providers, alongside a `sources` array of the URLs used.

## Input Format

Add `providerTools` to the same input object you pass to AI Generate (default `msg.payload`), next to `prompt` or `messages`:

```json
msg.payload = {
  prompt: "What are the top technology news stories today? Cite your sources.",
  providerTools: {
    openai:    { webSearch: { searchContextSize: "medium" } },
    anthropic: { webSearch: { maxUses: 3 } },
    google:    { webSearch: {} }
  }
};
```

`providerTools` is keyed by provider namespace. The AI Route's connection provider selects the namespace using the same mapping as `providerOptions`:

| Namespace   | Used by connection provider    |
| ----------- | ------------------------------ |
| `openai`    | OpenAI, Azure OpenAI           |
| `anthropic` | Anthropic, Vertex AI Anthropic |
| `google`    | Google AI, Vertex AI           |

Every other block is ignored, so it is safe to set all three.

The tool key inside each block is `webSearch` (the only tool today). An unrecognized tool key is skipped with a warning and the request still succeeds.

### Per-Provider Configuration

Each provider reads the config in its own vocabulary. Set the fields that apply to the provider your Route uses:

| Namespace   | Config                                                        | Provider reference                                                                                        |
| ----------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `openai`    | `searchContextSize`, `userLocation`                           | [OpenAI web search](https://platform.openai.com/docs/guides/tools-web-search)                             |
| `anthropic` | `maxUses`, `allowedDomains`, `blockedDomains`, `userLocation` | [Anthropic web search tool](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool) |
| `google`    | none; pass `{}`                                               | [Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search)                       |

Azure OpenAI accepts a subset of the OpenAI settings (`searchContextSize` and an approximate `userLocation`); other fields are dropped. Vertex AI uses the same empty-config form as `google`.

**Example: constrain the search by location**

```json
msg.payload = {
  prompt: "What is the current weather?",
  providerTools: {
    openai: {
      webSearch: {
        searchContextSize: "low",
        userLocation: {
          type: "approximate",
          city: "San Francisco",
          region: "California",
          country: "US",
          timezone: "America/Los_Angeles"
        }
      }
    },
    anthropic: {
      webSearch: {
        maxUses: 2,
        userLocation: {
          type: "approximate",
          city: "San Francisco",
          region: "California",
          country: "US",
          timezone: "America/Los_Angeles"
        }
      }
    },
    google: { webSearch: {} }
  }
};
```

## Using Web Search With Tools

Web search runs alongside any [Tools](/documentation-and-resources/components-and-data/flows/node-reference/ai-gateway/ai-tool.md) you select on the AI Generate node. In a single generation the model can search the web and call your tools. See [Tool Calling with AI Generate](/documentation-and-resources/components-and-data/flows/node-reference/ai-gateway/ai-generate.md) for tool setup.

Two behaviors to know:

* **Name collision** - If one of your tools is named `web_search` and the provider's search tool has the same native name, your tool keeps its name and the provider search is exposed to the model as `provider_web_search`.
* **Gemini before v3** - Older Gemini models cannot combine search grounding with function tools. On those models, when you select tools the search is dropped and your tools still run.

## Output Format

Providers report web search differently, so the response includes a normalized field that reports it the same way everywhere.

* **`providerToolActivity`** - The normalized, provider-agnostic signal. An array of provider-executed tool activity, discriminated by `tool`. When a web search ran it holds a `webSearch` entry whose `data` carries the search `queries` (when the provider exposes them) and `sources`. It is `[]` when no provider tool ran. Read this to confirm a search happened without branching on provider.
* **`sources`** - The response-level aggregate of the sources used to ground the answer. Each entry has `sourceType`, `id`, `url`, and `title`, plus a `providerMetadata` object on providers that attach one (e.g. Anthropic).
* **`text`** - The grounded answer, often with inline citations.
* **`steps`** - Raw per-step detail. For OpenAI, Azure OpenAI, and Anthropic the search appears here as provider-executed tool calls. For Google and Vertex AI, the gateway normalizes Gemini's search into grounding metadata under `providerMetadata` rather than a tool call, so no tool-call step appears.

Gemini grounds without a tool call, so `providerToolActivity` (which folds in the grounding case) is the field to check rather than scanning `steps` for a tool call.

**Example output**

```json
// msg.payload after node execution
{
  generationType: "text",
  text: "Mount Everest is Earth's highest mountain above sea level, at 8,849 meters. ([example.com](https://example.com/mount-everest))",
  providerToolActivity: [
    {
      tool: "webSearch",
      provider: "openai",
      data: {
        queries: ["how tall is Mount Everest"],
        sources: [
          { sourceType: "url", id: "everestSource", url: "https://example.com/mount-everest", title: "Mount Everest - Elevation and Facts" }
        ]
      }
    }
  ],
  sources: [
    { sourceType: "url", id: "everestSource", url: "https://example.com/mount-everest", title: "Mount Everest - Elevation and Facts" }
  ],
  model: "...",
  providerType: "openai",
  finishReason: "stop",
  usage: { inputTokens: 10809, outputTokens: 1787, totalTokens: 12596 }
}
```

See [AI Generate](/documentation-and-resources/components-and-data/flows/node-reference/ai-gateway/ai-generate.md) for the full output shape and metadata fields.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-reference/ai-gateway/web-search.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.