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 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 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:

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
anthropic	maxUses, allowedDomains, blockedDomains, userLocation	Anthropic web search tool
google	none; pass {}	Grounding with 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

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 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 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

// 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 for the full output shape and metadata fields.