Subagent-Verwaltung

Subagents sind spezialisierte KI-Agenten, die mit ihrem eigenen benutzerdefinierten System-Prompt, einem separaten Kontextfenster und einer isolierten Ausführungsumgebung arbeiten. Sie übernehmen bestimmte, vom Hauptagenten delegierte Aufgaben, ohne den Kontext der Hauptkonversation zu belasten.

Wesentliche Merkmale:

• Isolierte Kontextfenster: Jeder Subagent verwaltet sein eigenes separates Kontextfenster. Nur die von Subagents zurückgegebenen Endergebnisse belegen Platz im Kontext des Hauptagenten, nicht die Zwischenverarbeitung.
• Benutzerdefinierte System-Prompts: Jeder Subagent verfügt über einen eigenen System-Prompt, der sein Verhalten, seine Persönlichkeit und seinen Ansatz zur Aufgabeninterpretation definiert.
• Automatische Aufgabendelegation: Der Hauptagent ruft Subagents automatisch auf, wenn passende Aufgabentypen erkannt werden – ähnlich der automatischen Werkzeugauswahl.
• Manueller Aufruf: Nutzer können Subagents explizit über @-Erwähnungen referenzieren (@Verifier, @Explorer, @Code-reviewer).

Zwei Kategorien:

• Standard-Subagents: Integriert (Verifier, Explorer, Code-reviewer) – sofort verfügbar, vorkonfiguriert
• Benutzerdefinierte Subagents: Von Nutzern erstellt, gespeichert in ~/.verdent/subagents/ – auf projektspezifische Anforderungen zugeschnitten

Standard-Subagents verstehen

Verdent for VS Code enthält drei integrierte Standard-Subagents, die vorkonfiguriert und sofort verfügbar sind und keine Einrichtung oder Konfiguration erfordern.

@Verifier check this authentication logic

@Explorer find all API endpoints

@Code-reviewer review this authentication flow

Automatischer vs. manueller Aufruf

Auslöser für automatische Auswahl:

Der Hauptagent wählt Subagents automatisch basierend auf der Erkennung von Aufgabenmustern aus:

Explorer-Subagent:

• Fragen zur Struktur des Codebase ("Wie ist die Architektur aufgebaut?", "Wo ist X implementiert?")
• Anfragen zur Dateisuche ("Finde alle Dateien, die ...", "Zeig mir Komponenten im Zusammenhang mit ...")
• Anfragen zur Codenavigation ("Wie funktioniert die Authentifizierung?", "Was ruft diese Funktion auf?")

Code-reviewer-Subagent:

• Anfragen zur Sicherheitsprüfung ("Überprüfe Sicherheitslücken", "Prüfe auf SQL-Injection-Risiken")
• Prompts zur Bewertung der Codequalität ("Analysiere die Codequalität", "Identifiziere Wartbarkeitsprobleme")
• Szenarien für Reviews vor dem Commit (implizit, wenn Codeänderungen vorgelegt werden)

Verifier-Subagent:

• Validierungsanfragen ("Überprüfe diese Logik", "Prüfe, ob diese Implementierung korrekt ist")
• Syntax- und Korrektheitsprüfungen ("Funktioniert dieser Code?", "Validiere den Authentifizierungsablauf")

Manuelle Angabe:

Nutzer können das automatische Routing mit @-Erwähnungen überschreiben:

@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware

Schaltfläche „Subagent hinzufügen“: Wählen Sie die Schaltfläche Subagent hinzufügen im Eingabefeld, um:

• aus den verfügbaren Subagents (Standard und benutzerdefiniert) auszuwählen
• die Aufgabe explizit an den gewählten Subagenten zu delegieren
• automatische Routing-Entscheidungen zu überschreiben

Vorteile der manuellen Angabe:

• Präzision: Stellt sicher, dass genau der richtige Subagent die Aufgabe bearbeitet
• Überschreiben: Wählen Sie einen bestimmten Subagenten, wenn mehrere in Frage kommen
• Testen: Verhalten benutzerdefinierter Subagents explizit validieren
• Konsistenz: Aufgaben mit demselben Subagenten wiederholen, um konsistente Ergebnisse zu erhalten

Benutzerdefinierte Subagents erstellen

Mit benutzerdefinierten Subagents können Sie spezialisierte Agenten erstellen, die auf Ihre projektspezifischen Anforderungen, Fachkenntnisse oder Team-Workflows zugeschnitten sind.

Erstellungsmethoden

Dateistruktur

Dateien für benutzerdefinierte Subagents verwenden das Markdown-Format mit YAML-Frontmatter:

---
name: subagent-name
description: Brief description of specialization
---
# System Prompt

[Behavior definition, personality, interpretation style]

Invocation policy (strict): Only run if explicitly requested.

When to use:
- Specific scenario 1
- Specific scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2

YAML-Frontmatter (erforderlich):

• name: Subagenten-Bezeichner, der in @-Erwähnungen verwendet wird
• description: Einzeilige Beschreibung des Zwecks des Subagenten

Abschnitt System-Prompt: Markdown-Inhalt, der das Verhalten des Subagenten definiert:

• Persönlichkeit und Tonfall
• Interpretationsansatz für Aufgaben
• Bevorzugtes Ausgabeformat
• Entscheidungsprinzipien

Aufrufrichtlinie (erforderlich):

Invocation policy (strict|flexible): Policy description

• strict: Nur aufrufen, wenn vom Nutzer explizit angefordert
• flexible: Automatischen Aufruf basierend auf Aufgabenmustern erlauben

Nutzungsrichtlinien:

When to use the [name] agent:
- Bullet list of scenarios for invocation

When NOT to use:
- Bullet list of scenarios to avoid

Beispiele für benutzerdefinierte Subagents

---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt

You are an API documentation specialist.

Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides

When NOT to use:
- Inline code comments
- User-facing documentation

---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt

You are a database migration safety specialist.

Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables

Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures

Invocation policy (strict): Only run when explicitly requested.

When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures

When NOT to use:
- Schema design from scratch
- Query optimization

---
name: a11y-auditor
description: Audits frontend code for accessibility compliance
---
# System Prompt

You are an accessibility compliance specialist (WCAG 2.1 Level AA).

Audit criteria:
- Semantic HTML structure
- ARIA labels and roles
- Keyboard navigation support
- Color contrast ratios
- Screen reader compatibility
- Focus management

Report format:
- Issues categorized by severity (critical/major/minor)
- WCAG guideline references
- Code examples showing fixes
- Testing recommendations

Invocation policy (flexible): May auto-invoke for UI component reviews.

When to use:
- User creates/modifies UI components
- Pre-deployment accessibility checks
- Compliance audits

When NOT to use:
- Backend API code
- Build configuration files

Häufige Anwendungsfälle für benutzerdefinierte Subagents

Konfiguration des Subagenten-Verhaltens (AGENTS.md-Muster)

Während AGENTS.md primär als Projektregeldatei dient (siehe Regelsysteme), kann sie auch projektspezifisches Subagenten-Verhalten definieren.

Prinzipien für die Gestaltung von System-Prompts

Konkret und richtungsweisend sein: Definieren Sie exakte Verhaltenserwartungen statt allgemeiner Hinweise.

Gut:

Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks

Vermeiden:

Try to optimize code when possible

Persönlichkeit und Tonfall festlegen: Erstellen Sie ausgeprägte „Personas", die für bestimmte Zwecke optimiert sind:

You are a performance optimization specialist.

Entscheidungsprinzipien definieren: Legen Sie fest, wie der Subagent mit Abwägungen umgehen soll:

When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement

Ausgabeformat festlegen: Steuern Sie, wie Ergebnisse präsentiert werden:

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Konfiguration der Aufrufrichtlinie

Strict-Richtlinie:

Invocation policy (strict): Only run when explicitly requested.

Verwenden Sie diese, wenn:

• der Subagent sensible Vorgänge bearbeitet (Sicherheitsprüfungen, Datenbankmigrationen)
• der Nutzer bewusst entscheiden soll, wann er ihn aufruft
• ein automatischer Aufruf störend sein könnte

Flexible-Richtlinie:

Invocation policy (flexible): May auto-invoke based on task patterns.

Verwenden Sie diese, wenn:

• der Subagent hilfreichen Kontext bietet, ohne zu stören
• ein automatischer Aufruf die Workflow-Effizienz steigert
• Aufgabenmuster klar erkennbar sind

Best Practices für Nutzungsrichtlinien:

Abschnitt „Wann verwenden":

• Seien Sie konkret bei den Auslöseszenarien
• Fügen Sie Beispiel-Prompts ein, die den Subagenten aufrufen sollen
• Beschreiben Sie Aufgabenmerkmale, die der Spezialisierung des Subagenten entsprechen

Abschnitt „Wann NICHT verwenden":

• Listen Sie Ausschlüsse explizit auf, um unangemessene Aufrufe zu verhindern
• Klären Sie Abgrenzungen zu verwandten Subagents
• Verhindern Sie ausuferndes Aufgabenwachstum

Aufgabenrouting und -verteilung

Das Multi-Subagenten-System von Verdent ermöglicht die parallele Aufgabenausführung mit automatischem Routing und Koordination über spezialisierte Agenten hinweg.

Architekturkomponenten

Hauptagent (Orchestrator): Der primäre Agent analysiert Nutzeranfragen, zerlegt komplexe Aufgaben und delegiert spezialisierte Arbeit an die passenden Subagents. Er behält den Konversationskontext bei und koordiniert die Ergebnisse der Subagents.

Subagenten-Pool: Sammlung verfügbarer Subagents (sowohl Standard als auch benutzerdefiniert), die automatisch oder manuell aufgerufen werden können. Jeder arbeitet unabhängig mit isoliertem Kontext.

Automatisches Aufgabenrouting: Wenn der Hauptagent Aufgabenmuster erkennt, die zu Subagenten-Spezialisierungen passen, verteilt er die Arbeit automatisch:

• Fragen zur Erkundung des Codebase → Explorer-Subagent
• Anfragen zur Sicherheitsprüfung → Code-reviewer-Subagent
• Validierungsprüfungen → Verifier-Subagent

Parallele Ausführung: Für komplexe Vorgänge können mehrere Subagents gleichzeitig laufen. Beispiel: Der Explorer-Subagent durchsucht das Codebase, während der Code-reviewer gleichzeitig die Sicherheit analysiert – das liefert schnellere Ergebnisse.

Ergebniszusammenführung: Die Ausgaben der Subagents werden an den Hauptagenten zurückgegeben, der die Ergebnisse zusammenführt und dem Nutzer eine einheitliche Antwort präsentiert.

Subagenten-Überwachung

Verfolgen Sie die Nutzung und Leistung von Subagents über die Chat-Ansicht, in der Verdent Vorgänge und Ergebnisse der Subagents anzeigt.

Überwachungsmethoden

Anzeigen in der Chat-Ansicht:

• Aufrufe von Subagents erscheinen im Konversationsverlauf
• Fortschrittsanzeigen zeigen, wenn Subagents ausgeführt werden
• Ergebnisse geben explizit an, welcher Subagent die Ausgabe geliefert hat

Abschnitt „Subagenten-Ausgaben": Dedizierte Anzeige für:

• Ergebnisse aus der Aufgabenausführung der Subagents
• Fortschrittsanzeigen für parallele Aufgaben
• Zusammengefasste Übersichten nach Abschluss der Aufgaben

Zuordnung von Antworten: Verdent ordnet Ergebnisse in den Antworten den jeweiligen Subagents zu und macht so deutlich, welcher Agent welche Analyse oder Suche durchgeführt hat.

Sichtbarkeit und Transparenz

Transparenz der Vorgänge: Verdent zeigt an:

• welcher Subagent aufgerufen wurde
• ob der Aufruf automatisch oder manuell erfolgte
• den Grund der Aufgabendelegation
• den Ausführungsstatus des Subagenten

Überprüfung der manuellen Angabe: Wenn Sie @-Erwähnungen verwenden, bestätigt Verdent, dass der angegebene Subagent die Aufgabe bearbeitet, und stellt so sicher, dass Ihre Routing-Präferenzen berücksichtigt werden.

Siehe auch