README

Perplexity tools for the Laravel AI SDK - Search and Ask (Sonar)

Part of the shipfastlabs/toolkit catalog of reusable AI tools for the Laravel AI SDK.

Installation

composer require shipfastlabs/toolkit-perplexity

Usage

Register every Perplexity tool at once with the Perplexity helper:

use Shipfastlabs\Toolkit\Perplexity\Perplexity;

$tools = Perplexity::all(); // Collection<int, Tool>

Or add individual tools to an agent's tools():

use Shipfastlabs\Toolkit\Perplexity\PerplexitySearch;
use Shipfastlabs\Toolkit\Perplexity\PerplexityAsk;

$tools = [
    new PerplexitySearch,
    new PerplexityAsk,
];

Tools

PerplexitySearch

Search the web for real-time information and get a ranked list of sources. Uses the Perplexity Search API.

PerplexityAsk

Ask a question and get a direct, cited answer grounded in a live web search using Perplexity's Sonar models. The response includes the answer text plus the search_results and citations used.

Provider setup

Both tools read their API key from Laravel's services config and their optional defaults from the ai config.

1. Add the Perplexity service to config/services.php

// config/services.php

return [

    // ... existing services ...

    'perplexity' => [
        'key' => env('PERPLEXITY_API_KEY'),
    ],

];

2. Add toolkit defaults to config/ai.php

// config/ai.php

return [

    // ... existing laravel/ai config ...

    'toolkit' => [
        'perplexity' => [
            'search' => [
                'max_results' => (int) env('PERPLEXITY_SEARCH_MAX_RESULTS', 10),
                'recency' => env('PERPLEXITY_SEARCH_RECENCY'),
            ],
            'ask' => [
                'model' => env('PERPLEXITY_ASK_MODEL', 'sonar'),
                'search_mode' => env('PERPLEXITY_ASK_SEARCH_MODE', 'web'),
            ],
        ],
    ],

];

3. Add environment variables to .env

PERPLEXITY_API_KEY=pplx-your-key-here

# Search defaults
PERPLEXITY_SEARCH_MAX_RESULTS=10
PERPLEXITY_SEARCH_RECENCY=

# Ask defaults
PERPLEXITY_ASK_MODEL=sonar
PERPLEXITY_ASK_SEARCH_MODE=web

Safety

• Both tools validate required inputs before calling the API.
• max_results is clamped to its valid 1-20 range.
• model, search_mode, and search_recency_filter are validated against allow-lists, falling back to safe defaults.
• API errors are caught and returned as friendly string messages.
• Requires a valid Perplexity API key.

Perplexity API

These tools use the Perplexity API. You'll need an API key from your Perplexity account settings.

Full API reference:

• Search Endpoint
• Chat Completions Endpoint