Cursor Background Agents en 2026: tutorial para ejecutar código en paralelo en la nube

Los Background Agents son la novedad estrella de Cursor en 2026: agentes autónomos que se lanzan desde el IDE, se ejecutan en la nube dentro de un sandbox aislado y vuelven con un pull request listo para revisar. Puedes despachar un refactor masivo, una migración de dependencias o una batería de tests, cerrar el portátil e irte a comer; cuando abras GitHub, el trabajo estará hecho. En esta guía práctica veremos cómo activarlos paso a paso, cómo escribir un .cursorrules que los guíe bien y cómo revisar los PR automáticos sin llevarte sorpresas.

Qué son los Background Agents de Cursor

Los Background Agents son instancias remotas de Composer 2 que Cursor lanza en su propia infraestructura cloud. A diferencia del Agent Mode que usas dentro del editor, un Background Agent no consume tu CPU ni bloquea el hilo del IDE: se ejecuta en un contenedor con acceso a una copia efímera de tu repositorio, hace su trabajo (leer código, modificar archivos, correr tests, lanzar comandos) y al terminar abre un pull request en GitHub con el diff completo, un resumen en lenguaje natural y los logs de la sesión.

Este cambio de paradigma es sutil pero enorme. Hasta ahora, delegar una tarea a un agente de IA significaba quedarte mirando cómo trabajaba, con el editor secuestrado y el ventilador rugiendo. Con Background Agents, la tarea se convierte en un asyncio: tú sigues programando cosas más interesantes o abres otra rama, y el agente notifica cuando ha terminado. Es como pasar de threads bloqueantes a procesos desacoplados. Si vienes de nuestra guía de Cursor 3 y Composer 2, este tutorial es la continuación natural: aquí nos centramos en lo que ocurre fuera del editor.

Background Agents vs Composer/Agent Mode local

Muchos desarrolladores confunden los tres modos al empezar. Este cuadro deja las diferencias claras:

Regla mental: si la tarea cabe en un café y quieres ver cómo se hace, usa Composer o Agent Mode. Si la tarea son varias horas y quieres seguir con otra cosa (o irte a dormir), es un Background Agent.

Cómo activarlos y prerequisitos

Los Background Agents no están en el plan gratuito. Antes de empezar necesitas cumplir estos puntos:

• Plan Cursor Pro o Business activo en tu cuenta.
• Cursor 2026 instalado y actualizado (versión con Composer 2). Si sigues en Cursor 2, revisa nuestra guía base de Cursor para migrar.
• GitHub App de Cursor instalada en el repo o la organización donde vayas a trabajar. Sin ella, el agente no puede abrir PRs.
• Rama por defecto limpia. Los Background Agents parten del último commit de main (o del que indiques). Si tu main está roto, el agente heredará los errores.
• Un archivo .cursorrules bien redactado. Técnicamente es opcional, pero sin él los resultados son mucho peores.
• Conexión estable para lanzar y monitorizar; una vez lanzado, el agente sigue aunque cierres el portátil.

Tutorial paso a paso

Vamos con la parte práctica. Los ocho pasos siguientes cubren todo el ciclo, desde actualizar Cursor hasta iterar sobre la PR devuelta.

Paso 1: Actualizar Cursor a la versión 2026 con Background Agents

1. Abre Cursor y ve a Cursor → Check for Updates (macOS) o Help → Check for Updates (Windows y Linux).
2. Comprueba que la versión es al menos Cursor 2026.6. Debajo del número de build debe aparecer el sello “Composer 2 · Background Agents”.
3. Reinicia el editor y verifica que en la barra lateral aparece el icono del robót con la nubecita. Si no está, revisa que tu cuenta tenga plan Pro activo.

Paso 2: Conectar GitHub y dar permisos

1. Pulsa el icono de Background Agents en la barra lateral. Cursor te llevará a un asistente de configuración.
2. Elige Connect GitHub. Se abre el navegador con la instalación de la GitHub App oficial de Cursor.
3. Selecciona la organización o cuenta personal y marca Only select repositories. Nunca des acceso a "All repositories" salvo que sepas exactamente lo que estás permitiendo.
4. Confirma los permisos: lectura de código, escritura de ramas y pull requests. Cursor no necesita permisos de admin, y si te los pide algo va mal.
5. Al volver al IDE, el asistente muestra los repos conectados. Marca los que quieras habilitar para Background Agents.

Paso 3: Crear un .cursorrules bien estructurado

Un Background Agent hereda todo lo que ponga en .cursorrules: convenciones, estilo, tests obligatorios, dependencias prohibidas. Este archivo es la diferencia entre un PR til y un PR desastroso. Ejemplo real que uso en un proyecto Flask:

# Contexto
Este es un backend Flask 3.0 + MongoDB con Pydantic v2.
Python 3.12. La app se despliega en un servidor Ubuntu 24.04.

# Estilo
- Formatea siempre con `ruff format` (line-length 100).
- Todas las funciones públicas llevan type hints y docstring corto.
- Usa `pathlib.Path`, nunca `os.path`.
- Nombres de variables y funciones en snake_case; clases en PascalCase.

# Arquitectura
- Controladores en `app/routes/`, servicios en `app/services/`, modelos Pydantic en `app/models/`.
- No inyectes lógica de negocio en los controladores.
- Los tests van en `tests/`, replicando la estructura de `app/`.

# Reglas duras
- Nunca instales dependencias nuevas sin justificarlo en el PR.
- No commitees claves ni tokens: revisa `.env.example` antes de terminar.
- Cada PR debe pasar `pytest`, `ruff check` y `mypy` sin errores.
- Si tocas endpoints, actualiza `docs/api.md`.

# Comunicación
- Escribe los mensajes de commit en español, imperativo, tipo conventional commits.
- En el resumen de la PR, incluye un apartado "Riesgos" con lo que puede romperse.

Consejos para redactarlo bien: sé específico, pon ejemplos, y sobre todo escribe reglas verificables ("pasa pytest", no "escribe código bonito"). El agente aplica reglas concretas mucho mejor que principios abstractos.

Paso 4: Lanzar tu primer Background Agent (ejemplo: refactor de un módulo)

1. En el sidebar de Background Agents, pulsa New Agent.
2. Rellena el formulario:
   • Repository: el repo objetivo.
   • Base branch: normalmente main.
   • Target branch: refactor/servicio-usuarios (el agente la creará si no existe).
   • Task: la descripción concreta de lo que quieres.
3. Ejemplo de prompt sólido para un refactor:

   Refactoriza `app/services/user_service.py`:
   - Divide la clase `UserService` en `UserQueryService` (solo lectura) y `UserCommandService` (mutaciones).
   - Extrae los helpers de validación a `app/services/user/validators.py`.
   - Mantén compatibilidad con los llamantes: crea un `app/services/user/__init__.py` que reexporte los símbolos públicos.
   - Actualiza los tests en `tests/services/test_user_service.py` para reflejar la nueva estructura.
   - Ejecuta `pytest tests/services/` al final; si algo falla, corrígelo.
   

4. Opcional: sube un init script (por ejemplo scripts/agent-bootstrap.sh) que instale dependencias, semillas de base de datos y variables de entorno de test. El sandbox lo ejecuta antes de dar el control al agente.
5. Pulsa Launch. El agente arranca, aparece con estado Booting en el sidebar y en menos de un minuto pasa a Working.

Paso 5: Monitorizar el progreso desde el sidebar

Mientras el agente trabaja, no estás ciego. En el panel lateral tienes:

• Timeline en vivo: cada acción (leer archivo, ejecutar comando, editar diff) aparece como una entrada con timestamp.
• Terminal en streaming: puedes ver la salida de pytest, ruff o cualquier comando que el agente lance, como si fuera un CI.
• Diff parcial: en cualquier momento puedes pinchar en "View diff" y ver el estado del working tree del sandbox.
• Intervención manual: si ves que se está desviando, pulsa Interrupt, escribe una corrección en el chat contextual ("Deja los helpers en el mismo archivo") y el agente continúa con la nueva directriz.

Esta capacidad de “ver de reojo” sin abrir el sandbox convierte la delegación en algo mucho menos ansiógeno.

Paso 6: Revisar el PR generado

Cuando el agente termina, hace tres cosas:

1. Empuja la rama a GitHub.
2. Abre una pull request con título y descripción autogenerados (siguiendo tu .cursorrules).
3. Adjunta como comentario un resumen ejecutivo con los archivos tocados, decisiones tomadas y riesgos.

Recibes una notificación en el editor y en GitHub. La revisión humana es exactamente igual que la de un compañero, con dos matices útiles:

• Pincha en el enlace “Trace” que Cursor añade al PR y verás exactamente qué archivos leyó y qué comandos ejecutó. Es un log auditable, muy cómodo para revisiones de seguridad.
• Puedes responder al PR con instrucciones (“Usa logging en vez de print”) y volver a lanzar el agente sobre la misma rama con Continue Agent.

Paso 7: Merge, rechazar o iterar

Aquí hay tres decisiones posibles:

• Merge directo: si el PR pasa CI, cubre lo que pedías y el diff se lee bien, mérgealo como cualquier otro. Recuerda mantener la disciplina de squash o rebase de tu equipo.
• Iterar: en el 60% de los casos querrás pulir algo. Comenta en el PR (o desde el chat del agente en Cursor) y pulsa Continue Agent. El sandbox se relanza sobre la misma rama, incorporando tu feedback.
• Rechazar: si el enfoque es erróneo o los cambios rompen supuestos importantes, cierra el PR y borra la rama. No pasa nada: el coste emocional de tirar trabajo de un agente es cero.

Este ciclo de lanzar → revisar → iterar se parece más a gestionar un colaborador junior asignado a una tarea acotada que a usar un autocompletado. La curva de aprendizaje real es aprender a redactar buenos prompts iniciales y buenos comentarios de revisión.

Paso 8: Buenas prácticas y límites

• Una tarea, un agente. No pidas a un mismo Background Agent “refactoriza X y además escribe tests para Y”. Divide y lanza dos en paralelo.
• Prompts con criterios de éxito: “el PR debe pasar pytest y no añadir dependencias” es mucho más útil que “hazlo bien”.
• Init scripts idempotentes: el bootstrap del sandbox se puede lanzar varias veces si hay reintentos; que no falle al ejecutarse dos veces.
• Evita tareas con estado externo crítico: si el agente necesita hablar con una base de datos de producción, no lo hagas. Dale una copia sintética.
• Revisa el trace en PRs sensibles: es la mejor herramienta para detectar acciones inesperadas.
• No delegues decisiones de diseño: los Background Agents son excelentes ejecutando, mediocres decidiendo. La arquitectura sigue siendo tuya.

Casos de uso ideales

Estas son las tareas donde los Background Agents brillan y donde ya se están usando en equipos reales:

• Refactors masivos: división de módulos monolíticos, cambio de patrones (por ejemplo, de callbacks a async/await), renombrados globales con actualización de imports y tests.
• Migraciones de dependencias: subir de Pydantic v1 a v2, de React 18 a 19, de Node 20 a 22. Tareas mecánicas, ruidosas y perfectamente auditables por diff.
• Generación masiva de tests: cobertura para carpetas huérfanas. El agente lee código, infiere el contrato y escribe pruebas unitarias básicas.
• Actualización de docs: docstrings ausentes, README obsoleto, ejemplos rotos. Un agente barre el repo y abre PR con la documentación al día.
• Depuración de deuda técnica: quitar TODOs antiguos, eliminar código muerto detectado por linters, migrar helpers duplicados a módulos comunes.
• Tareas nocturnas: lanzar cinco agentes a las 22:00 y encontrar cinco PRs listos para revisar a las 8:00. La primera hora del día pasa de "pensar qué hago" a "reviso, mergeo y decido lo siguiente".

Si combinas esto con nuestra guía de frameworks de agentes autónomos, ves claro que el ciclo "delegar → revisar" se está convirtiendo en el patrón dominante del desarrollo profesional en 2026.

Costes y límites

Los Background Agents consumen recursos cloud reales (contenedores, modelos grandes tipo Claude Opus 4.8 o GPT-5.5, minutos de ejecución) y por eso Cursor los factura como parte de sus planes Pro y Business, con un cupo mensual y opción de comprar créditos extra. Los planes, límites de horas de agente, tamaño máximo de sandbox y coste de créditos adicionales cambian con frecuencia; para tener el dato exacto y actualizado, consulta la página oficial de precios en cursor.com antes de comprometerte con un uso intensivo.

Algunas consideraciones prácticas independientes del precio:

• Los sandboxes tienen un límite de duración. Tareas gigantescas (por ejemplo, migrar 1.500 archivos) conviene trocearlas en varios agentes.
• El tamaño del repo influye: monorepos enormes hacen que el clone y la indexación inicial consuman minutos.
• Modelos más potentes (Claude Opus 4.8) suelen dar mejores resultados pero consumen más crédito por tarea que modelos más ligeros. Para tareas mecánicas puedes bajar de gama.

Comparativa con GitHub Copilot Workspace y Claude Managed Agents

Cursor no es el único que apuesta por agentes cloud en 2026. Estas son las tres propuestas dominantes:

Para entender qué son los Claude Managed Agents en profundidad revisa nuestro análisis de Claude Managed Agents. La elección rara vez es excluyente: muchos equipos usan Cursor Background Agents para el flujo interactivo y Claude Managed Agents para pipelines desatendidos.

Errores comunes y troubleshooting

Estos son los tropiezos más frecuentes al empezar y cómo resolverlos:

• "The agent could not clone the repo": la GitHub App no tiene acceso al repo. Ve a github.com/settings/installations y añade el repositorio.
• Tests fallan solo en el sandbox: casi siempre son variables de entorno. Duplica tu .env.example, marca las claves críticas y explícalas en el init script.
• El agente instala 15 dependencias nuevas: falta una regla clara en .cursorrules. Añade "No instales dependencias sin explicarlo en el PR" y volverá al buen camino.
• El PR es enorme y toca todo: la tarea era demasiado abierta. Divide en objetivos concretos ("solo reorganiza app/services/") y relanza.
• Timeouts en tareas largas: reparte en varios agentes con criterios claros de dependencia entre ramas.
• Cambios silenciosos en config o CI: mira siempre el trace y añade a .cursorrules qué carpetas están prohibidas (por ejemplo .github/workflows/).
• PRs que se pisan entre sí: si lanzas dos agentes tocando el mismo módulo, prepárate para resolver conflictos manualmente. Mejor separar por carpeta.

Material recomendado para trabajar con Background Agents

Delegar tareas a agentes en la nube cambia la manera de trabajar: pasas más tiempo leyendo diffs y revisando PRs que escribiendo cada línea. Estos productos ayudan a hacerlo cómodo durante horas. Enlaces de afiliado verificados con tag Amazon webmasteroson-21:

• Monitor LG 29WP60G-B ultrawide 29" con USB-C: panel 21:9 ideal para tener el editor y el PR de GitHub uno al lado del otro sin cambiar de ventana. Ver precio actual en Amazon.
• Monitor BenQ RD280U 4K específico para programación: proporción 3:2, modo Coding y tratamiento anti-reflejos; una gozada para leer código denso y logs de agente. Ver precio actual en Amazon.
• Teclado Logitech MX Keys inalámbrico: tecleo silencioso y cómodo para redactar prompts y comentarios de revisión durante horas sin fatiga. Ver precio actual en Amazon.
• Ratón Logitech MX Master 3S: el estándar de oro en productividad; su scroll rápido acelera mucho la revisión de diffs largos. Ver precio actual en Amazon.
• Webcam Logitech Brio Stream 4K: imagen nítida para las llamadas de revisión de PR con el equipo, especialmente si trabajas en remoto. Ver precio actual en Amazon.
• Silla Secretlab TITAN Evo: pensada para sesiones largas de escritorio; soporte lumbar 4 vías y reposabrazos 4D. Ver precio actual en Amazon.
• Libro "El arte de la Ingeniería de Prompts con ChatGPT": mejora directamente la calidad de las instrucciones que envías a tus Background Agents. Ver precio actual en Amazon.

Conclusión

Los Background Agents rompen la máxima de “un IDE, un desarrollador, una tarea”. Ahora eres tú más un enjambre de agentes trabajando en paralelo, cada uno en su rama, cada uno abriendo su PR. La parte técnica de activarlos es sencilla; la interesante es la de cambiar tu flujo mental: escribir prompts muy claros, mantener .cursorrules vivo y aceptar que gran parte de tu jornada será leer diffs y decidir qué se mergea.

Si empiezas con una tarea acotada esta misma semana (por ejemplo, generar tests de una carpeta huérfana) y vas ampliando cuando cojas confianza, en pocos días habrás multiplicado tu productividad sin renunciar a la revisión humana. Ese equilibrio es la clave: agentes ejecutando, humanos decidiendo.

Preguntas frecuentes (FAQ)

Los enlaces de esta página son enlaces de afiliado. Si compras a través de ellos, Arkaia recibe una pequeña comisión sin coste adicional para ti, lo que nos ayuda a seguir creando contenido. Gracias por tu apoyo.