Einen benutzerdefinierten Agenten in TOML erstellen

Lektion am 2. November 2026 überarbeitet. In den vorherigen Beispielen wurden Schlüssel verwendet, die in Agenten-Dateien nicht existieren (model, system_prompt, auto_approve) sowie nicht vorhandene Tools (list_dir, edit_file). Die Schlüssel und Tool-Namen stimmen nun mit dem offiziellen Referenzmaterial und dem Vibe-Quellcode überein. Quellen: Agents · Konfigurationsreferenz — Agenten-Definitiondateien · eingebaute Tools (mistral-vibe-Repository).

Über die eingebaute Agenten-Funktionalität hinaus

Eingebaute Agenten decken Standard-Personas ab, doch Ihre Projekte haben spezifische Anforderungen: Ein Zahlungsteam benötigt andere Sicherheitsvorkehrungen als ein Dokumentationsteam. Mit Vibe können Sie benutzerdefinierte Agenten erstellen, indem Sie eine .toml-Datei in ~/.vibe/agents/ (Benutzer-Ebene) oder ./.vibe/agents/ (Projekt-Ebene, wird nur geladen, wenn das Verzeichnis vertrauenswürdig ist) platzieren. Das in einer Datei definierte Verhalten ist lesbar, versionierbar und teilbar, im Gegensatz zu Anweisungen, die in jeder Sitzung wiederholt werden müssen.

Der Agentenname entspricht dem Dateinamen: redteam.toml startet mit vibe --agent redteam. Der Name main ist reserviert.

Schlüssel in der Agenten-Datei

Benennbare Tools

Die eingebauten Tools von Vibe verwenden folgende Namen: read_file, write_file, edit (früher search_replace), bash, grep, todo, task (Delegation an einen Subagenten), skill, ask_user_question, web_fetch und web_search. Tools von einem MCP-Server werden als {server}_{tool} benannt, und Connector-Tools als connector_{connector}_{tool}. Ein falsch geschriebener Toolname in enabled_tools entspricht nichts: Überprüfen Sie die Rechtschreibung, bevor Sie schließen, dass ein Agent eine Datei „verweigert” zu schreiben.

Der erste Agent: Der Planer

Vibe verfügt über keinen eingebauten plan-Agenten; die Dokumentation bietet dieses lesegeschützte Beispiel an, um ein Repository zu erkunden und einen Plan vor jeder Änderung vorzuschlagen:

# ~/.vibe/agents/plan.toml
display_name = "Plan"
description = "Erkundet das Repository und schlägt einen Plan vor, bevor jede Änderung vorgenommen wird."
safety = "safe"
disabled_tools = ["edit", "write_file"]
instructions = """
Erkunden Sie das Repository und schlagen Sie einen schrittweisen Implementierungsplan vor.
Ändern Sie keine Dateien, bis der Benutzer den Plan genehmigt hat.
"""

[tools.bash]
permission = "ask"

Starten Sie ihn mit vibe --agent plan. Sobald der Plan genehmigt ist, drücken Sie Shift+Tab, um zu accept-edits zu wechseln, um die Ausführung zu starten. Beachten Sie die Dateireihenfolge: In TOML gehören alle Schlüssel, die nach einem Tabellenkopf wie [tools.bash] geschrieben werden, zu dieser Tabelle. Platzieren Sie die Top-Level-Schlüssel zuerst und die [tools.*]-Blöcke am Ende.

Ein Dokumentations-Agent

# ~/.vibe/agents/doc-writer.toml
display_name = "Technischer Autor"
description = "Erstellt technische Dokumentation auf Basis von Quellcode."
safety = "neutral"
enabled_tools = ["read_file", "grep", "write_file", "edit", "ask_user_question"]
instructions = """
Basierend auf dem Quellcode:
1. Erstellen Sie für jede öffentliche Funktion einen Docstring.
2. Pflegen Sie eine strukturierte README-Datei mit Beispielen.
3. Dokumentieren Sie erforderliche Umgebungsvariablen.
Stil: professionell, prägnant, unterstützt durch Code-Beispiele.
"""

[tools.write_file]
permission = "ask"

Er kann lesen, suchen und schreiben, kann aber keine Befehle ausführen: bash befindet sich nicht in seiner Liste. Jede Datei-Erstellung erfordert Ihre Genehmigung. Testen Sie ihn zunächst an einem kleinen Modul, bevor Sie ihn auf ein ganzes Repository anwenden.

Auswahl eines Agenten-Modells

active_model erwartet den Alias eines konfigurierten Modells. Vibe liefert ein eingebautes Modell, Mistral Medium 3.5, mit dem Alias mistral-medium-3.5. Für ein anderes Modell deklarieren Sie zunächst ein Preset in config.toml und verweisen dann auf dessen Alias:

# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"

# in der Agenten-Datei
active_model = "codestral"

Ohne active_model verwendet der Agent das Modell der aktuellen Sitzung.

Anweisungen verfassen

Es gibt zwei Wege. instructions enthält Inline-Text, der nach dem Systemprompt von Vibe angehängt wird: dies ist der einfachste Ansatz. system_prompt_id verweist auf eine Markdown-Datei im prompts/-Ordner, was für lange Prompts nützlich ist, die in Code-Reviews geprüft werden. Ein Verhaltensdetail ist wichtig: Der Prompt eines benutzerdefinierten Agenten gilt nur, wenn Sie ihn vor Ihrer ersten Nachricht auswählen (über --agent oder Shift+Tab). Wenn Sie Agenten mitten in einer Sitzung wechseln, gelten seine Tools, Berechtigungen und das Modell sofort, doch sein Prompt tritt nur nach /clear in Kraft.

Best Practices

Prinzip der geringsten Rechte zuerst: Geben Sie einem Agenten nur die Tools, die er benötigt. Ein Analyse-Agent benötigt write_file nicht; ein Autor benötigt bash nicht. Das Entfernen eines Tools macht eine ganze Kategorie von Fehlern unmöglich.

Ein Agent pro Verantwortungsbereich als Nächstes: Eine All-in-One-Datei erzeugt überall mittelmäßige Antworten. Drei gezielte Dateien schlagen eine generische Datei.

Präzise Anweisungen schließlich: Definieren Sie die genaue Rolle, Projekt-Konventionen, erwartetes Ausgabeformat und zu vermeidende Fehler. Wenn ein Agent enttäuscht, liegt es fast immer daran, dass einer dieser vier Punkte fehlt.

Wichtige Erkenntnisse

• Ein benutzerdefinierter Agent ist eine .toml-Datei in ~/.vibe/agents/ oder ./.vibe/agents/; sein Name entspricht dem Dateinamen
• Nützliche Schlüssel: display_name, description, instructions oder system_prompt_id, active_model, enabled_tools, disabled_tools, [tools.<tool>]
• Tool-Namen: read_file, write_file, edit, bash, grep, todo, task, skill, ask_user_question, web_fetch, web_search
• active_model erwartet einen Alias für ein Modell-Preset (oder mistral-medium-3.5, eingebautes Modell)
• Platzieren Sie [tools.*]-Blöcke am Ende der Datei