CÓMO CREAR UN CUSTOM AGENT EN GOOGLE ANTIGRAVITY

Introducción a los Custom Agents en Antigravity

Un Custom Agent es un agente especializado que se define mediante un archivo de configuración sencillo. Permite crear roles específicos con instrucciones, herramientas y políticas de seguridad propias, mejorando la precisión y la eficiencia respecto a un agente genérico.

En Google Antigravity (tanto en la versión 2.0 como en la CLI), los Custom Agents se crean con un único archivo Markdown que incluye una cabecera YAML.

Ubicación de los archivos de Custom Agent

Antigravity detecta automáticamente los agentes en las siguientes rutas:

  • Workspace (recomendado para equipos): ".agents/agents/<nombre>.md" o ".agents/agents/<nombre>/agent.md"
  • Global (disponible en todos los proyectos): ".~/.gemini/config/agents/<nombre>.md" o "~/.gemini/config/agents/<nombre>/agent.md"

Al guardar el archivo en la carpeta del proyecto, el Custom Agent queda disponible para todo el equipo a través de Git.

Estructura básica de un Custom Agent

El archivo se compone de dos partes: la cabecera YAML (entre triples guiones) y el cuerpo en Markdown, que se convierte en el system prompt del agente.

Ejemplo completo

---
name: dependency-modernizer
description: Ayuda a actualizar paquetes locales y verificar que las pruebas del proyecto pasen.
model: flash
tools:
- view_file
- replace_file_content
- manage_task
- run_command
mainAgent: true
subagent: true
commandExecutionPolicy: auto
---

# Instrucciones principales
Eres un especialista en modernización de dependencias.
Tu trabajo consiste en revisar los archivos de configuración, 
actualizar las dependencias objetivo, ejecutar las suites de pruebas 
y verificar que el build se complete correctamente.

Propiedades principales de la cabecera YAML

  • name (obligatorio): Identificador único del agente.
  • description (obligatorio): Descripción detallada que utiliza el planificador para decidir cuándo delegar tareas.
  • tools: Lista de herramientas permitidas (por ejemplo, view_file, run_command, grep_search).
  • mainAgent: Si es true, permite seleccionarlo como agente principal.
  • subagent: Si es true, permite invocarlo como subagente.
  • model: Modelo a utilizar (flash, pro o inherit).
  • commandExecutionPolicy: Política de ejecución de comandos (off, auto, eager, sandbox).
  • skills: Rutas a skills específicas que el agente puede utilizar.

Pasos para crear un Custom Agent

  1. Crear la carpeta .agents/agents/ en la raíz del proyecto (si no existe).
  2. Crear un archivo con extensión .md (por ejemplo, dependency-modernizer.md).
  3. Añadir la cabecera YAML con las propiedades deseadas.
  4. Escribir las instrucciones del agente en el cuerpo del archivo usando Markdown.
  5. Guardar el archivo. Antigravity lo detectará automáticamente.
  6. Seleccionar el nuevo agente desde el desplegable de la interfaz o lanzarlo mediante la CLI con agy --agent nombre-del-agente.

Consejos para un buen Custom Agent

  • Mantener las instrucciones claras, concisas y orientadas a un único rol.
  • Limitar las herramientas solo a las necesarias para evitar confusión y reducir el consumo de tokens.
  • Utilizar commandExecutionPolicy: auto cuando el agente deba ejecutar comandos de test o build de forma recurrente.
  • Incluir ejemplos de comportamiento esperado dentro de las instrucciones.
  • Probar el agente tanto como agente principal como subagente.

Conclusión

Crear un Custom Agent en Google Antigravity es un proceso sencillo que requiere únicamente un archivo Markdown con cabecera YAML. Esta capacidad permite especializar agentes para tareas concretas, mejorar la fiabilidad y estandarizar flujos de trabajo dentro de un equipo.

Con una configuración adecuada, los Custom Agents se convierten en colaboradores reutilizables y altamente eficientes dentro del ecosistema agentic de Antigravity.