> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                           |

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

### Le contrat SupportsGuidelines

```php theme={null}
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

```php theme={null}
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

```php theme={null}
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.

<Steps>
  <Step title="Créer la classe d'agent">
    Créez `app/Boost/MyAgent.php`.

    ```php theme={null}
    <?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';
        }
    }
    ```

    <Info>
      `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.
    </Info>
  </Step>

  <Step title="Enregistrer l'agent">
    Enregistrez l'agent personnalisé dans la méthode `boot` de `App\Providers\AppServiceProvider`.

    ```php theme={null}
    <?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.
  </Step>

  <Step title="Vérifier le fonctionnement">
    ```shell theme={null}
    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.
  </Step>
</Steps>

## Personnalisation des guidelines

### Configuration de guidelinesPath

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

```php theme={null}
// 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é.

```php theme={null}
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()`.

```php theme={null}
public function frontmatter(): bool
{
    return true;
}
```

### Post-traitement des guidelines

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

```php theme={null}
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 :

```php theme={null}
## 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.

````markdown theme={null}
---
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` :

```php theme={null}
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());
```

<Tip>
  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.
</Tip>

### 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
```

```php theme={null}
## 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
```

```markdown theme={null}
---
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 theme={null}
<?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` :

```php theme={null}
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 :

```shell theme={null}
php artisan boost:install --agent=pipeline_agent
```

## Liens de référence

<Card title="ClaudeCode.php — exemple officiel" icon="github" href="https://github.com/laravel/boost/blob/main/src/Install/Agents/ClaudeCode.php">
  Vous pouvez consulter le code source complet de l'agent ClaudeCode fourni avec Boost.
</Card>

<Card title="Agent Skills" icon="book" href="https://agentskills.io/what-are-skills">
  Consultez les spécifications du format SKILL.md et les bonnes pratiques.
</Card>

<Card title="Laravel Boost Custom Agent for GitHub Copilot CLI" icon="github" href="/fr/packages/laravel-boost-copilot-cli">
  Exemple de package publié compatible à la fois avec Copilot CLI et Testbench
</Card>

<Card title="Laravel Boost Custom Agent for PhpStorm with GitHub Copilot" icon="github" href="/fr/packages/laravel-boost-phpstorm-copilot">
  Exemple de package publié pour le plugin GitHub Copilot de PhpStorm
</Card>


## Related topics

- [Créer un fournisseur personnalisé pour l'AI SDK](/fr/advanced/ai-sdk-custom-provider.md)
- [Agents personnalisés](/fr/packages/laravel-copilot-sdk/custom-agents.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/fr/packages/laravel-boost-copilot-cli.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/fr/packages/laravel-boost-phpstorm-copilot.md)
- [Implémenter un guard d'authentification personnalisé](/fr/advanced/custom-auth-guard.md)