Създаване на персонализиран агент в TOML
На тази страница
Урокът е пренаписан на 2 ноември 2026 г. Предишните примери използваха ключове, които не съществуват във файловете на агентите (
model,system_prompt,auto_approve), и несъществуващи инструменти (list_dir,edit_file). Имената на ключовете и инструментите вече са приведени в съответствие с официалната документация и изходния код на Vibe. Източници: Agents · Configuration reference — Agent definition files · built-in tools (mistral-vibe repo).
Отвъд вградените агенти
Вградените агенти покриват стандартни роли, но Вашите проекти имат уникални нужди: екипът по плащанията изисква различни предпазни мерки в сравнение с екипа за документация. Vibe Ви позволява да създавате персонализирани агенти, като поставите .toml файл в ~/.vibe/agents/ (на ниво потребител) или ./.vibe/agents/ (на ниво проект, зарежда се само ако папката е доверена). Поведението, дефинирано във файл, е четимо, подлежащо на версиониране и споделяне, за разлика от инструкциите, които се повтарят във всяка сесия.
Името на агента съвпада с името на файла: redteam.toml се стартира с vibe --agent redteam. Името main е запазено.
Ключове във файла на агента
| Ключ | Роля |
|---|---|
agent_type | "agent" (по подразбиране, избираем от потребителя) или "subagent" (стартира се само чрез делегиране) |
display_name, description | Име за показване и описание; описанието е задължително за под-агент |
instructions | Вградени инструкции, добавяни след системния промпт (за под-агент те го заместват) |
system_prompt_id | Име на Markdown файл в ~/.vibe/prompts/ или ./.vibe/prompts/, без разширението |
active_model | Псевдоним (alias) на модела, който да се използва за този агент |
enabled_tools, disabled_tools | Списък с разрешени и блокирани инструменти (точни имена, шаблони с glob или изрази re:) |
[tools.<tool>] | Разрешения за конкретен инструмент: permission = "always", "ask" или "never", плюс за bash списъци allowlist и denylist с префикси на команди |
safety | Визуален индикатор само (цвят на рамката на входа): safe, neutral, destructive, smart или yolo; не налага никакви разрешения (Урок 3) |
Инструменти, които можете да назовете
Вградените инструменти на Vibe използват следните имена: read_file, write_file, edit (предишно име search_replace), bash, grep, todo, task (делегирне към под-агент), skill, ask_user_question, web_fetch и web_search. Инструментите от MCP сървър се именуват като {server}_{tool}, а инструментите на конекторите са connector_{connector}_{tool}. Грешно изписано име на инструмент в enabled_tools не съвпада с нищо: проверете правописа, преди да заключите, че агентът „отказва“ да запише файл.
Първи агент: Планировчикът
Vibe няма вграден агент plan; документацията предоставя този пример само за четене, за да проучите хранилището и да предложите план преди всякаква промяна:
# ~/.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"
Стартирайте го с vibe --agent plan. След като планът бъде одобрен, натиснете Shift+Tab, за да превключите към accept-edits за изпълнение. Обърнете внимание на реда на файловете: в TOML всеки ключ, написан след заглавие на таблица като [tools.bash], принадлежи към тази таблица. Поставете ключовете от най-високо ниво първи, а блоковете [tools.*] в края.
Агент за документация
# ~/.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"
Той може да чете, търси и пише, но не може да изпълнява команди: bash не е в неговия списък. Създаването на всеки файл изисква Вашето одобрение. Изпробвайте го върху малък модул, преди да го приложите към цяло хранилище.
Избор на модел за агент
active_model очаква псевдонима на конфигуриран модел. Vibe идва с вграден модел, Mistral Medium 3.5, с псевдоним mistral-medium-3.5. За друг модел първо декларирайте预设 (preset) в config.toml, след което препратете към неговия псевдоним:
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# във файла на агента
active_model = "codestral"
Без active_model агентът използва модела на сесията.
Написване на инструкции
Съществуват два пътя. instructions съдържа вграден текст, добавян след системния промпт на Vibe: това е най-простият подход. system_prompt_id сочи към Markdown файл в папката prompts/, което е полезно за дълги промптове, преглеждани при код ревюта. Един детайл в поведението е важен: промптът на персонализиран агент се прилага само ако го изберете преди първото си съобщение (чрез --agent или Shift+Tab). Ако превключите агентите по средата на сесията, неговите инструменти, разрешения и модел се прилагат незабавно, но неговият промпт влиза в сила едва след /clear.
Най-добри практики
Най-малко привилегии на първо място: предоставете на агента само инструментите, от които се нуждае. Един анализиращ агент не се нуждае от write_file; един писател не се нуждае от bash. Премахването на всеки инструмент прави цяла категория грешки невъзможни.
Един агент за една отговорност след това: файлът „всичко в едно“ произвежда посредствени отговори навсякъде. Три целеви файла са по-добри от един общ.
Прецизни инструкции накрая: дефинирайте точната роля, конвенциите на проекта, очаквания формат на изхода и грешките, които трябва да се избягват. Когато един агент разочарова, почти винаги е защото един от тези четири точки липсва.
Ключови изводи
- Персонализираният агент е
.tomlфайл в~/.vibe/agents/или./.vibe/agents/; името му съвпада с името на файла - Полезни ключове:
display_name,description,instructionsилиsystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<tool>] - Имена на инструменти:
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search active_modelочаква псевдоним на预设 за модел (илиmistral-medium-3.5, вграден)- Поставете блоковете
[tools.*]в края на файла