Cómo usar Cursor Agent SDK para crear agentes

Esta guía es para quien quiere crear un agente especializado, por ejemplo, para revisar cambios o organizar una tarea repetitiva. No es un tutorial sobre instalar el editor Cursor ni sobre construir un agente autónomo sin límites.

En este artículo verás:

• Cómo elegir una tarea segura y delimitada.
• Cómo escribir instrucciones que el agente pueda seguir.
• Cómo definir herramientas y evaluaciones.
• Cómo elegir entre ejecución hospedada e infraestructura propia.

Cómo usar Cursor Agent SDK empieza con una tarea delimitada

Elige una tarea repetitiva, con entradas y salidas claras. Un agente de revisión puede recibir un diff y señalar problemas de estilo o riesgos para que la persona los verifique, sin hacer merge automáticamente.

La documentación oficial de Cursor Agent SDK describe agentes definidos como código. Las instrucciones pueden quedar en Markdown, las herramientas pueden implementarse en TypeScript y las evaluaciones ayudan a medir cambios de comportamiento.

El anuncio oficial presenta dos opciones de despliegue: usar la infraestructura hospedada de Cursor o ejecutar el agente en tu propia infraestructura. Esto no significa que los entornos tengan requisitos idénticos. Revisa la documentación antes de decidir dónde el agente debe acceder a datos.

Antes de crear un agente, define el límite de acción

Escribe cuál es la tarea, quién inicia el agente y qué puede leer. Define también qué puede modificar y qué acciones siempre requieren confirmación humana.

Comienza con acceso solo de lectura. Si el agente necesita abrir un pull request o modificar archivos, concede ese permiso después de probar el flujo básico.

No pases credenciales de producción en el prompt ni dejes secretos en archivos de instrucción. Almacena credenciales según el entorno de ejecución y limita cada herramienta a lo que realmente necesita hacer.

Paso 1: escribe instrucciones cortas en Markdown

Separa el rol del agente de las reglas del proyecto. El rol indica qué debe entregar; las reglas indican cómo interpretar entradas, qué caminos evitar y cuándo pedir ayuda.

Un archivo de instrucciones puede especificar: objetivo, formato de entrada, formato de salida, criterios de éxito, límites de acceso y casos que requieren escalamiento. Usa ejemplos cortos para mostrar la diferencia entre una respuesta correcta y una respuesta incompleta.

Evita instrucciones vagas como “revisa bien el código”. Prefiere “señala archivos y líneas afectadas, explica el riesgo y sugiere una corrección, sin editar archivos ni aprobar el cambio”.

Paso 2: crea herramientas TypeScript con permisos mínimos

Cada herramienta debe hacer una acción pequeña y predecible. Por ejemplo, una herramienta puede consultar el diff de un cambio y devolver solo los archivos modificados, mientras que otra verifica el resultado de las pruebas.

Valida la entrada antes de ejecutar una acción. Rechaza rutas fuera del repositorio, limita el tamaño de los datos y maneja respuestas vacías o errores de servicios externos.

Mantén la lectura y la escritura separadas. Una herramienta que analiza un pull request no necesita, por defecto, la capacidad de aprobarlo o publicarlo.

Paso 3: evalúe al agente con casos que pueden fallar

El SDK incluye evaluaciones para medir cambios en el comportamiento del agente. Cree ejemplos que representen tanto el camino esperado como situaciones incompletas, como un diff vacío, una prueba que falló o instrucciones conflictivas.

Para un revisor de código, verifique si identifica un problema real, evita inventar archivos y distingue una sugerencia de una falla confirmada. Incluya casos en los que el agente debe responder que no tiene información suficiente.

Después de cambiar las instrucciones o una herramienta, ejecute los mismos casos nuevamente. Compare los resultados antes de concluir que una versión mejoró. Una evaluación pequeña y repetible es más útil que confiar en la impresión de una sola conversación.

Crédito de la imagen: Cursor, demostración oficial del Agent SDK. La miniatura muestra ejemplos de agentes organizados como carpetas de proyecto.

Mire también la demostración oficial del Cursor Agent SDK, que presenta el modelo de agentes definidos como código.

Paso 4: elija hospedaje con base en los datos y en los permisos

En la opción hospedada, revise qué recursos, datos y herramientas quedan disponibles para el agente. En la opción de infraestructura propia, defina quién mantiene el entorno, dónde quedan los logs y cómo se protegen las credenciales.

Pruebe primero con datos ficticios. Luego, verifique si los registros de ejecución contienen prompts, contenido de repositorio o datos personales que no deberían quedar accesibles a otras personas.

Para comparar la propuesta del SDK con el anuncio completo, vea el lanzamiento del Cursor Agent SDK. Si quiere dividir tareas de desarrollo en espacios separados, consulte la guía de agentes en Git worktrees.

Paso 5: mantenga una persona responsable por la decisión final

Use el agente para producir un análisis, una sugerencia o un cambio preparado para revisión. La aprobación para hacer merge, publicar o enviar datos debe continuar con la persona responsable, principalmente mientras el sistema está en evaluación.

Registre qué instrucciones, herramientas y casos de evaluación se usaron en cada versión. Así, cuando el resultado cambie, podrá relacionar la diferencia con un cambio concreto.

Cómo evitar los errores más comunes en el Cursor Agent SDK

Si el agente inventa una respuesta, agregue un caso de evaluación que exponga esa laguna y pídale que indique cuándo falta información. Si una herramienta recibe una entrada inesperada, valide y cierre sin ejecutar la acción.

Si los resultados varían, mantenga el mismo conjunto de evaluación al comparar cambios. Si el agente tiene acceso más allá de lo necesario, reduzca los permisos en lugar de intentar corregir todo solo con instrucciones en el prompt.