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

# Agenti personalizzati

> Descrive come definire sotto-agenti specifici per uso tramite customAgents di SessionConfig.

## Agenti personalizzati

Definendo agenti personalizzati puoi creare configurazioni di sotto-agenti con ruoli distinti in base all'uso.
Nella versione Laravel li configuri tramite `customAgents` di `SessionConfig`.

Per l'orchestrazione che esegue più sotto-agenti in parallelo, consulta [Fleet Mode](/it/packages/laravel-copilot-sdk/fleet-mode).

## Uso di base

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'Analizza il design dell\'autenticazione e proponi miglioramenti');

    dump($response->content());
}, config: new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'displayName' => 'Research Agent',
            'description' => 'Analizza il codice e organizza i punti chiave',
            'tools' => ['grep', 'glob', 'view'],
            'prompt' => 'You are a research assistant. Analyze code and summarize findings.',
        ],
        [
            'name' => 'editor',
            'displayName' => 'Editor Agent',
            'description' => 'Effettua modifiche minime al codice',
            'tools' => ['view', 'edit', 'bash'],
            'prompt' => 'You are a code editor. Make minimal, surgical changes only.',
        ],
    ],
));
```

Puoi specificare la stessa configurazione anche in forma di array.

```php theme={null}
Copilot::run(
    prompt: 'Migliora il README',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => 'Si occupa della scrittura della documentazione',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);
```

## Opzioni di configurazione

| Proprietà     | Tipo     | Obbligatorio | Descrizione                                                   |
| ------------- | -------- | ------------ | ------------------------------------------------------------- |
| `name`        | `string` | ✅            | Identificatore dell'agente                                    |
| `displayName` | `string` |              | Nome visualizzato                                             |
| `description` | `string` |              | Descrizione usata dal runtime per scegliere a chi delegare    |
| `tools`       | `?array` |              | Strumenti utilizzabili. Se `null` / omesso, tutti disponibili |
| `prompt`      | `string` | ✅            | System prompt dedicato all'agente                             |
| `mcpServers`  | `array`  |              | Configurazione MCP server dedicata a questo agente            |
| `infer`       | `bool`   |              | Se includere nella selezione automatica (default: `true`)     |
| `skills`      | `array`  |              | Lista di skill da caricare all'avvio                          |

> Più `description` è specifica, più migliora la precisione della selezione automatica.

## Selezionare un agente specifico all'avvio della sessione

Specificando `agent` puoi abilitare fin dal primo turn uno specifico agente personalizzato.

```php theme={null}
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'prompt' => 'You analyze code and answer questions.',
        ],
        [
            'name' => 'editor',
            'prompt' => 'You edit code with minimal changes.',
        ],
    ],
    agent: 'researcher',
);
```

## Disabilitare la selezione automatica (`infer: false`)

Per gli agenti che eseguono operazioni ad alto rischio, è più sicuro disabilitare la selezione automatica e usarli in modo esplicito.

```php theme={null}
$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'dangerous-cleanup',
            'description' => 'Rimuove file non necessari',
            'tools' => ['bash', 'edit', 'view'],
            'prompt' => 'Remove dead code and unused files carefully.',
            'infer' => false,
        ],
    ],
);
```

## Nascondere strumenti all'agente predefinito

Con `defaultAgent.excludedTools` puoi nascondere strumenti specifici solo all'agente principale.
Diventa più facile delegare all'agente personalizzato che può usare quello strumento.

```php theme={null}
$config = new SessionConfig(
    tools: [...],
    defaultAgent: [
        'excludedTools' => ['analyze-codebase'],
    ],
    customAgents: [
        [
            'name' => 'researcher',
            'tools' => ['analyze-codebase'],
            'prompt' => 'You perform deep codebase analysis.',
        ],
    ],
);
```

## Monitorare eventi dei sotto-agenti

Durante l'esecuzione dei sotto-agenti fluiscono eventi `subagent.*`.
Puoi monitorarli con `onEvent` o `$session->on()`.

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session) {
    $session->on(function (SessionEvent $event): void {
        if ($event->is(SessionEventType::SUBAGENT_STARTED)) {
            info('Sub-agent started', $event->toArray());
        }

        if ($event->is(SessionEventType::SUBAGENT_COMPLETED)) {
            info('Sub-agent completed', $event->toArray());
        }

        if ($event->is(SessionEventType::SUBAGENT_FAILED)) {
            info('Sub-agent failed', $event->toArray());
        }
    });

    $session->sendAndWait(prompt: 'Analizza l\'implementazione dell\'autenticazione di questo repository');
});
```

## Best practice

* Separa `researcher` (principalmente lettura) ed `editor` (responsabile delle modifiche)
* Riduci `tools` al minimo necessario e restringi i permessi
* Scrivi `description` in modo concreto per migliorare la precisione della delega automatica
* Cattura `subagent.failed` e predisponi strategie di retry o fallback

## Riferimenti

* [SessionConfig](/it/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/it/packages/laravel-copilot-sdk/session-event)
* [Fleet Mode](/it/packages/laravel-copilot-sdk/fleet-mode)
* [MCP](/it/packages/laravel-copilot-sdk/mcp)
* [Tools](/it/packages/laravel-copilot-sdk/tools)


## Related topics

- [Plugin Directories](/it/packages/laravel-copilot-sdk/plugin-directories.md)
- [Fleet Mode](/it/packages/laravel-copilot-sdk/fleet-mode.md)
- [Provider personalizzati](/it/packages/laravel-copilot-sdk/custom-providers.md)
- [Cast personalizzati di Eloquent](/it/advanced/eloquent-casts.md)
- [Pacchetto core e driver personalizzati - Feedable](/it/packages/feedable/core.md)