Benutzerdefinierte Agenten

Wenn Sie benutzerdefinierte Agenten definieren, können Sie eine Sub-Agenten-Struktur mit jeweils spezifischen Rollen aufbauen. In der Laravel-Version erfolgt die Konfiguration über customAgents in SessionConfig. Für die Orchestrierung mehrerer parallel laufender Sub-Agenten siehe Fleet Mode.

Grundlegende Verwendung

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' => 'コードを調査して要点を整理する',
            'tools' => ['grep', 'glob', 'view'],
            'prompt' => 'You are a research assistant. Analyze code and summarize findings.',
        ],
        [
            'name' => 'editor',
            'displayName' => 'Editor Agent',
            'description' => '必要最小限のコード変更を行う',
            'tools' => ['view', 'edit', 'bash'],
            'prompt' => 'You are a code editor. Make minimal, surgical changes only.',
        ],
    ],
));

Die Angabe im Array-Format ist ebenfalls möglich.

Copilot::run(
    prompt: 'READMEを改善して',
    config: [
        'customAgents' => [
            [
                'name' => 'docs-writer',
                'description' => 'ドキュメント執筆を担当する',
                'prompt' => 'Write clear technical documentation.',
            ],
        ],
    ],
);

Konfigurationsoptionen

Eigenschaft	Typ	Erforderlich	Beschreibung
`name`	`string`	✅	Bezeichner des Agenten
`displayName`	`string`		Anzeigename
`description`	`string`		Beschreibung, anhand derer die Runtime das Delegationsziel auswählt
`tools`	`?array`		Verfügbare Tools. Bei `null` / Weglassen sind alle verfügbar
`prompt`	`string`	✅	Agentenspezifischer System-Prompt
`mcpServers`	`array`		Agentenspezifische MCP-Server-Konfiguration
`infer`	`bool`		Ob der Agent für die automatische Auswahl in Frage kommt (Standard: `true`)
`skills`	`array`		Liste der beim Start zu ladenden Skill-Namen
`hooks`	`array<string, array<array<string, mixed>>>`		Deklarative Hook-Aktionen, die nur innerhalb des Agenten gelten

Je konkreter description formuliert ist, desto genauer wird die automatische Auswahl.

Deklarative Hooks pro Agent

In hooks eines benutzerdefinierten Agenten können Sie Eventnamen als Schlüssel und Arrays deklarativer Aktionen als Werte angeben. Die Aktionen werden zusammen mit der Definition des jeweiligen Agenten an die CLI übergeben und gelten nur für diesen Agenten. Das ist nützlich, wenn Sie etwa die Tool-Ausführung nur für einen bestimmten Agenten einschränken möchten.

use Revolution\Copilot\Types\SessionConfig;

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

customAgents[*].hooks sind deklarative Aktionen, die an die CLI übergeben werden. Geben Sie die Aktionen in dem Format an, das die Copilot CLI akzeptiert.

Das hooks auf oberster Ebene von SessionConfig ist eine separate Funktion zum Registrieren von PHP-Callbacks und gilt für die gesamte Session. Details finden Sie unter Session-Hooks.
Das Laden dateibasierter Hooks aus .github/hooks/ wird separat über enableFileHooks gesteuert.

Beim Sessionstart einen bestimmten Agenten wählen

Mit agent können Sie ab dem ersten Turn einen bestimmten benutzerdefinierten Agenten aktivieren.

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 Auswahl deaktivieren (`infer: false`)

Für Agenten, die risikobehaftete Operationen ausführen, ist es sicherer, die automatische Auswahl zu deaktivieren und sie explizit zu verwenden.

$config = new SessionConfig(
    customAgents: [
        [
            'name' => 'dangerous-cleanup',
            'description' => '不要ファイルを削除する',
            'tools' => ['bash', 'edit', 'view'],
            'prompt' => 'Remove dead code and unused files carefully.',
            'infer' => false,
        ],
    ],
);

Tools vom Standard-Agenten ausblenden

Mit defaultAgent.excludedTools können Sie bestimmte Tools nur vor dem Haupt-Agenten verbergen. Dadurch fällt die Delegation an einen benutzerdefinierten Agenten, der diese Tools nutzen darf, leichter.

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

Sub-Agenten-Ereignisse überwachen

Während der Ausführung von Sub-Agenten werden subagent.*-Ereignisse gesendet. Sie können sie über onEvent oder $session->on() überwachen.

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: 'このリポジトリの認証実装を調べて');
});

Best Practices

Trennen Sie researcher (lesegetrieben) und editor (Änderungen)
Halten Sie tools auf das Nötigste beschränkt und schränken Sie Rechte ein
Formulieren Sie description konkret, um die automatische Delegation zu verbessern
Fangen Sie subagent.failed ab und implementieren Sie Retry- oder Fallback-Strategien

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds und RSS

Middleware

Benutzerdefinierte Agenten