Subagentes

Los subagentes son asistentes de IA especializados a los que el agente de Cursor puede delegar tareas. Cada subagente opera en su propia ventana de contexto, se encarga de tipos de trabajo específicos y devuelve el resultado al agente principal. Usa subagentes para dividir tareas complejas, trabajar en paralelo y conservar el contexto en la conversación principal.

Puedes usar subagentes en el Editor, la CLI y los agentes en la nube.

Cómo funcionan los subagentes

Cuando el agente de programación se enfrenta a una tarea compleja, puede iniciar automáticamente un subagente. El subagente recibe una instrucción con todo el contexto necesario, trabaja de forma autónoma y devuelve un mensaje final con los resultados.

Los subagentes comienzan con un contexto limpio. El agente de programación principal incluye la información relevante en la instrucción, ya que los subagentes no tienen acceso al historial de conversaciones previo.

Primer plano vs. segundo plano

Los subagentes se ejecutan en uno de estos dos modos:

Subagentes integrados

Cursor incluye tres subagentes integrados que gestionan automáticamente operaciones que requieren mucho contexto. Estos subagentes se diseñaron a partir del análisis de conversaciones con agentes de programación en las que se alcanzaron los límites de la ventana de contexto.

Por qué existen estos subagentes

Estas tres operaciones comparten rasgos: generan una salida intermedia ruidosa, se benefician de instrucciones y herramientas especializadas y pueden consumir mucho contexto. Ejecutarlas como subagentes resuelve varios problemas:

• Aislamiento del contexto — La salida intermedia se mantiene en el subagente. El agente principal solo ve el resumen final.
• Flexibilidad del modelo — El subagente de exploración usa un modelo más rápido de forma predeterminada. Esto permite ejecutar 10 búsquedas en paralelo en el tiempo que tardaría una sola búsqueda del agente principal.
• Configuración especializada — Cada subagente tiene instrucciones y acceso a herramientas adaptados a su tarea específica.
• Eficiencia de costes — Los modelos más rápidos cuestan menos. Aislar en subagentes el trabajo que consume muchos tokens, con modelos adecuados, reduce el coste total.

No necesitas configurar estos subagentes. Agent los usa automáticamente cuando es apropiado.

Cuándo usar subagentes

Inicio rápido

El agente de programación usa subagentes automáticamente cuando corresponde. También puedes crear un subagente personalizado pidiéndoselo al agente de programación:

Para tener mayor control, crea subagentes personalizados manualmente en el directorio de tu proyecto o en tu directorio de usuario.

Subagentes personalizados

Define subagentes personalizados para incorporar conocimientos especializados, aplicar los estándares del equipo o automatizar flujos de trabajo repetitivos.

Ubicaciones de archivos

Los subagentes del proyecto tienen prioridad si hay nombres en conflicto. Cuando varias ubicaciones contienen subagentes con el mismo nombre, .cursor/ tiene prioridad sobre .claude/ y .codex/.

Formato del archivo

Cada subagente es un archivo markdown con frontmatter YAML:

---name: security-auditordescription: Security specialist. Use when implementing auth, payments, or handling sensitive data.model: inheritreadonly: true---You are a security expert auditing code for vulnerabilities.When invoked:1. Identify security-sensitive code paths2. Check for common vulnerabilities (injection, XSS, auth bypass)3. Verify secrets are not hardcoded4. Review input validation and sanitizationReport findings by severity:- Critical (must fix before deploy)- High (fix soon)- Medium (address when possible)

Campos de configuración

Configuración del modelo

El campo model determina qué modelo usa un subagente. Hay dos opciones:

Elige inherit cuando el subagente necesite la misma capacidad de razonamiento que el agente principal. Usa un ID de modelo específico cuando necesites las capacidades de un modelo concreto, independientemente del modelo que use el agente principal.

Parámetros del modelo

Añade corchetes a un ID de modelo para establecer opciones específicas, como velocidad, esfuerzo de razonamiento y ventana de contexto. Escribe las opciones como pares id=value y separa varias opciones con comas.

Las opciones disponibles dependen del modelo y usan los mismos pares id=value que los parámetros del modelo del SDK.

---name: plannerdescription: Plans complex changes before implementation.model: claude-opus-5[effort=high]---Break the task into a clear, ordered implementation plan.

Cuándo no se utilizará el modelo configurado

Cursor respeta el campo model del frontmatter de tu subagente, salvo que se cumpla alguna de estas condiciones:

• Restricciones del administrador del equipo — El administrador de tu organización ha bloqueado el modelo especificado.
• Ajuste heredado de Max Mode — En un plan heredado basado en solicitudes, el modelo requiere Max Mode y no lo tienes activado.
• Limitaciones del plan — El modelo no está disponible en tu plan actual.

En estos casos, Cursor usa un modelo compatible. Si el modelo se comporta de forma inesperada, revisa tu plan y la configuración del modelo.

---name: code-reviewerdescription: Reviews code for correctness and style.model: inherit---Review the code changes for bugs, style issues, and edge cases.

---name: search-agentdescription: Searches the codebase for relevant files and symbols.model: inherit---Search the codebase and return relevant file paths and code snippets.

---name: reasoning-agentdescription: Handles complex architectural decisions.model: gpt-5.6-sol---Analyze the architecture and recommend changes with detailed reasoning.

Uso de subagentes

Delegación automática

El Agent delega tareas de forma proactiva según:

• La complejidad y el alcance de la tarea
• Las descripciones personalizadas de los subagentes de tu proyecto
• El contexto actual y las herramientas disponibles

Incluye expresiones como "usar de forma proactiva" o "usar siempre para" en el campo de descripción para fomentar la delegación automática.

Invocación explícita

Solicita un subagente específico mediante la sintaxis /name en tu instrucción:

> /verifier confirma que el flujo de autenticación está completo> /debugger investiga este error> /security-auditor revisa el módulo de pagos

También puedes invocar subagentes mencionándolos de forma natural:

> Usa el subagente verificador para confirmar que el flujo de autenticación está completo> Pide al subagente depurador que investigue este error> Ejecuta el subagente auditor de seguridad en el módulo de pago

Ejecución paralela

Inicia varios subagentes a la vez para maximizar el rendimiento:

> Revisa los cambios de la API y actualiza la documentación en paralelo

El agente realiza varias llamadas a la herramienta Task en un mismo mensaje, por lo que los subagentes se ejecutan simultáneamente.

Subagentes en la nube

Desde una sesión de agente local, puedes delegar trabajo a un subagente en la nube que se ejecuta en su propia VM y rama. Tu espacio de trabajo local se mantiene limpio y ágil mientras las tareas de larga duración o en paralelo se ejecutan en la nube. El agente principal sigue ejecutándose de forma local o en la nube sin interrupciones. Los subagentes en la nube se ejecutan desde la ventana de agente de programación en la aplicación de escritorio de Cursor.

Inicia un subagente en la nube con /in-cloud

Escribe /in-cloud y la siguiente tarea que envíes se ejecutará como un subagente en la nube. Este iniciará su propia VM y rama para trabajar en ella.

Es útil para aislar tareas de larga duración o en paralelo, como solucionar problemas de CI, investigar un problema o explorar una base de código mientras sigues trabajando localmente.

Supervisa una PR con /babysit

Pide a un subagente en la nube que supervise una solicitud de extracción con /babysit o haciendo clic en el botón de acción rápida. El agente en la nube itera de forma remota para preparar la PR para fusionarla sin ocupar tu sesión local.

Los subagentes en la nube usan el entorno configurado para tu repositorio y siguen las mismas reglas de modelo y funcionalidad que otros agentes en la nube. Como se ejecutan en una VM en la nube, sus servidores MCP provienen de la configuración de tu equipo en cursor.com/agents, no de tu sesión local.

Reanudar subagentes

Puedes reanudar subagentes para continuar conversaciones anteriores. Esto resulta útil para tareas de larga duración que abarcan varias invocaciones.

Cada ejecución de un subagente devuelve un ID de agente. Proporciona este ID para reanudar el subagente conservando todo el contexto:

> Reanuda el agente abc123 y analiza los fallos de las pruebas restantes

Patrones comunes

Agente de verificación

Un agente de verificación valida de forma independiente si el trabajo declarado se completó realmente. Esto resuelve un problema común: la IA marca las tareas como completadas, pero las implementaciones son incompletas o no funcionan.

---name: verifierdescription: Valida el trabajo completado. Úsalo después de marcar las tareas como terminadas para confirmar que las implementaciones funcionan.---Eres un validador escéptico. Tu tarea es verificar que el trabajo que se declara completo realmente funciona.Cuando se te invoque:1. Identifica qué se declaró como completado2. Comprueba que la implementación existe y funciona3. Ejecuta los tests o pasos de verificación relevantes4. Busca casos límite que se hayan podido pasar por altoSé riguroso y escéptico. Informa de:- Qué se verificó y superó las comprobaciones- Qué se declaró como hecho pero está incompleto o roto- Problemas concretos que hay que resolverNo des por buenas las afirmaciones sin más. Pruébalo todo.

Este patrón es útil para:

• Validar que las funcionalidades funcionen de principio a fin antes de marcar los tickets como completados
• Detectar funcionalidades implementadas parcialmente
• Garantizar que las pruebas realmente se superen (no solo que existan archivos de prueba)

Patrón de orquestación

Para flujos de trabajo complejos, un agente principal puede coordinar varios subagentes especializados en secuencia:

1. Planificador analiza los requisitos y crea un plan técnico
2. Implementador desarrolla la funcionalidad según el plan
3. Verificador confirma que la implementación cumple los requisitos

Cada transferencia incluye una salida estructurada para que el siguiente agente disponga de un contexto claro.

Ejemplos de subagentes

Depurador

---name: debuggerdescription: Debugging specialist for errors and test failures. Use when encountering issues.---You are an expert debugger specializing in root cause analysis.When invoked:1. Capture error message and stack trace2. Identify reproduction steps3. Isolate the failure location4. Implement minimal fix5. Verify solution worksFor each issue, provide:- Root cause explanation- Evidence supporting the diagnosis- Specific code fix- Testing approachFocus on fixing the underlying issue, not symptoms.

Ejecutor de pruebas

---name: test-runnerdescription: Experto en automatización de tests. Usar de forma proactiva para ejecutar tests y solucionar fallos.---Eres un experto en automatización de tests.Cuando veas cambios de código, ejecuta de forma proactiva los tests adecuados.Si los tests fallan:1. Analiza la salida del fallo2. Identifica la causa raíz3. Soluciona el problema sin alterar la intención del test4. Vuelve a ejecutarlos para verificarInforma de los resultados de los tests indicando:- Número de tests superados/fallidos- Resumen de los fallos- Cambios realizados para solucionar los problemas

Mejores prácticas

• Crea subagentes especializados — Cada subagente debe tener una única responsabilidad clara. Evita los agentes «auxiliares» genéricos.
• Cuida las descripciones — El campo description determina cuándo Agent delega en tu subagente. Dedica tiempo a perfeccionarlo. Prueba con instrucciones y comprueba si se activa el subagente adecuado.
• Mantén las instrucciones concisas — Las instrucciones largas y divagantes diluyen el enfoque. Sé específico y directo.
• Añade subagentes al control de versiones — Incluye .cursor/agents/ en tu repositorio para que el equipo se beneficie.
• Empieza con agentes generados por Agent — Deja que Agent te ayude a redactar la configuración inicial y, después, personalízala.
• Usa hooks para generar archivos de salida — Si necesitas que los subagentes generen archivos de salida estructurados, considera usar hooks para procesar y guardar sus resultados de forma coherente.

Antipatrones que se deben evitar

• Descripciones vagas — "Usar para tareas generales" no le indica al agente de programación cuándo delegar. Sea específico: "Usar al implementar flujos de autenticación con proveedores de OAuth".
• Instrucciones demasiado largas — Una instrucción de 2000 palabras no hace que un subagente sea más inteligente. Lo hace más lento y difícil de mantener.
• Duplicar comandos con barra — Si una tarea tiene un único propósito y no necesita aislamiento de contexto, use una skill o un comando.
• Demasiados subagentes — Empiece con 2-3 subagentes especializados. Añada más solo cuando tenga casos de uso claros y distintos.

Gestión de subagentes

Crear subagentes

La forma más sencilla de crear un subagente es pedirle a Agent que lo cree por ti:

También puedes crear subagentes manualmente añadiendo archivos Markdown a .cursor/agents/ (proyecto) o ~/.cursor/agents/ (usuario).

Consultar subagentes

El agente incluye todos los subagentes personalizados entre las herramientas disponibles. Puedes consultar qué subagentes están configurados en el directorio .cursor/agents/ de tu proyecto.

Rendimiento y coste

Los subagentes tienen ventajas e inconvenientes. Comprenderlos te ayuda a decidir cuándo utilizarlos.

Consideraciones sobre tokens y coste

• Los subagentes consumen tokens de forma independiente — Cada subagente tiene su propia ventana de contexto y su propio consumo de tokens. Ejecutar cinco subagentes en paralelo consume aproximadamente cinco veces más tokens que un único agente de programación.
• Evalúa la sobrecarga — Para tareas rápidas y sencillas, el agente de programación principal suele ser más rápido. Los subagentes destacan en tareas complejas, de larga duración o que se ejecutan en paralelo.
• Los subagentes pueden ser más lentos — El beneficio es el aislamiento del contexto, no la velocidad. Un subagente que realiza una tarea sencilla puede ser más lento que el agente de programación principal porque parte desde cero.

Preguntas frecuentes