Agentes

Los agentes son asistentes de IA especializados que pueden configurarse para tareas y flujos de trabajo específicos. Te permiten crear herramientas enfocadas con indicaciones personalizadas, modelos y acceso a herramientas.

Puedes cambiar entre agentes durante una sesión o invocarlos con la mención @.

Tipos

Hay dos tipos de agentes en Dropstone: agentes primarios y subagentes.

Agentes primarios

Los agentes primarios son los asistentes principales con los que interactúas directamente. Puedes cambiar entre ellos usando la tecla Tab, o tu keybind switch_agent configurado. Estos agentes manejan tu conversación principal. El acceso a herramientas se configura mediante permisos: por ejemplo, Build tiene todas las herramientas habilitadas mientras que Plan está restringido.

Dropstone viene con dos agentes primarios integrados, Build y Plan. Los veremos a continuación.

Subagentes

Los subagentes son asistentes especializados que los agentes primarios pueden invocar para tareas específicas. También puedes invocarlos manualmente mencionándolos con @ en tus mensajes.

Dropstone viene con dos subagentes integrados, General y Explore. Los veremos a continuación.

Integrados

Dropstone viene con dos agentes primarios integrados y dos subagentes integrados.

Usar build

Modo: primary

Build es el agente primario predeterminado con todas las herramientas habilitadas. Este es el agente estándar para trabajo de desarrollo donde necesitas acceso completo a operaciones de archivos y comandos del sistema.

Usar plan

Modo: primary

Un agente restringido diseñado para planificación y análisis. Utilizamos un sistema de permisos para darte más control y prevenir cambios no intencionados. Por defecto, todos los siguientes están configurados en ask:

• file edits: Todas las escrituras, parches y ediciones
• bash: Todos los comandos bash

Este agente es útil cuando quieres que el LLM analice código, sugiera cambios o cree planes sin realizar modificaciones reales en tu base de código.

Usar general

Modo: subagent

Un agente de propósito general para investigar preguntas complejas y ejecutar tareas de múltiples pasos. Tiene acceso completo a herramientas (excepto todo), por lo que puede realizar cambios en archivos cuando sea necesario. Úsalo para ejecutar múltiples unidades de trabajo en paralelo.

Usar explore

Modo: subagent

Un agente rápido y de solo lectura para explorar bases de código. No puede modificar archivos. Úsalo cuando necesites encontrar rápidamente archivos por patrones, buscar código por palabras clave o responder preguntas sobre la base de código.

Usar compaction

Modo: primary

Agente del sistema oculto que compacta contexto largo en un resumen más pequeño. Se ejecuta automáticamente cuando es necesario y no es seleccionable en la interfaz de usuario.

Usar title

Modo: primary

Agente del sistema oculto que genera títulos cortos de sesión. Se ejecuta automáticamente y no es seleccionable en la interfaz de usuario.

Usar summary

Modo: primary

Agente del sistema oculto que crea resúmenes de sesión. Se ejecuta automáticamente y no es seleccionable en la interfaz de usuario.

Uso

1. Para agentes primarios, usa la tecla Tab para cambiar entre ellos durante una sesión. También puedes usar tu keybind switch_agent configurado.

2. Los subagentes pueden invocarse:

   • Automáticamente por agentes primarios para tareas especializadas basadas en sus descripciones.

   • Manualmente mencionando con @ un subagente en tu mensaje. Por ejemplo.

     @general ayúdame a buscar esta función
     

3. Navegación entre sesiones: Cuando los subagentes crean sesiones secundarias, usa session_child_first (predeterminado: <Leader>+Down) para entrar en la primera sesión secundaria desde la principal.

4. Una vez que estés en una sesión secundaria, usa:

   • session_child_cycle (predeterminado: Right) para cambiar a la siguiente sesión secundaria
   • session_child_cycle_reverse (predeterminado: Left) para cambiar a la sesión secundaria anterior
   • session_parent (predeterminado: Up) para volver a la sesión principal

   Esto te permite cambiar entre la conversación principal y el trabajo especializado del subagente.

Configurar

Puedes personalizar los agentes integrados o crear los tuyos propios a través de la configuración. Los agentes pueden configurarse de dos formas:

JSON

Configura agentes en tu archivo de configuración dropstone.json:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "dropstone/dropstone-pro",
      "prompt": "{file:./prompts/build.txt}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "dropstone/dropstone-fast",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "dropstone/dropstone-pro",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

Markdown

También puedes definir agentes usando archivos markdown. Colócalos en:

• Global: ~/.config/dropstone/agents/
• Por proyecto: .dropstone/agents/

---
description: Reviews code for quality and best practices
mode: subagent
model: dropstone/dropstone-pro
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

El nombre del archivo markdown se convierte en el nombre del agente. Por ejemplo, review.md crea un agente review.

Opciones

Veamos estas opciones de configuración en detalle.

Descripción

Usa la opción description para proporcionar una breve descripción de lo que hace el agente y cuándo usarlo.

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Esta es una opción de configuración requerida.

Temperatura

Controla la aleatoriedad y creatividad de las respuestas del LLM con la configuración temperature.

Los valores más bajos hacen que las respuestas sean más enfocadas y deterministas, mientras que los valores más altos aumentan la creatividad y variabilidad.

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Los valores de temperatura típicamente van de 0.0 a 1.0:

• 0.0-0.2: Respuestas muy enfocadas y deterministas, ideales para análisis de código y planificación
• 0.3-0.5: Respuestas equilibradas con algo de creatividad, buenas para tareas generales de desarrollo
• 0.6-1.0: Respuestas más creativas y variadas, útiles para lluvia de ideas y exploración

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Si no se especifica temperatura, Dropstone utiliza un valor predeterminado sensato ajustado para cada nivel.

Máximo de pasos

Controla el número máximo de iteraciones agentic que un agente puede realizar antes de ser forzado a responder solo con texto. Esto permite a los usuarios que deseen controlar costos establecer un límite en acciones agentic.

Si esto no está configurado, el agente continuará iterando hasta que el modelo elija detenerse o el usuario interrumpa la sesión.

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

Cuando se alcanza el límite, el agente recibe un indicador del sistema especial instruyéndole que responda con un resumen de su trabajo y tareas recomendadas restantes.

Deshabilitar

Establece en true para deshabilitar el agente.

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Indicación

Especifica un archivo de indicación del sistema personalizado para este agente con la configuración prompt. El archivo de indicación debe contener instrucciones específicas para el propósito del agente.

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Esta ruta es relativa a donde se encuentra el archivo de configuración. Así que funciona tanto para la configuración global de Dropstone como para la configuración específica del proyecto.

Modelo

Usa la configuración model para anular el modelo para este agente. Útil para usar diferentes modelos optimizados para diferentes tareas. Por ejemplo, un modelo más rápido para planificación, un modelo más capaz para implementación.

{
  "agent": {
    "plan": {
      "model": "dropstone/dropstone-fast"
    }
  }
}

El ID del modelo usa el formato dropstone/<tier>. Usa dropstone/dropstone-fast, dropstone/dropstone-pro, o dropstone/dropstone-heavy.

Herramientas (deprecado)

tools está deprecado. Prefiere el campo permission del agente para nuevas configuraciones, actualizaciones y control más granular.

Te permite controlar qué herramientas están disponibles en este agente. Puedes habilitar o deshabilitar herramientas específicas configurándolas en true o false. En la configuración tools de un agente, true es equivalente a {"*": "allow"} permiso y false es equivalente a {"*": "deny"} permiso.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

También puedes usar comodines en entradas heredadas de tools para controlar múltiples herramientas a la vez. Por ejemplo, para deshabilitar todas las herramientas de un servidor MCP:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Aprende más sobre herramientas.

Permisos

Puedes configurar permisos para gestionar qué acciones puede realizar un agente. Cada clave de permiso puede establecerse en:

• "ask": Solicitar aprobación antes de ejecutar la herramienta
• "allow": Permitir todas las operaciones sin aprobación
• "deny": Deshabilitar la herramienta

Las claves de permiso disponibles son:

read, edit, glob, grep, list, bash, task, external_directory, lsp, y skill aceptan ya sea una acción abreviada ("allow" | "ask" | "deny") u un objeto de glob/patrón → acción para control granular. Las claves restantes aceptan solo la acción abreviada.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "edit": "deny"
  }
}

Puedes anular estos permisos por agente.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

También puedes establecer permisos en agentes Markdown.

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.

Puedes establecer permisos para comandos bash específicos.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Esto puede tomar un patrón glob.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

Y también puedes usar el comodín * para gestionar permisos para todos los comandos. Dado que la última regla coincidente tiene precedencia, pon el comodín * primero y reglas específicas después.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Aprende más sobre permisos.

Modo

Controla el modo del agente con la configuración mode. La opción mode se utiliza para determinar cómo se puede usar el agente.

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

La opción mode puede establecerse en primary, subagent, o all. Si no se especifica mode, por defecto es all.

Oculto

Oculta un subagente del menú de autocompletado @ con hidden: true. Útil para subagentes internos que solo deben ser invocados programáticamente por otros agentes a través de la herramienta Task.

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Esto solo afecta la visibilidad del usuario en el menú de autocompletado. Los agentes ocultos aún pueden ser invocados por el modelo a través de la herramienta Task si los permisos lo permiten.

Permisos de tarea

Controla qué subagentes puede invocar un agente a través de la herramienta Task con permission.task. Usa patrones glob para coincidencia flexible.

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Cuando se establece en deny, el subagente se elimina completamente de la descripción de la herramienta Task, por lo que el modelo no intentará invocarlo.

Color

Personaliza la apariencia visual del agente en la interfaz de usuario con la opción color. Esto afecta cómo aparece el agente en la interfaz.

Usa un color hex válido (p. ej., #FF5733) o color de tema: primary, secondary, accent, success, warning, error, info.

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Controla la diversidad de respuestas con la opción top_p. Alternativa a temperatura para controlar la aleatoriedad.

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Los valores van de 0.0 a 1.0. Los valores más bajos son más enfocados, los valores más altos más diversos.

Adicional

Cualquier otra opción que especifiques en tu configuración de agente se pasa directamente como opciones de modelo. Para los niveles de Dropstone, las opciones de paso directo soportadas son profundidad de razonamiento y verbosidad de texto:

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "dropstone/dropstone-heavy",
      "variant": "xhigh",
      "textVerbosity": "low"
    }
  }
}

Crear agentes

Puedes crear nuevos agentes usando el siguiente comando:

dropstone agent create

Este comando interactivo:

1. Te preguntará dónde guardar el agente; global o específico del proyecto.
2. Descripción de lo que debe hacer el agente.
3. Genera un indicador del sistema apropiado e identificador.
4. Te permite seleccionar qué permisos debe tener el agente (cualquier cosa que no selecciones se deniega).
5. Finalmente, crea un archivo markdown con la configuración del agente.

Casos de uso

Aquí hay algunos casos de uso comunes para diferentes agentes.

• Agente Build: Trabajo de desarrollo completo con todas las herramientas habilitadas
• Agente Plan: Análisis y planificación sin realizar cambios
• Agente Review: Revisión de código con acceso de solo lectura más herramientas de documentación
• Agente Debug: Enfocado en investigación con herramientas bash y read habilitadas
• Agente Docs: Escritura de documentación con operaciones de archivo pero sin comandos del sistema

Ejemplos

Aquí hay algunos agentes de ejemplo que podrías encontrar útiles.

Agente de documentación

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Auditor de seguridad

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues