> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Benutzerdefinierte Agenten

> Beschreibt, wie Sie über customAgents in SessionConfig zweckgebundene Sub-Agenten definieren.

## 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](/de/packages/laravel-copilot-sdk/fleet-mode).

## Grundlegende Verwendung

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
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

## Referenzen

* [SessionConfig](/de/packages/laravel-copilot-sdk/session-config)
* [SessionEvent](/de/packages/laravel-copilot-sdk/session-event)
* [Fleet Mode](/de/packages/laravel-copilot-sdk/fleet-mode)
* [MCP](/de/packages/laravel-copilot-sdk/mcp)
* [Tools](/de/packages/laravel-copilot-sdk/tools)


## Related topics

- [Fleet Mode](/de/packages/laravel-copilot-sdk/fleet-mode.md)
- [Plugin Directories](/de/packages/laravel-copilot-sdk/plugin-directories.md)
- [Benutzerdefinierte Provider](/de/packages/laravel-copilot-sdk/custom-providers.md)
- [Einen eigenen Agenten für Boost erstellen](/de/advanced/boost-custom-agent.md)
- [Laravel AI SDK](/de/ai-sdk.md)