Crearea unui Agent Personalizat în TOML
Pe această pagină
Lecție rescrisă la 2 noiembrie 2026. Exemplele anterioare foloseau chei care nu există în fișierele de agenți (
model,system_prompt,auto_approve) și instrumente inexistente (list_dir,edit_file). Cheile și numele instrumentelor sunt acum aliniate cu referința oficială și codul sursă Vibe. Surse: Agents · Configuration reference — Agent definition files · built-in tools (mistral-vibe repo).
Dincolo de agenții încorporați
Agenții încorporați acoperă persoane standard, dar proiectele dumneavoastră au nevoi unice: o echipă de plăți necesită măsuri de siguranță diferite față de o echipă de documentație. Vibe vă permite să creați agenți personalizați plasând un fișier .toml în ~/.vibe/agents/ (la nivel de utilizator) sau ./.vibe/agents/ (la nivel de proiect, încărcat doar dacă dosarul este de încredere). Comportamentul definit într-un fișier este lizibil, poate fi versionat și partajat, spre deosebire de instrucțiunile repetate la fiecare sesiune.
Numele agentului corespunde numelui fișierului: redteam.toml se lansează cu vibe --agent redteam. Numele main este rezervat.
Cheile fișierului de agent
| Cheie | Rol |
|---|---|
agent_type | "agent" (implicit, selectabil de utilizator) sau "subagent" (lansat doar prin delegare) |
display_name, description | Numele afișat și descrierea; descrierea este obligatorie pentru un subagent |
instructions | Instrucțiuni inline adăugate după promptul de sistem (pentru un subagent, acestea îl înlocuiesc) |
system_prompt_id | Numele unui fișier Markdown din ~/.vibe/prompts/ sau ./.vibe/prompts/, fără extensie |
active_model | Aliasul modelului de utilizat pentru acest agent |
enabled_tools, disabled_tools | Listă de permisiuni (allowlist) și listă de blocare (blocklist) pentru instrumente (nume exacte, tipare glob sau expresii re:) |
[tools.<tool>] | Permisiuni per instrument: permission = "always", "ask" sau "never", plus pentru bash, allowlist și denylist de prefixe de comenzi |
safety | Indicator vizual doar (culoarea bordurii de intrare): safe, neutral, destructive, smart sau yolo; nu impune nicio permisiune (Lecția 3) |
Instrumente pe care le puteți numi
Instrumentele încorporate ale Vibe folosesc aceste nume: read_file, write_file, edit (fostul search_replace), bash, grep, todo, task (delegare către un subagent), skill, ask_user_question, web_fetch și web_search. Instrumentele de la un server MCP sunt numite {server}_{tool}, iar instrumentele conector sunt connector_{connector}_{tool}. Un nume de instrument scris greșit în enabled_tools nu va corespunde nimicului: verificați ortografierea înainte de a concluziona că un agent „refuză“ să scrie un fișier.
Primul agent: Planificatorul
Vibe nu are un agent plan încorporat; documentația oferă acest exemplu read-only pentru a explora un depozit și a propune un plan înainte de orice modificare:
# ~/.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"
Lansați-l cu vibe --agent plan. Odată ce planul este aprobat, apăsați Shift+Tab pentru a comuta la accept-edits pentru execuție. Rețineți ordinea fișierului: în TOML, orice cheie scrisă după un antet de tabel precum [tools.bash] aparține acelui tabel. Plasați cheile de nivel superior primele, iar blocurile [tools.*] la sfârșit.
Un agent de documentație
# ~/.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"
Acesta poate citi, căuta și scrie, dar nu poate rula comenzi: bash nu se află în lista sa. Fiecare creare de fișier necesită aprobarea dumneavoastră. Încercați-l pe un modul mic înainte de a-l aplica unui întreg depozit.
Alegerea unui model de agent
active_model așteaptă aliasul unui model configurat. Vibe vine cu un model încorporat, Mistral Medium 3.5, cu aliasul mistral-medium-3.5. Pentru un alt model, declarați mai întâi un preset în config.toml, apoi faceți referire la aliasul său:
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# în fișierul agentului
active_model = "codestral"
Fără active_model, agentul utilizează modelul sesiunii.
Scrierea instrucțiunilor
Există două căi. instructions conține text inline adăugat după promptul de sistem al Vibe: aceasta este abordarea cea mai simplă. system_prompt_id indică un fișier Markdown din dosarul prompts/, util pentru prompturi lungi revizuite în cadrul reviziilor de cod. Un detaliu comportamental contează: promptul unui agent personalizat se aplică doar dacă îl selectați înainte de primul mesaj (prin --agent sau Shift+Tab). Dacă comutați agenții la mijlocul sesiunii, instrumentele, permisiunile și modelul său se aplică imediat, dar promptul său intră în vigoare doar după /clear.
Cele mai bune practici
Privilegiul minim mai întâi: oferiți unui agent doar instrumentele de care are nevoie. Un agent de analiză nu are nevoie de write_file; un scriitor nu are nevoie de bash. Eliminarea fiecărui instrument face imposibilă o întreagă categorie de erori.
Un agent per responsabilitate apoi: un fișier universal produce răspunsuri mediocre peste tot. Trei fișiere țintite bat unul generic.
Instrucțiuni precise în final: definiți rolul exact, convențiile proiectului, formatul de ieșire așteptat și erorile de evitat. Când un agent dezamăgește, este aproape întotdeauna pentru că unul dintre aceste patru puncte lipsește.
Puncte cheie
- Un agent personalizat este un fișier
.tomlîn~/.vibe/agents/sau./.vibe/agents/; numele său corespunde numelui fișierului - Chei utile:
display_name,description,instructionssausystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<tool>] - Nume de instrumente:
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search active_modelașteaptă un alias de preset de model (saumistral-medium-3.5, încorporat)- Plasați blocurile
[tools.*]la sfârșitul fișierului