PHPackages                             avvertix/laravel-agent-request - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. avvertix/laravel-agent-request

ActiveLibrary

avvertix/laravel-agent-request
==============================

Attempt to identify if an AI Agent want to browse a page

v0.0.3(2mo ago)042↓50%[2 PRs](https://github.com/avvertix/laravel-agent-request/pulls)MITPHPPHP ^8.3CI passing

Since Mar 4Pushed 1mo agoCompare

[ Source](https://github.com/avvertix/laravel-agent-request)[ Packagist](https://packagist.org/packages/avvertix/laravel-agent-request)[ Docs](https://github.com/avvertix/laravel-agent-request)[ RSS](/packages/avvertix-laravel-agent-request/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (28)Versions (6)Used By (0)

Laravel Agent Request
=====================

[](#laravel-agent-request)

[![Latest Version on Packagist](https://camo.githubusercontent.com/f8a7bc607c3d1d5a6421093a18cf18032a19c29c260bc018c6318cd87d5e45d3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61767665727469782f6c61726176656c2d6167656e742d726571756573742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/avvertix/laravel-agent-request)[![GitHub Tests Action Status](https://camo.githubusercontent.com/8a7378c3d21084b7a31c753974e4548afb0213e147f9c1d1f26f1d2cef811b1f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f61767665727469782f6c61726176656c2d6167656e742d726571756573742f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/avvertix/laravel-agent-request/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/b2ba14475c2c652b4a80ec1136d6b0c3878706adb22de2aef3c3f5ce93d8d72c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f61767665727469782f6c61726176656c2d6167656e742d726571756573742f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/avvertix/laravel-agent-request/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/b0fa7a67c941d2a635f6b89f5a41068e9bfb442f2314f7dcd93645288b536d91/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f61767665727469782f6c61726176656c2d6167656e742d726571756573742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/avvertix/laravel-agent-request)

Detect and manage AI agent HTTP requests in Laravel applications. It identifies AI assistants, crawlers, and data-extraction tools via User-Agent patterns and infrastructure headers, then gives you middleware to block, trace, or serve them differently.

Requirements
------------

[](#requirements)

- PHP 8.3 or higher

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require avvertix/laravel-agent-request
```

The service provider is auto-discovered by Laravel.

Configuration
-------------

[](#configuration)

Agent Request is configurable via environment variables.

VariableDefaultDescription`AGENT_REQUEST_ENABLED``true`Set to `false` to bypass all middleware globally`AGENT_REQUEST_BLOCK`—Comma-separated list of categories to block, e.g. `assistant,crawler,tool`In case you want to configure the detection logic you can publish the configuration file:

```
php artisan vendor:publish --tag="laravel-agent-request-config"
```

### Environment variables

[](#environment-variables)

Agent categories
----------------

[](#agent-categories)

We groups known AI agents into three categories:

Category`AgentType`DescriptionAssistants`AgentType::ASSISTANT`Agents browsing on behalf of a live user (ChatGPT-User, Claude-User, Gemini, Perplexity-User, …)Crawlers`AgentType::CRAWLER`Automated training and indexing bots (GPTBot, ClaudeBot, Google-Extended, Applebot, …)Tools`AgentType::TOOL`AI-powered research and data-extraction tools (Diffbot, FirecrawlAgent, Scrapy, TavilyBot, …)Requests that match no known pattern return `AgentType::HUMAN`.

Usage
-----

[](#usage)

### Detecting agents in a controller

[](#detecting-agents-in-a-controller)

Inject or type-hint `AgentRequest` instead of the standard `Request`:

```
use Avvertix\AgentRequest\LaravelAgentRequest\Http\AgentRequest;
use Avvertix\AgentRequest\LaravelAgentRequest\Enums\AgentType;

class PageController
{
    public function show(AgentRequest $request)
    {
        if ($request->isAgent()) {
            // Any AI agent
        }

        $type = $request->detect();          // AgentType::CRAWLER, ::ASSISTANT, ::TOOL, or ::HUMAN
        $name = $request->agentName();       // e.g. 'GPTBot', 'Claude', null for humans

        if ($type === AgentType::ASSISTANT) {
            // Respond differently for interactive AI assistants
        }

        if ($request->expectsMarkdown()) {
            return response($markdown, headers: ['Content-Type' => 'text/markdown']);
        }
    }
}
```

All detection methods available on `AgentRequest`:

MethodReturnsDescription`isAgent()``bool`Any recognised AI agent`isAiAssistant()``bool`User-facing AI assistant`isAiCrawler()``bool`Training or indexing crawler`isAiTool()``bool`Data-extraction or research tool`isCloudflareBrowserRendering()``bool`Cloudflare Browser Rendering infrastructure`detect()``AgentType`Category of the detected agent`agentName()``?string`Canonical name key of the agent, or `null``wantsMarkdown()``bool``Accept` header contains `text/markdown` or `text/x-markdown``expectsMarkdown()``bool``wantsMarkdown()` or `Accept: text/plain`### Middleware

[](#middleware)

Register middleware in `bootstrap/app.php` or a route group:

```
use Avvertix\AgentRequest\LaravelAgentRequest\Http\Middleware\DenyAgentMiddleware;
use Avvertix\AgentRequest\LaravelAgentRequest\Http\Middleware\TraceAgentMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(DenyAgentMiddleware::class);
    $middleware->append(TraceAgentMiddleware::class);
})
```

#### DenyAgentMiddleware

[](#denyagentmiddleware)

Returns a `404 Not Found` response for any agent whose category appears in the `agent-request.block` config list.

By default `assistant` and `tool` agents are blocked; `crawler` agents are allowed through (they respect `robots.txt`). To block crawlers too, update the config or set the environment variable:

```
AGENT_REQUEST_BLOCK=assistant,crawler,tool
```

To disable blocking entirely without removing the middleware:

```
AGENT_REQUEST_ENABLED=false
```

#### TraceAgentMiddleware

[](#traceagentmiddleware)

Adds `agent_name` and `agent_type` to the [Laravel Context](https://laravel.com/docs/context) for every recognised AI agent request. Laravel includes them in log entries automatically:

```
agent_name: GPTBot
agent_type: AgentType::CRAWLER

```

This middleware never blocks. Stack it with `DenyAgentMiddleware` freely.

### Request macros

[](#request-macros)

The package adds two macros to the base `Illuminate\Http\Request`:

```
$request->isAgent();        // bool — any AI agent
$request->isAiAssistant();  // bool — user-facing AI assistant
```

### Using DetectAgent directly

[](#using-detectagent-directly)

```
use Avvertix\AgentRequest\LaravelAgentRequest\Actions\DetectAgent;

$detector = DetectAgent::fromRequest($request);

$detector->detect();      // AgentType
$detector->agentName();   // ?string
$detector->isAgent();
$detector->isAiCrawler();
```

Generating a robots.txt
-----------------------

[](#generating-a-robotstxt)

Generate a `robots.txt` that instructs known AI agents to not crawl your site:

```
# Write (or overwrite) public/robots.txt with all known agents
php artisan agent-request:robots-txt

# Limit to specific categories
php artisan agent-request:robots-txt --category=crawler
php artisan agent-request:robots-txt --category=assistant --category=crawler

# Append missing entries to an existing robots.txt without duplicating
php artisan agent-request:robots-txt --merge
```

`--category` accepts `assistant`, `crawler`, and `tool`. Pass it multiple times to combine. Omit it to include all three.

Extending the detector
----------------------

[](#extending-the-detector)

Extend `DetectAgent` and override the pattern arrays, then register your class in the config:

```
use Avvertix\AgentRequest\LaravelAgentRequest\Actions\DetectAgent;

class MyDetector extends DetectAgent
{
    protected static array $aiAssistants = [
        ...parent::$aiAssistants,
        'Acme' => 'AcmeAgent',
    ];
}
```

```
// config/agent-request.php
'detector' => MyDetector::class,
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Alessio Vertemati](https://github.com/avvertix)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

41

—

FairBetter than 88% of packages

Maintenance96

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

65d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0d6c28ebb739784366f8f6751e40d630edef88d0ea094dcbc656351a1417c0a2?d=identicon)[avvertix](/maintainers/avvertix)

---

Top Contributors

[![avvertix](https://avatars.githubusercontent.com/u/5672748?v=4)](https://github.com/avvertix "avvertix (10 commits)")

---

Tags

requestlaravelagentsartificial intelligence

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/avvertix-laravel-agent-request/health.svg)

```
[![Health](https://phpackages.com/badges/avvertix-laravel-agent-request/health.svg)](https://phpackages.com/packages/avvertix-laravel-agent-request)
```

###  Alternatives

[clickbar/laravel-magellan

This package provides functionality for working with the postgis extension in Laravel.

423715.4k1](/packages/clickbar-laravel-magellan)[spatie/laravel-prometheus

Export Laravel metrics to Prometheus

2651.3M6](/packages/spatie-laravel-prometheus)[vormkracht10/laravel-mails

Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app.

24149.7k](/packages/vormkracht10-laravel-mails)[ralphjsmit/laravel-glide

Auto-magically generate responsive images from static image files.

4719.6k5](/packages/ralphjsmit-laravel-glide)[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

3786.5k](/packages/harris21-laravel-fuse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)