Egyéni ügynök létrehozása TOML-ben
Ezen az oldalon
A leckét 2026. november 2-án írtuk át. A korábbi példák olyan kulcsokat használtak, amelyek nem léteznek az ügynökfájlokban (
model,system_prompt,auto_approve), valamint nem létező eszközöket (list_dir,edit_file). A kulcsok és az eszköznevek most már összhangban vannak a hivatalos referenciával és a Vibe forráskódjával. Források: Ügynökök · Konfigurációs referencia — Ügynökdefiníciós fájlok · beépített eszközök (mistral-vibe repo).
Túl a beépített ügynökökön
A beépített ügynökök lefedik a szabványos személyiségeket, de a projektjeidnek egyedi igényei lehetnek: egy fizetési csapatnak más biztonsági intézkedésekre van szüksége, mint egy dokumentációs csapatnak. A Vibe lehetővé teszi egyéni ügynökök létrehozását egy .toml fájl elhelyezésével a ~/.vibe/agents/ (felhasználói szint) vagy a ./.vibe/agents/ (projektszint, csak akkor töltődik be, ha a mappa megbízható) könyvtárban. A fájlban definiált viselkedés olvasható, verziókövethető és megosztható, ellentétben a minden munkamenetben megismételt utasításokkal.
Az ügynök neve megegyezik a fájlnévvel: a redteam.toml a vibe --agent redteam paranccsal indul. A main név fenntartott.
Ügynökfájl kulcsai
| Kulcs | Szerep |
|---|---|
agent_type | "agent" (alapértelmezett, a felhasználó választhatja) vagy "subagent" (csak delegálással indítható) |
display_name, description | Megjelenítendő név és leírás; alügynök esetén a leírás kötelező |
instructions | Beágyazott utasítások, amelyek a rendszerprompt után kerülnek hozzáfűzésre (alügynök esetén ezt helyettesítik) |
system_prompt_id | Egy Markdown fájl neve a ~/.vibe/prompts/ vagy ./.vibe/prompts/ könyvtárban, kiterjesztés nélkül |
active_model | Az ügynök által használni kívánt modell aliasa |
enabled_tools, disabled_tools | Az eszközök engedélyezési listája (allowlist) és tiltólistája (blocklist) (pontos nevek, glob minták vagy re: kifejezések) |
[tools.<tool>] | Eszközönkénti jogosultságok: permission = "always", "ask" vagy "never", plusz a bash esetén a parancselőtagok allowlist és denylist listái |
safety | Csak vizuális jelző (bemeneti keret színe): safe, neutral, destructive, smart vagy yolo; nem érvényesít jogosultságokat (3. lecke) |
Eszköznevek, amelyeket használhatsz
A Vibe beépített eszközei a következő neveket használják: read_file, write_file, edit (korábban search_replace), bash, grep, todo, task (delegálás alügynöknek), skill, ask_user_question, web_fetch és web_search. Egy MCP szerverről származó eszközök neve {server}_{tool}, a csatlakozó (connector) eszközöké pedig connector_{connector}_{tool}. Ha egy eszköznevét elgépeled az enabled_tools listában, az semmire sem fog illeszkedni: ellenőrizd a helyesírást, mielőtt arra következtetnél, hogy az ügynök „megtagadja“ egy fájl írását.
Első ügynök: A Tervező
A Vibe-nek nincs beépített plan ügynöke; a dokumentáció ezt a csak olvasható példát biztosítja egy tároló feltárására és egy terv javaslatára bármilyen módosítás előtt:
# ~/.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"
Indítsd el a vibe --agent plan paranccsal. Miután a tervet jóváhagytad, nyomd meg a Shift+Tab billentyűkombinációt, hogy az accept-edits ügynökre válts a végrehajtáshoz. Figyeld meg a fájlon belüli sorrendet: TOML-ben minden kulcs, amelyet egy táblafejléc (pl. [tools.bash]) után írsz, ahhoz a táblához tartozik. Helyezd el először a felső szintű kulcsokat, és a [tools.*] blokkokat a fájl végére.
Egy dokumentációs ügynök
# ~/.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"
Ez az ügynök tud olvasni, keresni és írni, de nem futtathat parancsokat: a bash nincs a listáján. Minden fájl létrehozása jóváhagyást igényel tőled. Próbáld ki először egy kis modulon, mielőtt egy teljes tárolóra alkalmaznád.
Ügynökmodell kiválasztása
Az active_model kulcs egy konfigurált modell aliasát várja. A Vibe tartalmaz egy beépített modellt, a Mistral Medium 3.5-öt, amelynek aliasa mistral-medium-3.5. Egy másik modell használatához először deklarálnod kell egy előbeállítást (preset) a config.toml fájlban, majd hivatkoznod kell az aliasára:
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# az ügynökfájlban
active_model = "codestral"
active_model nélkül az ügynök a munkamenet modelljét használja.
Utasítások írása
Két út létezik. Az instructions olyan beágyazott szöveget tartalmaz, amely a Vibe rendszerpromptja után kerül hozzáfűzésre: ez a legegyszerűbb megközelítés. A system_prompt_id egy Markdown fájlra mutat a prompts/ mappában, ami hosszú promptok esetén hasznos, amelyeket kódreview-k során vizsgálnak felül. Egy viselkedésbeli részlet számít: egy egyéni ügynök promptja csak akkor érvényesül, ha azt az első üzeneted előtt kiválasztod (a --agent kapcsolóval vagy a Shift+Tab billentyűvel). Ha munkamenet közben ügynököt váltasz, az eszközei, jogosultságai és modellje azonnal érvénybe lépnek, de a promptja csak a /clear parancs után lép hatályba.
Legjobb gyakorlatok
Először is a legkisebb jogosultság elve: csak azokat az eszközöket add meg az ügynöknek, amelyekre szüksége van. Egy elemző ügynöknek nincs szüksége write_file eszközre; egy írónak nincs szüksége bash-ra. Minden egyes eszköz eltávolítása lehetetlenné teszi a hibák egy teljes kategóriáját.
Másodszor: egy ügynök egy feladatkörre. Egy mindent átfogó fájl mindenhol közepes válaszokat produkál. Három célzott fájl jobb, mint egy általános.
Végül: pontos utasítások. Határozd meg a pontos szerepet, a projekt konvencióit, a várt kimeneti formátumot és a kerülendő hibákat. Ha egy ügynök csalódást okoz, az szinte mindig azért van, mert e négy pont valamelyike hiányzik.
Főbb megállapítások
- Egy egyéni ügynök egy
.tomlfájl a~/.vibe/agents/vagy a./.vibe/agents/könyvtárban; a neve megegyezik a fájlnévvel - Hasznos kulcsok:
display_name,description,instructionsvagysystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<tool>] - Eszköznevek:
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search - Az
active_modelegy modell előbeállítás (preset) aliasát várja (vagy a beépítettmistral-medium-3.5-öt) - Helyezd a
[tools.*]blokkokat a fájl végére