Custom agents

Door custom agents te definiëren, maak je een opzet met subagents die elk hun eigen rol per taak hebben.
In de Laravel-versie configureer je dit met customAgents in SessionConfig. Zie Fleet Mode voor orkestratie waarbij meerdere subagents parallel draaien.

Basisgebruik

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'Onderzoek het authenticatieontwerp en stel verbeteringen voor');

    dump($response->content());
}, config: new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'displayName' => 'Research Agent',
            'description' => 'Onderzoekt de codebase en vat de belangrijkste punten samen',
            'tools' => ['grep', 'glob', 'view'],
            'prompt' => 'You are a research assistant. Analyze code and summarize findings.',
        ],
        [
            'name' => 'editor',
            'displayName' => 'Editor Agent',
            'description' => 'Voert minimale codewijzigingen door',
            'tools' => ['view', 'edit', 'bash'],
            'prompt' => 'You are a code editor. Make minimal, surgical changes only.',
        ],
    ],
));

Je kunt het ook in arrayvorm opgeven.

Copilot::run(
    prompt: 'Verbeter de README',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => 'Verantwoordelijk voor het schrijven van documentatie',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);

Configuratieopties

Property	Type	Verplicht	Beschrijving
`name`	`string`	✅	De identifier van de agent
`displayName`	`string`		Weergavenaam
`description`	`string`		Beschrijving die de runtime gebruikt om de delegatiebestemming te kiezen
`tools`	`?array`		Beschikbare tools. Bij `null` of weglaten is alles beschikbaar
`prompt`	`string`	✅	De agent-specifieke system prompt
`mcpServers`	`array`		MCP-serverconfiguratie exclusief voor deze agent
`infer`	`bool`		Of de agent in aanmerking komt voor automatische selectie (standaard: `true`)
`skills`	`array`		Lijst met skillnamen die bij het starten worden geladen
`hooks`	`array<string, array<array<string, mixed>>>`		Declaratieve hook-acties die alleen binnen deze agent gelden

Hoe concreter je de description schrijft, hoe nauwkeuriger de automatische selectie wordt.

Declaratieve hooks per agent

In hooks van een custom agent geef je eventnamen op als sleutels en arrays met declaratieve acties als waarden. De acties worden samen met de definitie van de betreffende agent aan de CLI doorgegeven en gelden alleen voor die agent. Gebruik dit bijvoorbeeld als je de uitvoering van tools alleen voor een specifieke agent wilt beperken.

use Revolution\Copilot\Types\SessionConfig;

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

customAgents[*].hooks zijn declaratieve acties die aan de CLI worden doorgegeven. Geef de inhoud van de acties op in het formaat dat de Copilot CLI accepteert.

De top-level hooks van SessionConfig is een aparte functie die PHP-callbacks registreert en voor de hele session geldt. Zie Session hooks voor details.
Het laden van file-based hooks uit .github/hooks/ regel je afzonderlijk met enableFileHooks.

Een specifieke agent kiezen bij de start van een sessie

Met agent activeer je vanaf de eerste turn een specifieke custom agent.

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',
);

Automatische selectie uitschakelen (`infer: false`)

Voor agents die risicovolle bewerkingen uitvoeren, is het veiliger om de automatische selectie uit te schakelen en ze alleen expliciet te gebruiken.

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'dangerous-cleanup',
            'description' => 'Verwijdert onnodige bestanden',
            'tools' => ['bash', 'edit', 'view'],
            'prompt' => 'Remove dead code and unused files carefully.',
            'infer' => false,
        ],
    ],
);

Tools verbergen voor de standaardagent

Met defaultAgent.excludedTools verberg je specifieke tools alleen voor de hoofdagent.
Zo delegeer je makkelijker naar een custom agent die die tool wel mag gebruiken.

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

Subagent-events monitoren

Tijdens de uitvoering van subagents stromen er subagent.*-events binnen.
Je kunt ze monitoren met onEvent of $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: 'Onderzoek de authenticatie-implementatie in deze repository');
});

Best practices

Scheid een researcher (voornamelijk lezen) en een editor (verantwoordelijk voor wijzigingen)
Houd tools zo minimaal mogelijk en beperk de rechten
Schrijf een concrete description om de precisie van automatische delegatie te verhogen
Vang subagent.failed op en zorg voor een retry- of fallbackstrategie

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kits

Feeds en RSS

Middleware

Custom agents

Custom agents

Basisgebruik

Configuratieopties

Declaratieve hooks per agent

Een specifieke agent kiezen bij de start van een sessie

Automatische selectie uitschakelen (`infer: false`)

Tools verbergen voor de standaardagent

Subagent-events monitoren

Best practices

Referenties

​Custom agents

​Basisgebruik

​Configuratieopties

​Declaratieve hooks per agent

​Een specifieke agent kiezen bij de start van een sessie

​Automatische selectie uitschakelen (infer: false)

​Tools verbergen voor de standaardagent

​Subagent-events monitoren

​Best practices

​Referenties

Custom agents

Basisgebruik

Configuratieopties

Declaratieve hooks per agent

Een specifieke agent kiezen bij de start van een sessie

Automatische selectie uitschakelen (`infer: false`)

Tools verbergen voor de standaardagent

Subagent-events monitoren

Best practices

Referenties