Laravel AI’s own WebSearch tool is a provider tool: it runs inside the provider’s API. Cloudflare has no such feature on chat calls, so that tool can’t run on Workers AI. Cloudflare does have a separate Web Search API, though, and CloudflareWebSearch is a normal tool that calls it. It runs in your app and works with any model that calls tools.
Before you start
- Cloudflare bills each search, so load AI Gateway credits on your account, or store a search provider’s key on a gateway.
- Use a model that calls tools, such as
@cf/openai/gpt-oss-120b. The package’s default text model doesn’t.
The tool uses the key from your workers-ai provider entry. In a test on 2026-11-05, a token with only Workers AI Read could search through the default gateway. Cloudflare’s docs also list AI Gateway Read for this API, so add that permission 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, and the tool returns a JSON list of results, each with a url, title and description. Laravel AI runs the tool loop as it does 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, while two other named gateways returned 400 web_search_byok_not_configured. If you get that error on a gateway you passed with gateway:, store a provider key on it, or use default.
Search without a model
You can also call the search yourself, 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
The tool has no fake of its own, so 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.']],
])]);