Scaffolding y Gestión de Paquetes Reproducibles

Autor: Eduardo Martínez Agrelo

En el desarrollo de software profesional, no creamos carpetas y archivos de forma manual cada vez que iniciamos un proyecto. Para escalar, necesitamos una estructura predecible y estandarizada. En este laboratorio utilizaremos el comando create de agents-cli para generar un "Scaffolding" (andamiaje) industrial que separa la lógica, las pruebas y la infraestructura siguiendo las mejores prácticas de Google.

¿Qué es el Scaffolding Industrial?

El scaffolding es la creación automática del esqueleto de una aplicación. Al usar el flag --prototype, la CLI nos entrega una arquitectura lista para el mundo real:

• Carpeta app/: El contenedor exclusivo para la lógica de vuestro agente y sus herramientas.
• Carpeta tests/: El espacio reservado para los Evals y pruebas unitarias que garantizan la calidad.
• Infraestructura como Código: Archivos preconfigurados para que el despliegue en la nube sea una tarea administrativa y no un reto técnico.

El Manifiesto del Proyecto: pyproject.toml

Hemos dejado atrás el antiguo archivo requirements.txt. El estándar moderno en Python es el pyproject.toml, un archivo centralizado que define la identidad de vuestro agente:

[project.dependencies] -> Lista de librerías validadas

Este manifiesto no solo gestiona qué librerías necesita vuestro agente para "pensar", sino que configura las herramientas de desarrollo, las versiones mínimas de Python y los metadatos necesarios para que Google Cloud Build sepa cómo empaquetar vuestra aplicación de forma eficiente.

Inmutabilidad con uv.lock

Uno de los mayores problemas en producción es el "en mi máquina funciona". Para solucionarlo, introducimos el concepto de Reproducibilidad mediante archivos lock:

• Determinismo: El archivo uv.lock contiene los hashes y versiones exactas de cada sub-dependencia.
• Estabilidad: Garantiza que el entorno virtual que tenéis en vuestro portátil sea una copia exacta del que se ejecutará en los servidores de Google, evitando errores inesperados por actualizaciones de librerías de terceros.

Implementación práctica

En este laboratorio, generaremos nuestro primer "Agente Profesional" mediante la CLI. Exploraremos la anatomía de la estructura generada y aprenderemos a usar el comando uv add para gestionar dependencias de forma técnica. Sincronizaremos el entorno virtual con agents-cli install y observaremos cómo el archivo pyproject.toml se convierte en el contrato de inmutabilidad de nuestro software, preparando vuestro repositorio de GitHub para un flujo de trabajo colaborativo de alto nivel.

Conclusión: La base de la ingeniería de software

Has aprendido que el orden y la reproducibilidad son tan importantes como el código mismo. Ya tienes un proyecto con estructura de nivel senior. Con los cimientos construidos, el siguiente paso es personalizar el agente y conectarlo de forma segura con el ecosistema de datos de Google Cloud.