Laravel AI’s WebSearch provider tool runs inside the provider’s own API. Cloudflare has no such feature on chat calls, so that tool cannot run on Workers AI.
Cloudflare does have a Web Search API. CloudflareWebSearch is a normal tool that calls it. It runs in your app, and works with any model that calls tools.
Before you start
- Load AI Gateway credits on your account, or store a search provider’s key on a gateway. Cloudflare bills each search.
- Use a model that calls tools, such as
@cf/openai/gpt-oss-120b. The package’s default text model does not.
The tool uses the key from your workers-ai provider entry. In a test on 2026-11-05, a token with Workers AI Read searched the default gateway. Cloudflare’s docs also list AI Gateway Read for this API, so add it if you get a permission error.
Give the tool to a model
use Meirdick\WorkersAi\Tools\CloudflareWebSearch;
use function Laravel\Ai\agent;
$response = agent(
'Search the web, then answer in one short sentence.',
tools: [new CloudflareWebSearch(limit: 3)],
)->prompt(
'What is Cloudflare Workers AI?',
provider: 'workers-ai',
model: '@cf/openai/gpt-oss-120b',
);The model sends a query. The tool returns a JSON list of results, each with a url, title and description. Laravel AI runs the tool loop, as for any other tool. See Tools.
Options
| Argument | Default | Description |
|---|---|---|
limit |
5 |
Results per search, 1 to 10. |
searchProvider |
none | ceramic, exa or linkup. Cloudflare’s default is ceramic. |
gateway |
default |
The AI Gateway that runs and bills the search. |
byokAlias |
none | The alias of a provider key stored on the gateway. |
provider |
workers-ai |
The Laravel AI provider entry that holds your credentials. |
The tool uses the default gateway even when your provider entry sets gateway. In tests on 2026-11-05, default and one named gateway returned results, and two other named gateways returned 400 web_search_byok_not_configured. If that error appears on a gateway you pass with gateway:, store a provider key on it, or use default.
Search without a model
$results = (new CloudflareWebSearch(limit: 3))->search('Laravel release dates');
$results[0]['url'];Errors
A failed search throws AiException with Cloudflare’s message, such as No provider key is configured on this gateway. The tool needs account_id, or a url that ends in /ai/v1. A url that ends in /compat throws.
Test your code
Fake the HTTP call:
use Illuminate\Support\Facades\Http;
Http::fake(['*/ai/websearch/' => Http::response([
'items' => [['url' => 'https://example.com', 'title' => 'Example', 'description' => 'A result.']],
])]);