Luo mukautettu agentti TOML-muodossa
Tällä sivulla
Oppitunti kirjoitettu uudelleen 2. marraskuuta 2026. Aiemmat esimerkit käyttivät avaimia, joita ei ole olemassa agenttitiedostoissa (
model,system_prompt,auto_approve), sekä olemattomia työkaluja (list_dir,edit_file). Avaimet ja työkalujen nimet on nyt yhdenmukaistettu virallisen viittauksen ja Vibe-lähdekoodin kanssa. Lähteet: Agents · Configuration reference — Agent definition files · built-in tools (mistral-vibe repo).
Sisäänrakennettujen agenttien tuolla puolen
Sisäänrakennetut agentit kattavat standardiroolit, mutta projekteillasi on ainutlaatuisia tarpeita: maksutiimi tarvitsee erilaisia suojauksia kuin dokumentaatiotiimi. Vibe mahdollistaa mukautettujen agenttien luomisen sijoittamalla .toml-tiedoston hakemistoon ~/.vibe/agents/ (käyttäjäkohtainen) tai ./.vibe/agents/ (projektikohtainen, ladataan vain, jos kansio on luotettu). Tiedostoon määritelty käyttäytyminen on luettavaa, versionoitavaa ja jaettavissa olevaa, toisin kuin joka istunnossa toistettavat ohjeet.
Agentin nimi vastaa tiedostonimeä: redteam.toml käynnistyy komennolla vibe --agent redteam. Nimi main on varattu.
Agenttitiedoston avaimet
| Avain | Rooli |
|---|---|
agent_type | "agent" (oletus, käyttäjän valittavissa) tai "subagent" (käynnistyy vain delegoinnin kautta) |
display_name, description | Näyttönimi ja kuvaus; kuvaus on pakollinen alagentille |
instructions | Rivinsisäiset ohjeet, jotka liitetään system promptin perään (alagentilla nämä korvaavat sen) |
system_prompt_id | Markdown-tiedoston nimi hakemistossa ~/.vibe/prompts/ tai ./.vibe/prompts/, ilman tiedostopäätettä |
active_model | Tälle agentille käytettävän mallin alias |
enabled_tools, disabled_tools | Työkalujen sallimis- ja estolistat (tarkat nimet, glob-kuviot tai re:-lausekkeet) |
[tools.<tool>] | Työkalukohtaiset oikeudet: permission = "always", "ask" tai "never", sekä bash:lle komentoetuliitteiden allowlist ja denylist |
safety | Vain visuaalinen indikaattori (syötteen reunan väri): safe, neutral, destructive, smart tai yolo; se ei pakota oikeuksia (Oppitunti 3) |
Nimeämisesi työkalut
Viben sisäänrakennetut työkalut käyttävät seuraavia nimiä: read_file, write_file, edit (aiemmin search_replace), bash, grep, todo, task (delegointi alagentille), skill, ask_user_question, web_fetch ja web_search. MCP-palvelimen työkalut nimetään muodossa {server}_{tool}, ja liittimien työkalut muodossa connector_{connector}_{tool}. Väärin kirjoitettu työkalun nimi kohdassa enabled_tools ei täsmää mihinkään: tarkista oikeinkirjoitus ennen kuin päättelet agentin “kieltäytyvän” tiedoston kirjoittamisesta.
Ensimmäinen agentti: Suunnittelija
Vibellä ei ole sisäänrakennettua plan-agenttia; dokumentaatio tarjoaa tämän vain lukuun tarkoitetun esimerkin repositorion tutkimiseen ja suunnitelman ehdottamiseen ennen muutoksia:
# ~/.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"
Käynnistä se komennolla vibe --agent plan. Kun suunnitelma on hyväksytty, paina Shift+Tab vaihtaaksesi tilaan accept-edits toteutusta varten. Huomaa tiedoston järjestys: TOML-muodossa mikä tahansa avain, joka on kirjoitettu taulukon otsikon (kuten [tools.bash]) jälkeen, kuuluu kyseiseen taulukkoon. Sijoita ylemmän tason avaimet ensin ja [tools.*]-lohkot loppuun.
Dokumentaatioagentti
# ~/.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"
Se voi lukea, hakea ja kirjoittaa, mutta ei suorittaa komentoja: bash ei ole sen listalla. Jokainen tiedoston luominen vaatii hyväksyntäsi. Kokeile sitä pienellä moduulilla ennen kuin sovellat sitä koko repositorioon.
Agenttimallin valinta
active_model odottaa määritetyn mallin aliasta. Vibe toimitetaan sisäänrakennetun mallin, Mistral Medium 3.5:n, kanssa, jonka alias on mistral-medium-3.5. Toista mallia varten määritä ensin esiasetus tiedostoon config.toml ja viittaa sen jälkeen sen aliakseen:
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# agenttitiedostossa
active_model = "codestral"
Ilman active_model-avainta agentti käyttää istunnon mallia.
Ohjeiden kirjoittaminen
Kaksi polkua on olemassa. instructions sisältää rivinsisäistä tekstiä, joka liitetään Viben system promptin perään: tämä on yksinkertaisin lähestymistapa. system_prompt_id osoittaa Markdown-tiedostoon prompts/-kansiossa, mikä on hyödyllistä pitkille prompteille, jotka käydään läpi koodikatselmuksissa. Yksi käyttäytymiseen liittyvä yksityiskohta on tärkeä: mukautetun agentin prompt otetaan käyttöön vain, jos valitset sen ennen ensimmäistä viestiäsi (komentovalitsimella --agent tai näppäinyhdistelmällä Shift+Tab). Jos vaihdat agentteja istunnon aikana, sen työkalut, oikeudet ja malli tulevat voimaan välittömästi, mutta sen prompt astuu voimaan vasta /clear-komennon jälkeen.
Parhaat käytännöt
Vähäisin oikeudet ensin: anna agentille vain tarvittavat työkalut. Analyysiagentti ei tarvitse write_file-työkalua; kirjoittaja ei tarvitse bash:ia. Jokaisen työkalun poistaminen tekee kokonaisesta virheluokasta mahdottoman.
Yksi agentti per vastuualue seuraavaksi: yleiskäyttöinen tiedosto tuottaa keskinkertaisia vastauksia kaikkialla. Kolme kohdennettua tiedostoa voittaa yhden yleisen.
Tarkat ohjeet lopuksi: määritä tarkka rooli, projektin käytännöt, odotettu tulostemuoto ja vältettävät virheet. Kun agentti pettää odotukset, syynä on lähes aina yhden näistä neljästä kohdasta puuttuminen.
Keskeiset asiat
- Mukautettu agentti on
.toml-tiedosto hakemistossa~/.vibe/agents/tai./.vibe/agents/; sen nimi vastaa tiedostonimeä - Hyödyllisiä avaimia:
display_name,description,instructionstaisystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<tool>] - Työkalujen nimet:
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search active_modelodottaa mallin esiasetuksen aliasta (tai sisäänrakennettuamistral-medium-3.5:tä)- Sijoita
[tools.*]-lohkot tiedoston loppuun