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

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

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