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

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.

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