Ir al contenido principal
Español— Elegir un idioma
Menú

Crear un agente personalizado en TOML

Lección 2 de 14 Actualizado el 2 de noviembre de 2026 Avanzado
En esta página
  1. Más allá de los agentes integrados
  2. Claves del archivo de agente
  3. Herramientas que puedes nombrar
  4. Primer agente: El planificador
  5. Un agente de documentación
  6. Elección del modelo del agente
  7. Redacción de instrucciones
  8. Mejores prácticas
  9. Puntos clave

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

ClaveFunción
agent_type"agent" (predeterminado, seleccionable por el usuario) o "subagent" (lanzado solo por delegación)
display_name, descriptionNombre visible y descripción; la descripción es obligatoria para un subagente
instructionsInstrucciones en línea añadidas después del prompt del sistema (para un subagente, lo sustituyen)
system_prompt_idNombre de un archivo Markdown en ~/.vibe/prompts/ o ./.vibe/prompts/, sin la extensión
active_modelAlias del modelo que usará este agente
enabled_tools, disabled_toolsLista 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
safetyIndicador 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 .toml en ~/.vibe/agents/ o ./.vibe/agents/; su nombre coincide con el del archivo
  • Claves útiles: display_name, description, instructions o system_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_model espera un alias de preajuste de modelo (o mistral-medium-3.5, integrado)
  • Coloca los bloques [tools.*] al final del archivo