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.

Uso di base

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.

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
`hooks`	`array<string, array<array<string, mixed>>>`		Azioni hook dichiarative attive solo all’interno dell’agente

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

Hook dichiarativi per agente

In hooks di un agente personalizzato puoi specificare il nome dell’evento come chiave e un array di azioni dichiarative come valore. Le azioni vengono passate alla CLI insieme alla definizione dell’agente corrispondente e sono attive solo per quell’agente. Usalo, ad esempio, quando vuoi limitare l’esecuzione degli strumenti solo per un agente specifico.

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'restricted-agent',
            'prompt' => 'Review tool usage.',
            'hooks' => [
                'preToolUse' => [
                    ['permissionDecision' => 'deny'],
                ],
            ],
        ],
    ],
);

customAgents[*].hooks sono azioni dichiarative passate alla CLI. Specifica il contenuto delle azioni nel formato accettato da Copilot CLI.

Il hooks di primo livello di SessionConfig è una funzionalità distinta che registra callback PHP e si applica all’intera sessione. Per i dettagli consulta Hook di sessione.
Il caricamento degli hook basati su file da .github/hooks/ è controllato separatamente con enableFileHooks.

Selezionare un agente specifico all’avvio della sessione

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

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.

$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.

$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().

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

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kit

Feed e RSS

Middleware

Agenti personalizzati