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

# Creare un agente personalizzato per Boost

> Approfondisci l'architettura di estensione di Laravel Boost e crea un agente personalizzato implementando i contract SupportsGuidelines, SupportsMcp e SupportsSkills.

## Perché serve un agente personalizzato

Laravel Boost supporta di default i principali strumenti di AI coding come Claude Code, Cursor, Codex, GitHub Copilot (VS Code). Per adattarsi a strumenti interni, agenti AI emergenti o flussi di lavoro proprietari, però, devi implementare un agente personalizzato tramite l'estensione di Boost.

Casi in cui un agente custom è utile:

* Stai usando un IDE o uno strumento AI non supportato da Boost
* Vuoi integrare Boost in un flusso di sviluppo interno o in una pipeline CI/CD proprietaria
* L'agente richiede un formato di file di configurazione o una procedura di installazione specifica

## Architettura di estensione di Boost

### Classe base Agent

Tutti gli agenti estendono `Laravel\Boost\Install\Agents\Agent`. Questa classe astratta fornisce:

* Rilevamento dell'agente (a livello di sistema e di progetto)
* Installazione di server MCP (file-based e shell-command-based)
* Hook di trasformazione delle linee guida (`transformGuidelines`)

Ci sono due metodi astratti obbligatori.

| Metodo                                      | Descrizione                                                            |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| `name()`                                    | Identificatore interno dell'agente (es. `claude_code`)                 |
| `displayName()`                             | Nome mostrato in fase di installazione (es. `Claude Code`)             |
| `systemDetectionConfig(Platform $platform)` | Configurazione di rilevamento dell'installazione a livello di sistema  |
| `projectDetectionConfig()`                  | Configurazione di rilevamento dell'installazione a livello di progetto |

### I tre contract

Per abilitare selettivamente le funzionalità di Boost, implementi i contract che servono.

| Contract             | Ruolo                                                           |
| -------------------- | --------------------------------------------------------------- |
| `SupportsGuidelines` | Path in cui scrivere il file di linee guida AI e trasformazione |
| `SupportsMcp`        | Installazione della configurazione di server MCP                |
| `SupportsSkills`     | Path di installazione degli Agent Skills                        |

<Info>
  Tutti e tre i contract sono opzionali. Puoi implementare solo le linee guida senza MCP, ad esempio.
</Info>

### Contract SupportsGuidelines

```php theme={null}
interface SupportsGuidelines
{
    // path del file in cui scrivere le linee guida AI
    public function guidelinesPath(): string;

    // se il file richiede un frontmatter
    public function frontmatter(): bool;

    // post-elaborazione del Markdown generato
    public function transformGuidelines(string $markdown): string;
}
```

`guidelinesPath()` restituisce il path del file in cui scrivere le linee guida generate. Per Claude Code è `CLAUDE.md`, per Cursor `.cursor/rules/laravel-boost.mdc`, adattandosi al formato che l'agente carica.

`transformGuidelines()` è un hook per elaborare il Markdown dopo la generazione. Puoi aggiungere un header specifico dell'agente o convertirlo in un formato speciale. Il default nella classe base restituisce la stringa così com'è.

### Contract SupportsMcp

```php theme={null}
interface SupportsMcp
{
    // se usare path assoluti nei comandi MCP
    public function useAbsolutePathForMcp(): bool;

    // restituisce il path dell'eseguibile PHP
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // restituisce il path di artisan
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // installa la configurazione del server MCP
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // installa la configurazione del server MCP tramite HTTP
    public function installHttpMcp(string $key, string $url): bool;
}
```

La classe base `Agent` ha già implementazioni di default per `installMcp()` e `installHttpMcp()`: nella maggior parte dei casi basta fare override di `mcpInstallationStrategy()` e `mcpConfigPath()`.

Ci sono due strategie di installazione.

| `McpInstallationStrategy` | Comportamento                                           |
| ------------------------- | ------------------------------------------------------- |
| `FILE`                    | Scrive la configurazione in un file JSON/TOML (default) |
| `SHELL`                   | Esegue un comando shell per registrare l'MCP            |
| `NONE`                    | Salta l'installazione MCP                               |

### Contract SupportsSkills

```php theme={null}
interface SupportsSkills
{
    // path della directory in cui scrivere gli Agent Skills
    public function skillsPath(): string;
}
```

Restituisce il path della directory di skills letta dall'agente. Per Claude Code è `.claude/skills`, per Cursor `.cursor/skills`, e così via.

## Creare un agente personalizzato

Implementiamo concretamente una classe di agente custom. Come esempio, un ipotetico "MyAgent" integrato in un flusso CI/CD proprietario.

<Steps>
  <Step title="Creare la classe dell'agente">
    Crea `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() usa il default della classe base Agent (false)
        // anche transformGuidelines() usa il default (restituisce la stringa)

        // --- SupportsMcp ---

        // useAbsolutePathForMcp(), getPhpPath(), getArtisanPath(),
        // installMcp(), installHttpMcp() sono già implementati nella classe base

        public function mcpInstallationStrategy(): McpInstallationStrategy
        {
            return McpInstallationStrategy::FILE;
        }

        public function mcpConfigPath(): string
        {
            return '.myagent.json';
        }

        // --- SupportsSkills ---

        public function skillsPath(): string
        {
            return '.myagent/skills';
        }
    }
    ```

    <Info>
      `systemDetectionConfig()` e `projectDetectionConfig()` servono a Boost per rilevare automaticamente l'agente a livello di sistema e di progetto. All'esecuzione di `boost:install` l'agente compare fra i candidati.
    </Info>
  </Step>

  <Step title="Registrare l'agente">
    Nel metodo `boot` di `App\Providers\AppServiceProvider` registri l'agente custom.

    ```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);
        }
    }
    ```

    Dopo la registrazione, con `php artisan boost:install` MyAgent compare tra le scelte.
  </Step>

  <Step title="Verifica del funzionamento">
    ```shell theme={null}
    php artisan boost:install
    ```

    Nella schermata di selezione dell'agente MyAgent viene mostrato. Selezionandolo vengono generati `MYAGENT.md`, `.myagent.json` e `.myagent/skills/`.
  </Step>
</Steps>

## Personalizzare le linee guida

### Impostare guidelinesPath

Ogni agente carica il file delle linee guida da un punto diverso.

```php theme={null}
// per generare un unico file
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}
```

Renderlo sovrascrivibile da file di configurazione aumenta la flessibilità.

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

### Agenti che richiedono frontmatter

Per formati che richiedono un frontmatter (come i `.cursor/rules/*.mdc` di Cursor) restituisci `true` da `frontmatter()`.

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

### Post-elaborazione delle linee guida

Con `transformGuidelines()` puoi elaborare il Markdown dopo la generazione.

```php theme={null}
public function transformGuidelines(string $markdown): string
{
    // aggiunge un header specifico dell'agente
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}
```

## Aggiungere linee guida AI personalizzate

Per aggiungere regole specifiche del progetto alle linee guida di Boost, metti file Blade nella directory `.ai/guidelines/`.

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

Esempio di file:

```php theme={null}
## Regole specifiche del progetto

In questo progetto segui queste convenzioni:

- Colloca sempre i modelli nel namespace `App\Models\`
- Crea tutti gli endpoint API sotto `App\Http\Controllers\Api\`
- Racchiudi le transazioni DB con `DB::transaction()` all'interno delle service class

@verbatim
<code-snippet name="Esempio di transazione in una service class" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim
```

Eseguendo `boost:install` queste linee guida vengono unite automaticamente a quelle integrate in Boost.

### Override delle linee guida integrate

Se metti un file personalizzato nello stesso path di una linea guida integrata di Boost, la tua ha la priorità.

```
# override della "Inertia React v2 Form Guidance" di Boost
.ai/guidelines/inertia-react/2/forms.blade.php
```

## Aggiungere skills personalizzati

### Creare SKILL.md

Definisci le skill in `.ai/skills/{nome-skill}/SKILL.md`.

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

`SKILL.md` è composto da un frontmatter YAML e da istruzioni Markdown.

````markdown theme={null}
---
name: creating-invoices
description: Skill da usare quando implementi la creazione, l'aggiornamento e l'invio di fatture (Invoice).
---

# Skill di creazione fatture

## Quando usare questa skill

Quando implementi il modello Invoice, la generazione PDF e l'invio email di una fattura.

## Struttura dei file

- `app/Models/Invoice.php` — modello Invoice
- `app/Services/InvoiceService.php` — logica di business
- `app/Jobs/SendInvoiceEmail.php` — job di invio email

## Pattern di implementazione

### Creare una fattura

```php
// $items è l'array passato dal controller o da un altro service
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);
````

### Generare il PDF della fattura

Genera il PDF con `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>
  Le skill sono progettate per essere "caricate solo quando servono". Metti in linee guida le informazioni sempre necessarie e nelle skill i pattern dettagliati specifici del task: ottimizzi l'uso della context dell'AI.
</Tip>

### Override delle skill integrate

Creando una skill custom con lo stesso nome di una skill integrata di Boost, la sovrascrivi.

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

## Aggiungere il supporto Boost a pacchetti di terze parti

Per aggiungere il supporto Boost al tuo pacchetto, metti i file di configurazione nella directory `resources/boost/` del pacchetto.

### Aggiungere linee guida

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

```php theme={null}
## MyPackage

Questo pacchetto fornisce [panoramica delle funzionalità].

### Uso di base

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

### Aggiungere skill

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

```markdown theme={null}
---
name: mypackage-development
description: Skill per implementare funzionalità con MyPackage.
---

# MyPackage Development

## Quando usare questa skill
Quando implementi funzionalità che usano MyPackage.

## Funzionalità principali

- Funzionalità 1: ...
- Funzionalità 2: ...
```

Quando gli utenti del pacchetto eseguono `php artisan boost:install`, queste linee guida e skill vengono rilevate automaticamente e proposte per l'installazione.

## Esempio pratico: agente custom per pipeline CI/CD

Esempio completo di "PipelineAgent", un agente virtuale integrato in una pipeline CI/CD interna. L'agente supporta solo le linee guida, non MCP e non skill.

```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
    {
        // rileva la presenza tramite variabili d'ambiente di CI
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // rileva tramite un file di configurazione nella root del progetto
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // path delle regole che l'agente CI/CD legge
        return '.pipeline/CODING_GUIDELINES.md';
    }

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

    public function transformGuidelines(string $markdown): string
    {
        // aggiunge un header di metadati per la pipeline
        $timestamp = now()->toIso8601String();

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

Registrazione in `AppServiceProvider`:

```php theme={null}
use App\Boost\PipelineAgent;
use Laravel\Boost\Boost;

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

In ambiente CI puoi generare solo le linee guida con:

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

## Link di riferimento

<Card title="ClaudeCode.php — esempio ufficiale" icon="github" href="https://github.com/laravel/boost/blob/main/src/Install/Agents/ClaudeCode.php">
  Codice sorgente completo dell'agente ClaudeCode incluso in Boost.
</Card>

<Card title="Agent Skills" icon="book" href="https://agentskills.io/what-are-skills">
  Specifica del formato SKILL.md e best practice.
</Card>

<Card title="Laravel Boost Custom Agent for GitHub Copilot CLI" icon="github" href="/it/packages/laravel-boost-copilot-cli">
  Esempio di pacchetto pubblicato che supporta sia Copilot CLI sia Testbench.
</Card>

<Card title="Laravel Boost Custom Agent for PhpStorm with GitHub Copilot" icon="github" href="/it/packages/laravel-boost-phpstorm-copilot">
  Esempio di pacchetto pubblicato per il plugin GitHub Copilot di PhpStorm.
</Card>


## Related topics

- [Creare un provider personalizzato per l'AI SDK](/it/advanced/ai-sdk-custom-provider.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/it/packages/laravel-boost-copilot-cli.md)
- [Laravel Boost](/it/boost.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/it/packages/laravel-boost-phpstorm-copilot.md)
- [Implementare un guard di autenticazione personalizzato](/it/advanced/custom-auth-guard.md)