Przejdź do głównej treści
Polski— Wybierz język
Menu

Tworzenie własnego agenta w formacie TOML

Lekcja 2 z 14 Zaktualizowano 2 listopada 2026 Zaawansowany
Na tej stronie
  1. Poza agentami wbudowanymi
  2. Klucze pliku agenta
  3. Narzędzia, które możesz nazwać
  4. Pierwszy agent: Planista
  5. Agent dokumentacyjny
  6. Wybór modelu agenta
  7. Pisanie instrukcji
  8. Najlepsze praktyki
  9. Kluczowe wnioski

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

KluczRola
agent_type"agent" (domyślnie, wybieralny przez użytkownika) lub "subagent" (uruchamiany tylko przez delegację)
display_name, descriptionWyświetlana nazwa i opis; opis jest obowiązkowy dla podagenta (subagent)
instructionsInstrukcje wbudowane (inline) dołączane po monicie systemowym (dla podagenta zastępują one prompt systemowy)
system_prompt_idNazwa pliku Markdown w katalogu ~/.vibe/prompts/ lub ./.vibe/prompts/, bez rozszerzenia
active_modelAlias modelu używanego przez tego agenta
enabled_tools, disabled_toolsBiał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ń
safetyWizualny 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 .toml w katalogu ~/.vibe/agents/ lub ./.vibe/agents/; jego nazwa odpowiada nazwie pliku
  • Przydatne klucze: display_name, description, instructions lub system_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_model oczekuje aliasu presetu modelu (lub mistral-medium-3.5, wbudowanego)
  • Umieść bloki [tools.*] na końcu pliku