Crear un agente personalizado en TOML
En esta página
Lección reescrita el 2 de noviembre de 2026. Los ejemplos anteriores utilizaban claves que no existen en los archivos de agente (
model,system_prompt,auto_approve) y herramientas inexistentes (list_dir,edit_file). Las claves y los nombres de las herramientas se han alineado ahora con la referencia oficial y el código fuente de Vibe. Fuentes: Agents · Configuration reference — Agent definition files · built-in tools (mistral-vibe repo).
Más allá de los agentes integrados
Los agentes integrados cubren personas estándar, pero tus proyectos tienen necesidades únicas: un equipo de pagos requiere salvaguardas diferentes a las de un equipo de documentación. Vibe te permite crear agentes personalizados colocando un archivo .toml en ~/.vibe/agents/ (nivel de usuario) o ./.vibe/agents/ (nivel de proyecto, se carga solo si la carpeta es de confianza). El comportamiento definido en un archivo es legible, versionable y compartible, a diferencia de las instrucciones que se repiten en cada sesión.
El nombre del agente coincide con el nombre del archivo: redteam.toml se lanza con vibe --agent redteam. El nombre main está reservado.
Claves del archivo de agente
| Clave | Función |
|---|---|
agent_type | "agent" (predeterminado, seleccionable por el usuario) o "subagent" (lanzado solo por delegación) |
display_name, description | Nombre visible y descripción; la descripción es obligatoria para un subagente |
instructions | Instrucciones en línea añadidas después del prompt del sistema (para un subagente, lo sustituyen) |
system_prompt_id | Nombre de un archivo Markdown en ~/.vibe/prompts/ o ./.vibe/prompts/, sin la extensión |
active_model | Alias del modelo que usará este agente |
enabled_tools, disabled_tools | Lista blanca y lista negra de herramientas (nombres exactos, patrones glob o expresiones re:) |
[tools.<tool>] | Permisos por herramienta: permission = "always", "ask" o "never", además de allowlist y denylist de prefijos de comando para bash |
safety | Indicador visual únicamente (color del borde de entrada): safe, neutral, destructive, smart o yolo; no aplica permisos (Lección 3) |
Herramientas que puedes nombrar
Las herramientas integradas de Vibe usan estos nombres: read_file, write_file, edit (anteriormente search_replace), bash, grep, todo, task (delegación a un subagente), skill, ask_user_question, web_fetch y web_search. Las herramientas de un servidor MCP se nombran como {server}_{tool}, y las herramientas de conector como connector_{connector}_{tool}. Un nombre de herramienta mal escrito en enabled_tools no coincidirá con nada: verifica la ortografía antes de concluir que un agente «se niega» a escribir un archivo.
Primer agente: El planificador
Vibe no tiene un agente plan integrado; la documentación proporciona este ejemplo de solo lectura para explorar un repositorio y proponer un plan antes de cualquier modificación:
# ~/.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"
Lánzalo con vibe --agent plan. Una vez aprobado el plan, pulsa Shift+Tab para cambiar a accept-edits y ejecutarlo. Ten en cuenta el orden del archivo: en TOML, cualquier clave escrita después de un encabezado de tabla como [tools.bash] pertenece a esa tabla. Coloca las claves de nivel superior primero y los bloques [tools.*] al final.
Un agente de documentación
# ~/.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"
Puede leer, buscar y escribir, pero no puede ejecutar comandos: bash no está en su lista. Cada creación de archivo requiere tu aprobación. Pruébalo en un módulo pequeño antes de aplicarlo a un repositorio entero.
Elección del modelo del agente
active_model espera el alias de un modelo configurado. Vibe incluye un modelo integrado, Mistral Medium 3.5, con el alias mistral-medium-3.5. Para otro modelo, declara primero un preajuste en config.toml y luego referencia su alias:
# ~/.vibe/config.toml
[[models]]
name = "codestral-latest"
provider = "mistral"
alias = "codestral"
# en el archivo del agente
active_model = "codestral"
Sin active_model, el agente usa el modelo de la sesión.
Redacción de instrucciones
Existen dos caminos. instructions contiene texto en línea añadido después del prompt del sistema de Vibe: este es el enfoque más sencillo. system_prompt_id apunta a un archivo Markdown en la carpeta prompts/, útil para prompts largos revisados en revisiones de código. Un detalle de comportamiento es importante: el prompt de un agente personalizado solo se aplica si lo seleccionas antes de tu primer mensaje (mediante --agent o Shift+Tab). Si cambias de agente a mitad de sesión, sus herramientas, permisos y modelo se aplican de inmediato, pero su prompt solo surtirá efecto después de /clear.
Mejores prácticas
Mínimo privilegio primero: da al agente solo las herramientas que necesita. Un agente de análisis no necesita write_file; un escritor no necesita bash. Eliminar cada herramienta hace imposible toda una categoría de errores.
Un agente por responsabilidad después: un archivo comodín produce respuestas mediocres en todas partes. Tres archivos específicos valen más que uno genérico.
Instrucciones precisas finalmente: define el rol exacto, las convenciones del proyecto, el formato de salida esperado y los errores a evitar. Cuando un agente decepciona, casi siempre es porque falta uno de estos cuatro puntos.
Puntos clave
- Un agente personalizado es un archivo
.tomlen~/.vibe/agents/o./.vibe/agents/; su nombre coincide con el del archivo - Claves útiles:
display_name,description,instructionsosystem_prompt_id,active_model,enabled_tools,disabled_tools,[tools.<tool>] - Nombres de herramientas:
read_file,write_file,edit,bash,grep,todo,task,skill,ask_user_question,web_fetch,web_search active_modelespera un alias de preajuste de modelo (omistral-medium-3.5, integrado)- Coloca los bloques
[tools.*]al final del archivo