Tworzenie własnego agenta w formacie TOML
Na tej stronie
Lekcja przepisana 2 listopada 2026 r. Poprzednie przykłady używały kluczy, które nie istnieją w plikach agentów (
model,system_prompt,auto_approve) oraz narzędzi, których nie ma (list_dir,edit_file). Klucze i nazwy narzędzi są teraz zgodne z oficjalną dokumentacją referencyjną i kodem źródłowym Vibe. Źródła: Agents · Configuration reference — Agent definition files · built-in tools (mistral-vibe repo).
Poza agentami wbudowanymi
Agenty wbudowane obsługują standardowe persony, ale Twoje projekty mają unikalne potrzeby: zespół ds. płatności wymaga innych zabezpieczeń niż zespół ds. dokumentacji. Vibe pozwala tworzyć własne agenty poprzez umieszczenie pliku .toml w katalogu ~/.vibe/agents/ (poziom użytkownika) lub ./.vibe/agents/ (poziom projektu, ładowany tylko, jeśli folder jest zaufany). Zachowanie zdefiniowane w pliku jest czytelne, podlega kontroli wersji i można się nim dzielić, w przeciwieństwie do instrukcji powtarzanych przy każdej sesji.
Nazwa agenta odpowiada nazwie pliku: redteam.toml uruchamia się poleceniem vibe --agent redteam. Nazwa main jest zarezerwowana.
Klucze pliku agenta
| Klucz | Rola |
|---|---|
agent_type | "agent" (domyślnie, wybieralny przez użytkownika) lub "subagent" (uruchamiany tylko przez delegację) |
display_name, description | Wyświetlana nazwa i opis; opis jest obowiązkowy dla podagenta (subagent) |
instructions | Instrukcje wbudowane (inline) dołączane po monicie systemowym (dla podagenta zastępują one prompt systemowy) |
system_prompt_id | Nazwa pliku Markdown w katalogu ~/.vibe/prompts/ lub ./.vibe/prompts/, bez rozszerzenia |
active_model | Alias modelu używanego przez tego agenta |
enabled_tools, disabled_tools | Biała i czarna lista narzędzi (dokładne nazwy, wzorce glob lub wyrażenia re:) |
[tools.<tool>] | Uprawnienia dla konkretnego narzędzia: permission = "always", "ask" lub "never", a dla bash dodatkowo allowlist i denylist prefiksów poleceń |
safety | Wizualny wskaźnik tylko (kolor ramki pola wprowadzania): safe, neutral, destructive, smart lub yolo; nie wymusza żadnych uprawnień (Lekcja 3) |
Narzędzia, które możesz nazwać
Wbudowane narzędzia Vibe mają następujące nazwy: read_file, write_file, edit (dawniej search_replace), bash, grep, todo, task (delegacja do podagenta), skill, ask_user_question, web_fetch oraz web_search. Narzędzia z serwera MCP mają nazwę {server}_{tool}, a narzędzia konektorów to connector_{connector}_{tool}. Błędnie wpisana nazwa narzędzia w enabled_tools nie dopasuje niczego: sprawdź pisownię, zanim wnioskujesz, że agent „odmawia“ zapisu pliku.
Pierwszy agent: Planista
Vibe nie posiada wbudowanego agenta plan; dokumentacja dostarcza ten przykład tylko do odczytu, aby eksplorować repozytorium i proponować plan przed jakąkolwiek modyfikacją:
# ~/.vibe/agents/plan.toml
display_name = "Plan"
description = "Explores the repository and proposes a plan before any modification."
safety = "safe"
disabled_tools = ["edit", "write_file"]
instructions = """
Explore the repository and propose a step-by-step implementation plan.
Do not modify any files until the user approves the plan.
"""
[tools.bash]
permission = "ask"
Uruchom go poleceniem vibe --agent plan. Gdy plan zostanie zatwierdzony, naciśnij Shift+Tab, aby przełączyć się na accept-edits w celu wykonania. Zwróć uwagę na kolejność w pliku: w formacie TOML każdy klucz zapisany po nagłówku tabeli, takim jak [tools.bash], należy do tej tabeli. Najpierw umieść klucze najwyższego poziomu, a bloki [tools.*] na końcu.
Agent dokumentacyjny
# ~/.vibe/agents/doc-writer.toml
display_name = "Technical Writer"
description = "Writes technical documentation based on source code."
safety = "neutral"
enabled_tools = ["read_file", "grep", "write_file", "edit", "ask_user_question"]
instructions = """
Based on the source code:
1. Write a docstring for every public function.
2. Maintain a structured README with examples.
3. Document required environment variables.
Style: professional, concise, supported by code examples.
"""
[tools.write_file]
permission = "ask"
Może on czytać, wyszukiwać i zapisywać, ale nie może uruchamiać poleceń: bash nie znajduje się na jego liście. Każde utworzenie pliku wymaga Twojej zgody. Wypróbuj go na małym module przed zastosowaniem do całego repozytorium.
Wybór modelu agenta
Klucz active_model oczekuje aliasu skonfigurowanego modelu. Vibe jest dostarczany z wbudowanym modelem, Mistral Medium 3.5, z aliasem mistral-medium-3.5. Aby użyć innego modelu, najpierw zadeklaruj preset w pliku config.toml, a następnie odwołaj się do jego aliasu:
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# w pliku agenta
active_model = "codestral"
Bez klucza active_model agent używa modelu bieżącej sesji.
Pisanie instrukcji
Istnieją dwie ścieżki. instructions zawiera tekst wbudowany dołączany po prompcie systemowym Vibe: jest to najprostsze podejście. system_prompt_id wskazuje na plik Markdown w folderze prompts/, co jest przydatne w przypadku długich promptów recenzowanych w ramach code review. Istnieje jeden istotny szczegół behawioralny: prompt własnego agenta stosuje się tylko wtedy, gdy wybierzesz go przed swoją pierwszą wiadomością (poprzez --agent lub Shift+Tab). Jeśli przełączysz agentów w trakcie sesji, jego narzędzia, uprawnienia i model zaczną obowiązywać natychmiast, ale jego prompt zostanie zastosowany dopiero po wykonaniu polecenia /clear.
Najlepsze praktyki
Najpierw zasada najmniejszych przywilejów: daj agentowi tylko te narzędzia, których potrzebuje. Agent analityczny nie potrzebuje write_file; pisarz nie potrzebuje bash. Usunięcie każdego narzędzia czynni całą kategorię błędów niemożliwą do popełnienia.
Następnie jeden agent na jedno zadanie: plik typu „wszystko w jednym“ generuje przeciętne odpowiedzi wszędzie. Trzy ukierunkowane pliki są lepsze niż jeden ogólny.
Na koniec precyzyjne instrukcje: zdefiniuj dokładną rolę, konwencje projektowe, oczekiwany format wyjścia oraz błędy, których należy unikać. Gdy agent zawodzi, prawie zawsze wynika to z pominięcia jednego z tych czterech punktów.
Kluczowe wnioski
- Własny agent to plik
.tomlw katalogu~/.vibe/agents/lub./.vibe/agents/; jego nazwa odpowiada nazwie pliku - Przydatne klucze:
display_name,description,instructionslubsystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<tool>] - Nazwy narzędzi:
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search active_modeloczekuje aliasu presetu modelu (lubmistral-medium-3.5, wbudowanego)- Umieść bloki
[tools.*]na końcu pliku