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

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

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