Skip to content

Web search

Give a Workers AI model web search with a normal tool that calls Cloudflare's Web Search API.

Updated

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.']],
])]);

Type to search…

↑↓ navigate↵ selectEsc close