Dale a un agente de IA acceso de escritura a tu proyecto API y puede causar daños reales. No maliciosamente; los agentes simplemente hacen lo que el prompt implica. Pídele que “limpie los endpoints de usuario” y podría eliminar una ruta activa de la que aún dependes. Pídele que “actualice el esquema” y puede sobrescribir un modelo de datos al que hacen referencia otros tres endpoints. El agente no tiene idea de lo que está en producción. Solo ve los recursos que tiene permitido tocar, y los toca.
Esta es una nueva clase de riesgo. Cuando un humano realizó esas ediciones, dudó antes de eliminar un endpoint. Un agente ejecutándose en un bucle desde tu terminal no duda. Ejecuta el comando, obtiene una respuesta exitosa y sigue adelante. Si ese comando llegó a tu rama principal, el cambio ya está activo en tu fuente de diseño.
La solución no es bloquear a los agentes. Es darles un sandbox del que no puedan escapar. La Rama AI de Apidog hace exactamente eso: cada edición impulsada por un agente aterriza en una rama aislada, tu rama fuente permanece intacta y nada llega a la rama principal hasta que un humano revisa las diferencias y las fusiona. Esta publicación recorre el flujo de CLI de principio a fin, y luego cubre la higiene general de agentes seguros que debería rodearlo. Para conocer el razonamiento de diseño detrás de la función, consulta la descripción más detallada sobre Rama AI y cambios más seguros impulsados por agentes; esta pieza es el manual práctico.
Por qué el acceso de escritura del agente es peligroso por defecto
La mayoría de las herramientas otorgan a un agente un solo nivel de acceso: el proyecto. Si el agente puede crear un endpoint, también puede eliminar uno. Si puede actualizar un esquema, también puede reemplazarlo por algo incompatible. No hay brecha entre “el agente propuso un cambio” y “el cambio está en tu fuente de verdad”.
Tres modos de fallo aparecen una y otra vez:
- Sobreescritura. El agente regenera un esquema a partir de una comprensión parcial de tu API y elimina campos que otros endpoints necesitan.
- Eliminación. El agente “consolida” endpoints y elimina rutas que todavía son llamadas por clientes activos.
- Desvío silencioso. El agente realiza docenas de pequeñas ediciones a lo largo de una sesión. Ningún cambio individual parece incorrecto, pero la suma diverge silenciosamente de lo que lanzaste.
Ninguno de estos es exótico. Son el resultado normal de un agente haciendo su trabajo en la rama incorrecta. El objetivo es hacer que la rama incorrecta sea imposible de alcanzar.
La solución principal: una rama AI aislada
Una Rama AI es un tipo especial de rama de sprint construida para operaciones externas de IA y CLI. Cuando creas una, el agente edita dentro de ella y los cambios permanecen allí. Tu rama fuente y tu rama principal no se ven afectadas hasta que decides fusionarlas.
La creas desde la CLI. Primero instala y autentica la CLI de Apidog:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Luego crea la rama AI. La documentación recomienda nombrarla con la fecha, la rama fuente y el propósito para que sea fácil de identificar más tarde:
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
Aquí hay dos cosas importantes. La rama se crea a partir de main, pero crearla no afecta a main. Y la rama comienza vacía. Una Rama AI no copia automáticamente todo tu proyecto en sí misma; solo contiene los recursos que el agente trae explícitamente. Esa es una propiedad de seguridad deliberada. El agente solo puede editar lo que ha importado, por lo que el radio de impacto es lo que hayas definido, no todo el proyecto.
Para ver el conjunto completo de banderas para cualquier comando de rama, ejecútalo con -h:
apidog branch create -h
Importar los recursos fuente antes de editarlos
Dado que la Rama AI está vacía, el primer trabajo del agente es traer los recursos específicos en los que necesita trabajar. Este es el paso que evita que un agente opere a ciegas. Importas el endpoint, esquema o documento que deseas cambiar, y nada más viene incluido.
Dirige al agente (o a ti mismo) a los recursos exactos por ID. La CLI de Apidog utiliza banderas de ID plurales, separadas por comas para estas operaciones:
apidog branch pick-to \
--type ai \
--from main \
--to "ai/20260708-from-main-user-register" \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Ahora la rama AI contiene una copia de los endpoints 1 y 2 y del esquema 3 tal como existen en main. El agente trabaja con estas copias. Haga lo que haga con ellas, los originales en main permanecen inalterados. Si el agente elimina un endpoint aquí, elimina la copia, no la ruta activa. Esta es la diferencia entre “el agente destruyó nuestra API” y “el agente destruyó una copia temporal que podemos desechar”.
Si estás impulsando esto a través de un agente de codificación, los mismos comandos se ejecutan dentro del bucle del agente. La CLI de Apidog devuelve JSON estructurado con agentHints.nextSteps, para que un agente pueda leer el resultado de cada comando y decidir qué hacer a continuación sin que tú le traduzcas la salida. La guía apidog-cli en Cursor muestra este patrón conectado a un editor real.
Deja que el agente edite, luego lee las diferencias
Con los recursos importados, deja que el agente haga su trabajo. Crea, actualiza o elimina endpoints, esquemas, documentos y escenarios de prueba dentro de la rama AI. Cada una de esas escrituras está contenida.
Cuando termina, revisas antes de que se fusione nada. Nada en el flujo de la Rama AI es automático; la fusión es una decisión humana. Inspecciona los cambios desde la CLI o el cliente de Apidog y confirma que las diferencias coinciden con lo que realmente querías. Esta es tu puerta. Si el agente se desvió, lo ves aquí, y la solución es descartar la rama, no revertir la producción.
Trata esta revisión como obligatoria, no opcional. El objetivo de todo el flujo es que un humano examine la salida del agente antes de que se haga realidad. Saltar la revisión anula el aislamiento.
Aplica cambios con una solicitud de fusión
Cómo fusionas depende de si la rama de destino está protegida. Aquí es donde una rama principal protegida rinde sus frutos.
Si la rama de destino no está protegida, puedes fusionar directamente, nombrando los recursos exactos a transferir:
apidog branch merge \
--type ai \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Si main está protegida, y debería estarlo, una fusión directa está bloqueada. En su lugar, abres una solicitud de fusión y diriges el cambio a través de una revisión:
apidog merge-request create \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--reviewer-ids <REVIEWER_USER_IDS> \
--description "AI branch: user register changes" \
--project <PROJECT_ID>
La solicitud de fusión es la ruta preferida para cualquier cosa generada por un agente. Fuerza el cambio a través del mismo flujo de revisión al que se enfrentaría un colaborador humano. Un compañero de equipo lo aprueba, y luego se aplica. El agente nunca escribe directamente en main por sí mismo; solo puede solicitar, a través de una solicitud de fusión, que un humano acepte su trabajo. Ten en cuenta que la fusión solo transfiere los IDs de recursos que enumeras. Si el agente tocó algo que no tenías intención de enviar, dejas ese ID fuera de la fusión y se queda atrás.
Esto refleja cómo un flujo de trabajo de API nativo de Git maneja a los colaboradores humanos: ramificar, proponer, revisar, fusionar. La Rama AI aplica la misma disciplina a un colaborador no humano, que es el que menos quieres que escriba directamente en `main`.
Limpiar ramas fusionadas y abandonadas
Las ramas AI fusionadas o abandonadas deben archivarse rápidamente para mantener legible la lista de ramas. Una vez que una rama se fusiona o decides que no la necesitas, archívala primero y luego elimínala:
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
La cadencia recomendada es una rama AI por tarea. Una rama se asigna a una única unidad de trabajo del agente, se revisa, se fusiona o descarta, y luego se archiva. Esto mantiene el aislamiento significativo; nunca estarás revisando una rama que acumuló tres sesiones de ediciones no relacionadas.
Higiene del agente seguro alrededor de la rama
La Rama AI gestiona el aislamiento, pero funciona mejor dentro de unos pocos hábitos que limitan lo que un agente puede alcanzar en primer lugar.
Usa tokens de acceso de menor privilegio. El token que pasas a apidog login --with-token define el alcance de lo que el agente puede hacer. Dale a un token de automatización acceso a los proyectos que necesita y nada más. No le des a un agente tu token personal de propietario porque fuera conveniente. Si un token se filtra o un agente se comporta mal, quieres que el daño esté limitado por el alcance del token.
Protege tu rama principal. Esta es la única configuración que convierte “revisar antes de fusionar” de una sugerencia en una regla. Con main protegida, la ruta de fusión directa está cerrada y cada cambio del agente tiene que pasar por merge-request create. La protección es lo que hace que la solicitud de fusión no sea opcional.
Revisa antes de fusionar, siempre. El aislamiento solo te protege si un humano realmente lee las diferencias. Incorpora la revisión al flujo de trabajo para que no se pueda omitir. Un agente que ha sido confiable durante una semana aún puede malinterpretar una instrucción al octavo día.
Delega, luego verifica. Este es el patrón que lo une todo. Delegas una tarea con alcance al agente, lo dejas ejecutar en su rama aislada y luego verificas el resultado antes de que se fusione. El agente hace el trabajo; tú posees la aceptación. La misma división aparece cuando los agentes ejecutan pruebas: el agente ejecuta la suite, tú verificas los resultados del arnés de prueba y el código de salida antes de confiar en ellos. Delega la ejecución, mantén el juicio.
Si estás versionando tu especificación de API en Git junto con todo esto, el flujo de trabajo de control de versiones de OpenAPI te proporciona una segunda capa de historial para comparar cuando algo parece incorrecto.
El flujo de principio a fin, en orden
Aquí tienes todo el proceso en una secuencia que puedes entregar a un agente o ejecutar tú mismo:
apidog branch create --type aidesdemain. La rama está vacía ymainno se toca.apidog branch pick-tolos endpoints y esquemas específicos que el agente necesita. Nada más se incluye.- Deja que el agente edite dentro de la rama. Cada escritura está contenida.
- Revisa las diferencias desde la CLI o el cliente. Esta es la puerta humana.
apidog merge-request createcontra unamainprotegida. Un compañero de equipo aprueba; el agente nunca escribe directamente en main.apidog branch archiveuna vez fusionada o abandonada.
En ningún momento el agente tiene un camino para sobrescribir o eliminar un endpoint activo en main. Lo peor que puede hacer es realizar un cambio incorrecto en una copia temporal que luego tú rechazas fusionar.
Dale a los agentes espacio para trabajar sin entregarles las llaves
Los agentes son útiles precisamente porque actúan sin preguntar. Eso es también lo que hace peligroso el acceso de escritura sin restricciones. La respuesta no es ralentizar al agente; es hacer que sus escrituras rápidas e indudables aterricen en un lugar seguro. Una rama AI aislada, una `main` protegida, tokens de menor privilegio y una revisión obligatoria convierten “el agente destruyó nuestra API” en una diferencia que miras y rechazas.
Apidog lo integra para que no tengas que ensamblarlo a partir de herramientas separadas. Hazte con la CLI de Apidog, crea una rama AI y deja que tus agentes editen contra una copia en lugar de la cosa real. Descarga Apidog para probar el flujo de la Rama AI, y lee la documentación de la Rama AI para obtener la referencia completa de comandos antes de conectarla a un flujo de trabajo de producción.