How to Use Laravel AI Provider Tools with the agent() Helper

The Question

How do you enable Laravel AI’s provider tools (like WebSearch, WebFetch, or FileSearch) when using the agent() helper? They’re not regular tools—they’re native provider capabilities—but the API surface looks identical.

The Answer

Provider tools pass through the same tools parameter as regular tools. Laravel AI’s gateway layer automatically detects and separates them under the hood.

Basic Usage

use Laravel\Ai\Providers\Tools\WebSearch;
use function Laravel\Ai\agent;

$response = agent(
    instructions: 'You are a research assistant.',
    tools: [new WebSearch],
)->prompt('What are the best practices for API rate limiting?');

With Configuration Options

Provider tools support fluent configuration:

$response = agent(
    instructions: 'You are a research assistant.',
    tools: [
        (new WebSearch)
            ->max(5)                                      // limit number of searches
            ->allow(['stackoverflow.com', 'laravel.com']) // restrict to specific domains
            ->location(city: 'London', country: 'UK'),    // refine by geographic context
    ],
)->prompt('Find recent discussions on queue optimization.');

Mixing Provider Tools with Regular Tools

You can combine them seamlessly:

$response = agent(
    instructions: 'You are a research assistant.',
    tools: [
        new WebSearch,         // provider tool (handled natively)
        new DatabaseQuery,     // your custom Tool implementation
    ],
)->prompt('Research this topic and query our internal database for related records.');

Available Provider Tools

• WebSearch — Search the web (Anthropic, OpenAI, Gemini)
• WebFetch — Fetch and extract content from URLs (Anthropic, Gemini)
• FileSearch — Semantic search over file stores (OpenAI, Gemini)

Provider Support Matrix

Note: If your configured provider doesn’t support a given tool, Laravel AI throws a RuntimeException at runtime.

Why This Matters

Provider tools unlock powerful native capabilities without the overhead of implementing custom tool handlers. When your agent needs to search the web, fetch external content, or query semantic file stores, you can hand that responsibility directly to the provider’s optimized implementation.

The unified API keeps your code simple: whether it’s a native provider tool or your own custom tool, they all live in the same tools array.