Créer un agent personnalisé pour Boost

Découvrez l’architecture extensible de Laravel Boost et apprenez à créer un agent personnalisé qui implémente les contrats SupportsGuidelines, SupportsMcp et SupportsSkills.

​

Pourquoi un agent personnalisé est nécessaire

Laravel Boost prend en charge en standard les principaux outils de coding IA tels que Claude Code, Cursor, Codex, GitHub Copilot (VS Code). Cependant, pour prendre en charge des outils internes, des agents d’IA émergents ou des workflows propres, vous devez implémenter un agent personnalisé à l’aide des mécanismes d’extension de Boost.

Situations où un agent personnalisé est utile :

• Vous utilisez un IDE ou un outil d’IA non pris en charge par Boost
• Vous voulez intégrer Boost dans un workflow de développement interne ou un pipeline CI/CD propre
• L’agent a un format de fichier de configuration ou une procédure d’installation spécifiques

​

Architecture d’extension de Boost

​

La classe de base Agent

Tous les agents héritent de Laravel\Boost\Install\Agents\Agent. Cette classe abstraite fournit :

• La détection de l’agent (à l’échelle système ou du projet)
• L’installation du serveur MCP (basée sur des fichiers ou des commandes shell)
• Un hook de transformation des guidelines (transformGuidelines)

Deux méthodes abstraites sont obligatoires à implémenter.

Méthode	Description
name()	Identifiant interne de l’agent (ex. claude_code)
displayName()	Nom affiché lors de l’installation (ex. Claude Code)
systemDetectionConfig(Platform $platform)	Configuration de détection pour l’installation à l’échelle système
projectDetectionConfig()	Configuration de détection pour l’installation au niveau du projet

​

Les trois contrats

Pour activer sélectivement les fonctionnalités de Boost, implémentez les contrats ci-dessous selon vos besoins.

Contrat	Rôle
SupportsGuidelines	Chemin de sortie et transformation du fichier de guidelines d’IA
SupportsMcp	Installation de la configuration du serveur MCP
SupportsSkills	Chemin d’installation des Agent Skills

Les trois contrats sont tous facultatifs. Une implémentation qui ne prend en charge que les guidelines, sans MCP, est possible.

​

Le contrat SupportsGuidelines

interface SupportsGuidelines
{
    // Chemin de fichier où écrire les guidelines d'IA
    public function guidelinesPath(): string;

    // Le fichier de guidelines nécessite-t-il un frontmatter ?
    public function frontmatter(): bool;

    // Post-traite le Markdown de guidelines généré
    public function transformGuidelines(string $markdown): string;
}

guidelinesPath() retourne le chemin du fichier dans lequel les guidelines générées seront écrites. Adaptez-le au format lu par l’agent : CLAUDE.md pour Claude Code, .cursor/rules/laravel-boost.mdc pour Cursor, etc.

transformGuidelines() est un hook pour transformer le Markdown après génération. Vous pouvez ajouter un en-tête spécifique à l’agent ou convertir vers un format particulier. L’implémentation par défaut de la classe de base Agent retourne la chaîne telle quelle.

​

Le contrat SupportsMcp

interface SupportsMcp
{
    // Utiliser un chemin absolu pour la commande MCP ?
    public function useAbsolutePathForMcp(): bool;

    // Retourne le chemin de l'exécutable PHP
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // Retourne le chemin d'artisan
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // Installe la configuration du serveur MCP
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // Installe la configuration MCP en HTTP
    public function installHttpMcp(string $key, string $url): bool;
}

Comme la classe de base Agent fournit une implémentation par défaut de installMcp() et installHttpMcp(), il suffit dans la plupart des cas de surcharger mcpInstallationStrategy() et mcpConfigPath().

Il existe deux stratégies d’installation.

McpInstallationStrategy	Comportement
FILE	Écrit la configuration dans un fichier JSON/TOML (par défaut)
SHELL	Exécute une commande shell pour enregistrer le MCP
NONE	Ignore l’installation MCP

​

Le contrat SupportsSkills

interface SupportsSkills
{
    // Chemin du répertoire où écrire les Agent Skills
    public function skillsPath(): string;
}

Retourne le chemin du répertoire de skills lu par l’agent. Adaptez-le aux spécifications de l’agent : .claude/skills pour Claude Code, .cursor/skills pour Cursor, etc.

​

Création d’un agent personnalisé

Implémentons concrètement notre propre classe d’agent. Nous prendrons pour exemple un agent virtuel « MyAgent » intégré dans un workflow CI/CD propre.

1. Créer la classe d'agent

   Créez app/Boost/MyAgent.php.

   <?php
   
   declare(strict_types=1);
   
   namespace App\Boost;
   
   use Laravel\Boost\Contracts\SupportsGuidelines;
   use Laravel\Boost\Contracts\SupportsMcp;
   use Laravel\Boost\Contracts\SupportsSkills;
   use Laravel\Boost\Install\Agents\Agent;
   use Laravel\Boost\Install\Enums\McpInstallationStrategy;
   use Laravel\Boost\Install\Enums\Platform;
   
   class MyAgent extends Agent implements SupportsGuidelines, SupportsMcp, SupportsSkills
   {
       public function name(): string
       {
           return 'my_agent';
       }
   
       public function displayName(): string
       {
           return 'MyAgent';
       }
   
       public function systemDetectionConfig(Platform $platform): array
       {
           return match ($platform) {
               Platform::Darwin, Platform::Linux => [
                   'command' => 'command -v myagent',
               ],
               Platform::Windows => [
                   'command' => 'cmd /c where myagent 2>nul',
               ],
           };
       }
   
       public function projectDetectionConfig(): array
       {
           return [
               'files' => ['.myagent.json'],
           ];
       }
   
       // --- SupportsGuidelines ---
   
       public function guidelinesPath(): string
       {
           return 'MYAGENT.md';
       }
   
       // frontmatter() utilise la valeur par défaut de la classe de base Agent (false)
       // transformGuidelines() utilise également la valeur par défaut de la classe de base (retourne tel quel)
   
       // --- SupportsMcp ---
   
       // useAbsolutePathForMcp(), getPhpPath(), getArtisanPath(),
       // installMcp(), installHttpMcp() sont tous déjà implémentés par la classe de base Agent
   
       public function mcpInstallationStrategy(): McpInstallationStrategy
       {
           return McpInstallationStrategy::FILE;
       }
   
       public function mcpConfigPath(): string
       {
           return '.myagent.json';
       }
   
       // --- SupportsSkills ---
   
       public function skillsPath(): string
       {
           return '.myagent/skills';
       }
   }
   

   systemDetectionConfig() et projectDetectionConfig() sont utilisées par Boost pour détecter automatiquement l’agent au niveau système et projet. Lors de l’exécution de boost:install, l’agent correspondant sera automatiquement affiché comme candidat.

2. Enregistrer l'agent

   Enregistrez l’agent personnalisé dans la méthode boot de App\Providers\AppServiceProvider.

   <?php
   
   namespace App\Providers;
   
   use App\Boost\MyAgent;
   use Illuminate\Support\ServiceProvider;
   use Laravel\Boost\Boost;
   
   class AppServiceProvider extends ServiceProvider
   {
       public function boot(): void
       {
           Boost::registerAgent('my_agent', MyAgent::class);
       }
   }
   

   Après enregistrement, lancer php artisan boost:install fait apparaître MyAgent parmi les choix.

3. Vérifier le fonctionnement

   php artisan boost:install
   

   Sur l’écran de sélection des agents à installer, MyAgent apparaîtra. En le sélectionnant, MYAGENT.md, .myagent.json et .myagent/skills/ seront générés.

​

Personnalisation des guidelines

​

Configuration de guidelinesPath

L’emplacement de lecture des guidelines varie selon l’agent.

// Cas d'une sortie en fichier unique
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}

Permettre l’écrasement depuis un fichier de configuration augmente la flexibilité.

public function guidelinesPath(): string
{
    return config('boost.agents.my_agent.guidelines_path', 'MYAGENT.md');
}

​

Agents nécessitant un frontmatter

Pour les formats qui nécessitent un frontmatter, comme les .cursor/rules/*.mdc de Cursor, faites retourner true par frontmatter().

public function frontmatter(): bool
{
    return true;
}

​

Post-traitement des guidelines

Utilisez transformGuidelines() pour transformer le Markdown après génération.

public function transformGuidelines(string $markdown): string
{
    // Ajouter un en-tête spécifique à l'agent
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}

​

Ajout de guidelines d’IA personnalisées

Pour ajouter des règles spécifiques au projet dans les guidelines Boost, placez des fichiers Blade dans le répertoire .ai/guidelines/.

.ai/
└── guidelines/
    ├── my-domain-rules.blade.php
    └── coding-standards.blade.php

Exemple de fichier :

## Règles spécifiques au projet

Dans ce projet, respectez les conventions suivantes :

- Placer les modèles obligatoirement dans le namespace `App\Models\`
- Créer tous les endpoints API sous `App\Http\Controllers\Api\`
- Encapsuler les transactions BDD avec `DB::transaction()` à l'intérieur de la classe de service

@verbatim
<code-snippet name="Exemple de transaction dans une classe de service" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim

Lors de l’exécution de boost:install, ces guidelines sont automatiquement combinées avec les guidelines intégrées de Boost et produites en sortie.

​

Surcharger les guidelines intégrées

Si vous placez un fichier personnalisé au même chemin qu’une guideline intégrée de Boost, votre fichier a priorité.

# Surcharger "Inertia React v2 Form Guidance" de Boost
.ai/guidelines/inertia-react/2/forms.blade.php

​

Ajout de skills personnalisés

​

Création de SKILL.md

Définissez la skill dans .ai/skills/{nom-de-la-skill}/SKILL.md.

.ai/
└── skills/
    └── creating-invoices/
        └── SKILL.md

SKILL.md est composé d’un frontmatter YAML et d’instructions en Markdown.

---
name: creating-invoices
description: Skill utilisée pour implémenter la création, la mise à jour et l'envoi des factures (Invoice).
---

# Skill de création de factures

## Quand utiliser cette skill

À utiliser lors de l'implémentation du modèle de facture, de la génération PDF de la facture et de l'envoi par e-mail.

## Structure des fichiers

- `app/Models/Invoice.php` — Modèle de facture
- `app/Services/InvoiceService.php` — Logique métier
- `app/Jobs/SendInvoiceEmail.php` — Job d'envoi d'e-mail

## Patterns d'implémentation

### Création d'une facture

```php
// $items est un tableau passé depuis le contrôleur ou un autre service
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);

​

Génération PDF de la facture

Le PDF est généré avec barryvdh/laravel-dompdf :

use Barryvdh\DomPDF\Facade\Pdf;
use Illuminate\Support\Facades\Storage;

$pdf = Pdf::loadView('invoices.pdf', ['invoice' => $invoice]);
Storage::put("invoices/{$invoice->id}.pdf", $pdf->output());

Les skills sont conçues pour être « chargées uniquement quand nécessaire ». En séparant les informations toujours utiles dans les guidelines et les patterns détaillés propres à une tâche dans les skills, vous optimisez la consommation de contexte de l’IA.

​

Surcharger les skills intégrées

Créer une skill personnalisée du même nom qu’une skill intégrée de Boost écrase cette dernière.

# Personnaliser la skill livewire-development
.ai/skills/livewire-development/SKILL.md

​

Ajouter le support Boost à un package tiers

Pour ajouter la prise en charge de Boost à votre propre package, placez les fichiers de configuration dans le répertoire resources/boost/ du package.

​

Ajouter des guidelines

resources/
└── boost/
    └── guidelines/
        └── core.blade.php

## MyPackage

Ce package fournit [aperçu des fonctionnalités].

### Utilisation de base

@verbatim
<code-snippet name="Initialisation de MyPackage" lang="php">
$result = MyPackage::create([
    'option' => 'value',
]);
</code-snippet>
@endverbatim

​

Ajouter des skills

resources/
└── boost/
    └── skills/
        └── mypackage-development/
            └── SKILL.md

---
name: mypackage-development
description: Skill pour implémenter les fonctionnalités de MyPackage.
---

# MyPackage Development

## Quand utiliser cette skill
À utiliser lors de l'implémentation de fonctionnalités utilisant MyPackage.

## Fonctionnalités principales

- Fonctionnalité 1 : ...
- Fonctionnalité 2 : ...

Lorsqu’un utilisateur du package exécute php artisan boost:install, ces guidelines et skills sont automatiquement détectées et affichées comme cibles d’installation.

​

Exemple pratique : agent personnalisé pour un pipeline CI/CD propre

Voici l’implémentation complète d’un agent virtuel « PipelineAgent » intégré dans un pipeline CI/CD interne. Cet agent ne prend en charge que les guidelines, pas le MCP ni les skills.

<?php

declare(strict_types=1);

namespace App\Boost;

use Laravel\Boost\Contracts\SupportsGuidelines;
use Laravel\Boost\Install\Agents\Agent;
use Laravel\Boost\Install\Enums\Platform;

class PipelineAgent extends Agent implements SupportsGuidelines
{
    public function name(): string
    {
        return 'pipeline_agent';
    }

    public function displayName(): string
    {
        return 'Pipeline Agent (CI/CD)';
    }

    public function systemDetectionConfig(Platform $platform): array
    {
        // Détecter la présence via une variable d'environnement CI
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // Détecter via un fichier de configuration à la racine du projet
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // Chemin des conventions lu par l'agent CI/CD
        return '.pipeline/CODING_GUIDELINES.md';
    }

    public function frontmatter(): bool
    {
        return false;
    }

    public function transformGuidelines(string $markdown): string
    {
        // Ajouter un en-tête de métadonnées pour le pipeline
        $timestamp = now()->toIso8601String();

        return "<!-- Generated by Laravel Boost at {$timestamp} -->\n\n{$markdown}";
    }
}

Enregistrer dans AppServiceProvider :

use App\Boost\PipelineAgent;
use Laravel\Boost\Boost;

public function boot(): void
{
    Boost::registerAgent('pipeline_agent', PipelineAgent::class);
}

En environnement CI, vous pouvez générer uniquement les guidelines avec la commande suivante :

php artisan boost:install --agent=pipeline_agent

​

Liens de référence

ClaudeCode.php — exemple officiel

Vous pouvez consulter le code source complet de l’agent ClaudeCode fourni avec Boost.

Agent Skills

Consultez les spécifications du format SKILL.md et les bonnes pratiques.

Laravel Boost Custom Agent for GitHub Copilot CLI

Exemple de package publié compatible à la fois avec Copilot CLI et Testbench

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

Exemple de package publié pour le plugin GitHub Copilot de PhpStorm