Agents personnalisés

Définir des agents personnalisés permet de mettre en place des configurations de sous-agents aux rôles distincts. Dans la version Laravel, cela se configure via customAgents dans SessionConfig. Pour orchestrer plusieurs sous-agents en parallèle, voir Fleet Mode.

Utilisation de 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: '認証周りの設計を調査して改善案を提案して');

    dump($response->content());
}, config: new SessionConfig(
    customAgents: [
        [
            'name' => 'researcher',
            'displayName' => 'Research Agent',
            'description' => 'Enquête sur le code et en synthétise les points clés',
            'tools' => ['grep', 'glob', 'view'],
            'prompt' => 'You are a research assistant. Analyze code and summarize findings.',
        ],
        [
            'name' => 'editor',
            'displayName' => 'Editor Agent',
            'description' => 'Effectue des modifications de code minimales',
            'tools' => ['view', 'edit', 'bash'],
            'prompt' => 'You are a code editor. Make minimal, surgical changes only.',
        ],
    ],
));

Vous pouvez aussi spécifier ceci sous forme de tableau.

Copilot::run(
    prompt: 'READMEを改善して',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => 'Prend en charge la rédaction de la documentation',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);

Paramètres

Propriété	Type	Requis	Description
`name`	`string`	✅	Identifiant de l’agent
`displayName`	`string`		Nom d’affichage
`description`	`string`		Description utilisée par le runtime pour choisir vers qui déléguer
`tools`	`?array`		Outils utilisables. Si `null` ou omis, tout est disponible
`prompt`	`string`	✅	Prompt système propre à l’agent
`mcpServers`	`array`		Configuration de serveurs MCP propres à cet agent
`infer`	`bool`		L’agent est-il candidat à la sélection automatique (par défaut : `true`)
`skills`	`array`		Liste des skills à charger au démarrage
`hooks`	`array<string, array<array<string, mixed>>>`		Actions de hook déclaratives actives uniquement dans l’agent

Plus la description est précise, plus la sélection automatique est fiable.

Hooks déclaratifs par agent

Dans hooks d’un agent personnalisé, vous pouvez indiquer des noms d’événements comme clés et des tableaux d’actions déclaratives comme valeurs. Les actions sont transmises au CLI avec la définition de l’agent concerné et ne sont actives que pour cet agent. C’est utile par exemple pour restreindre l’exécution d’outils pour un agent spécifique uniquement.

use Revolution\Copilot\Types\SessionConfig;

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

customAgents[*].hooks sont des actions déclaratives transmises au CLI. Indiquez le contenu des actions dans le format accepté par Copilot CLI.

Les hooks au niveau supérieur de SessionConfig constituent une fonctionnalité distincte qui enregistre des callbacks PHP et s’applique à toute la session. Pour plus de détails, consultez Hooks de session.
Le chargement des hooks basés sur des fichiers dans .github/hooks/ se contrôle séparément avec enableFileHooks.

Choisir un agent spécifique au démarrage de la session

En spécifiant agent, vous activez dès le premier tour un agent personnalisé donné.

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

Désactiver la sélection automatique (`infer: false`)

Pour les agents effectuant des opérations à risque, il est plus sûr de désactiver la sélection automatique et de les invoquer explicitement.

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

Masquer des outils à l’agent par défaut

defaultAgent.excludedTools permet de masquer certains outils uniquement à l’agent principal. Cela facilite la délégation vers un agent personnalisé disposant de ces outils.

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

Observer les événements des sous-agents

Pendant l’exécution d’un sous-agent, des événements subagent.* sont émis. Vous pouvez les observer via onEvent ou $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: 'このリポジトリの認証実装を調べて');
});

Bonnes pratiques

Séparez un researcher (principalement en lecture) d’un editor (chargé des modifications)
Restreignez tools au strict nécessaire pour limiter les permissions
Rédigez une description précise pour améliorer la délégation automatique
Interceptez subagent.failed pour prévoir un retry ou un fallback

GitHub Copilot

SDK

AI SDK

VOICEVOX

Kits de démarrage

Flux et RSS

Middleware

Agents personnalisés