Web search domain constraints are accepted and silently discarded by providers that cannot honour them

[saarnilauri]

WebSearch carries allowedDomains and disallowedDomains. Anthropic honours them. The other two first-party providers accept the configuration, emit a bare search tool, and discard the domains — with no error, no warning, and no way for the caller to find out.

Evidence

ai-provider-for-openai, src/Models/OpenAiTextGenerationModel.php:417-421:

if ($webSearch) {
    $webSearchTool = ['type' => 'web_search'];
    // Note: The OpenAI Responses API web_search tool may have different filtering options.
    // For now, we use the basic form.
    $tools[] = $webSearchTool;
}

ai-provider-for-google, src/Models/GoogleTextGenerationModel.php:224-227:

$webSearch = $config->getWebSearch();
if ($webSearch) {
    // Filtering by allowed or disallowed domains is not supported by the Google AI API.
    $tools[] = ['googleSearch' => new \stdClass()];
}

Both declare the option as supported — OpenAiModelMetadataDirectory.php:90 and GoogleModelMetadataDirectory.php:144 both contain new SupportedOption(OptionEnum::webSearch()) — so ModelResolver routes to them happily.

For contrast, ai-provider-for-anthropic passes them through (AnthropicTextGenerationModel.php:593-594).

Why this is worth changing

A caller who restricts a search to a domain is usually doing it for correctness or safety — grounding an assistant in a site's own content, keeping a regulated product away from sources it may not cite. Dropping that constraint does not degrade the feature, it inverts it: the request that was meant to be narrower than an unrestricted search silently becomes an unrestricted one. A caller cannot detect it from the result, because a plausible answer comes back either way.

The Google comment is the interesting part. It shows the limitation is known and deliberately not signalled — the provider is aware it cannot honour the constraint and has no way to say so. That is the argument for fixing this in the SDK rather than in either plugin: a provider that knows it cannot satisfy a requested constraint currently has nowhere to report that.

Possible directions

1. Make domain filtering separately declarable. A required option distinct from webSearch itself, so a provider that supports search but not domain filtering does not advertise it and ModelResolver never routes there. Fails at resolution time, which is the earliest and cheapest point.
2. Throw at request time in providers that cannot honour a populated domain list. Simpler, but fails later and per-request.
3. Status quo, documented. Cheapest, and leaves the sharp edge in place.

1 seems right to me, with the caveat that OptionEnum synthesises its cases by reflecting over ModelConfig's KEY_* constants (only INPUT_MODALITIES is declared literally), so a new option needs a home in ModelConfig or an explicit constant alongside INPUT_MODALITIES — worth deciding deliberately rather than as a side effect.

I am raising it here rather than on the two provider repos because neither can fix it alone: the OpenAI and Google APIs do not offer domain filtering at all, so there is no provider-side implementation to write. The only available fix is an SDK-level mechanism for declining to route, or for reporting the constraint as unmet. Happy to open provider-side issues and a PR once there is a direction.

[saarnilauri]

Correction to the last paragraph of my original report, which was wrong in a way that changes the recommendation.

I wrote that "the OpenAI and Google APIs do not offer domain filtering at all, so there is no provider-side implementation to write." That is wrong for OpenAI. From OpenAI's web search documentation, verbatim:

With the filters parameter you can configure up to 100 allowed_domains or up to 100 blocked_domains.

{
  "type": "web_search",
  "filters": {
    "allowed_domains": ["pubmed.ncbi.nlm.nih.gov", "clinicaltrials.gov", "www.who.int"]
  }
}

It is generally available on the Responses API web_search tool (not the legacy web_search_preview). So OpenAiTextGenerationModel::prepareToolsParam() has a direct fix available today: map the DTO's existing allowedDomains / disallowedDomains onto filters. The code comment there — "the OpenAI Responses API web_search tool may have different filtering options" — has been overtaken. I will open that separately on the provider repo; it needs nothing from this issue.

What this leaves. The issue narrows to Google, which still has no domain filtering, but does not dissolve: a provider that supports web search and cannot honour a domain constraint still has no way to say so, and ModelResolver routes to it regardless.

It also strengthens the case. Domain filtering turns out to be close to universal. Surveying the search tools reachable through the Vercel AI Gateway:

Tool	Domain filtering
Anthropic	yes
OpenAI	yes, ≤100
xAI	yes, ≤5
Perplexity	yes, ≤20
Exa	yes
Tako	yes, ≤20
Parallel	yes
Google	no

Six of eight, with Google the sole outlier rather than the pattern. That makes the DTO's existing domain fields well-chosen, and makes silently discarding the constraint a worse default than I first argued: one provider's limitation, paid for by every caller, in a form they cannot detect.

For what it is worth, the resolver-level opt-out does work when providers use it — the Vercel AI Gateway and Grok provider plugins both omit webSearch() from their supported options and are simply never routed to. What is missing is the finer granularity: declaring web search while declining a constraint within it.

The ask therefore stands, more narrowly framed: sub-option granularity, or some way for a provider to report a supported option as unsatisfiable for a given value, so resolution fails instead of the constraint evaporating.

[sarthak-19]

Dug into how php-ai-client would need to change to fix this, before proposing a direction , sharing what I found since it narrows the fix.

Confirmed: ModelRequirements::toRequiredOptions() (src/Providers/Models/DTO/ModelRequirements.php:409-411) currently reduces webSearch to a boolean requirement RequiredOption(OptionEnum::webSearch(), true). The allowedDomains/disallowedDomains values never reach SupportedOption/RequiredOption matching at all. So today ModelResolver can't distinguish "supports web search" from "supports web search restricted to domains" the gap is a level deeper than a provider-side silent discard.

Also confirmed: OptionEnum (src/Providers/Models/Enums/OptionEnum.php:91-115) synthesizes nearly all its cases by reflecting over ModelConfig::KEY_* constants only INPUT_MODALITIES is hard-coded (derived from message content, not a real config key). So fixing this means adding to that reflected surface, which every provider plugin's metadata directory depends on.

Given that, it seems worth aligning on direction before opening PRs across three repos. Candidate directions:

1. Separate declarable sub-option e.g. OptionEnum::webSearchDomainFilter(), required only when allowedDomains/disallowedDomains are non-empty. A provider that omits it from its SupportedOption list is simply never routed to for that request, resolved at ModelResolver time before any API call the same pattern the Vercel AI Gateway and Grok providers already use by omitting webSearch() entirely when they can't support it.
2. Throw at request time in providers that receive a populated domain list they can't honour. No OptionEnum/ModelConfig change needed, but fails later and per-request rather than at resolution.
3. Status quo, documented.

Leaning toward (1), for consistency with how ModelResolver already excludes models that can't meet a requirement. If that's the direction, two things worth deciding explicitly rather than as a side effect:

• Should this generalize to a "capability-with-constraints" mechanism, or is a one-off webSearchDomainFilter-style option good enough for now?
• Should the new option live as a new ModelConfig::KEY_* constant (picked up by OptionEnum's reflection), or as an explicit literal case alongside INPUT_MODALITIES (which is deliberately not reflected, since it isn't a real ModelConfig key)?

Separately: the OpenAI provider-side gap (mapping onto filters.allowed_domains/blocked_domains, which the Responses API already supports) doesn't depend on any of this happy to open that as a direct PR on ai-provider-for-openai regardless of which direction this takes.