1. Qué aprenderás
Pila completa de Vibe del agente de IA
¡Te damos la bienvenida! Estás a punto de aprender la siguiente habilidad fundamental en el desarrollo de software: cómo guiar de manera eficaz a la Inteligencia Artificial para compilar, probar y, luego, implementar software de calidad para producción. La IA generativa no es un "piloto automático"; es un copiloto potente que necesita un director capacitado.
En este taller, se proporciona una metodología estructurada y repetible para asociarse con la IA en cada etapa del ciclo de vida del desarrollo de software (SDLC) profesional. Pasarás de ser un escritor de código línea por línea a un director técnico, un arquitecto con una visión y un contratista general que usa la IA para ejecutar esa visión con precisión. 🚀
Al final de este instructivo, tendrás lo siguiente:
- Tradujo una idea de alto nivel en una arquitectura de nube con IA.
- Se generó un backend de Python completo con instrucciones específicas y orientadas.
- Usé la IA como programador par para depurar y corregir código.
- Se delegó en la IA la creación de pruebas de unidades, incluidos los simulacros.
Se generó infraestructura como código (IaC) lista para la producción con Terraform.
Se creó una canalización de CI/CD completa en Acciones de GitHub con una sola instrucción.
Supervisaste y administrase tu aplicación en producción con herramientas operativas potenciadas por IA.
No solo te irás con una app que funciona, sino también con un plan para el desarrollo aumentado por IA. Comencemos.
2. Requisitos previos y configuración
Antes de comenzar, preparemos tu entorno. Este es un paso fundamental para garantizar una experiencia fluida en el taller.
Crea una cuenta de GCP nueva y vincula tu facturación
Para potenciar nuestros agentes de IA, necesitamos dos cosas: un proyecto de Google Cloud que proporcione la base y una clave de API de Gemini para acceder a los potentes modelos de Google.
Paso 1: Habilita la cuenta de facturación
- Reclama tu cuenta de facturación con un crédito de USD 5, ya que lo necesitarás para la implementación. Asegúrate de que sea tu cuenta de Gmail.
Paso 2: Crea un proyecto de GCP nuevo
- Ve a la consola de Google Cloud y crea un proyecto nuevo.
- Ve a la consola de Google Cloud y crea un proyecto nuevo.
- Abre el panel izquierdo, haz clic en
Billingy verifica si la cuenta de facturación está vinculada a esta cuenta de GCP.
Si ves esta página, marca manage billing account, elige la prueba de Google Cloud One y vincúlala.
Paso 3: Genera tu clave de API de Gemini
Antes de proteger la llave, debes tener una.
- Navega a Google AI Studio : https://aistudio.google.com/
- Accede con tu cuenta de Gmail.
- Haz clic en el botón "Obtener clave de API", que suele encontrarse en el panel de navegación de la izquierda o en la esquina superior derecha.
- En el diálogo "Claves de API", haz clic en "Crear clave de API en un proyecto nuevo".
- Elige el proyecto nuevo que creaste y que tiene configurada la cuenta de facturación.
- Se generará una nueva clave de API para ti. Copia esta clave de inmediato y guárdala en un lugar seguro de forma temporal (como un administrador de contraseñas o una nota segura). Este es el valor que usarás en los siguientes pasos.
Autenticación de GitHub
Abre Cloud Shell. Para ello, ve a la consola de Google Cloud y haz clic en el botón "Activar Cloud Shell" en la parte superior derecha.
Paso 1: Abre Cloud Shell
👉 Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud (es el ícono con forma de terminal en la parte superior del panel de Cloud Shell), 
👉 Haz clic en el botón "Abrir editor" (parece una carpeta abierta con un lápiz). Se abrirá el editor de código de Cloud Shell en la ventana. Verás un explorador de archivos en el lado izquierdo. 
👉 Busca tu ID del proyecto de Google Cloud:
- Abre la consola de Google Cloud: https://console.cloud.google.com
- Selecciona el proyecto que deseas usar para este taller en el menú desplegable de proyectos que se encuentra en la parte superior de la página.
- Tu ID del proyecto se muestra en la tarjeta de información del proyecto en el panel.
👉Abre la terminal en el IDE de Cloud.
👉💻 En la terminal, verifica que ya te autenticaste y que el proyecto esté configurado con tu ID del proyecto usando el siguiente comando:
gcloud auth list
Paso 2: Autentícate con GitHub y bifurca
Autentícate con GitHub:
👉💻
gh auth login
copiar el código en la página de verificación de acceso
Bifurca y clona el repositorio: 👉💻
gh repo fork cuppibla/storygen-learning --clone=true
3. Arquitectura: De la idea al plano con Cloud Assist
Todo gran proyecto comienza con una visión clara. Usaremos nuestro copiloto de IA, Cloud Assist, para diseñar la arquitectura de nuestra app.
Acciones
- Abre la consola de Google Cloud: https://console.cloud.google.com
- En la esquina superior derecha, haz clic en "Abrir el chat de Cloud Assist".
Habilita Cloud Assist
- Haz clic en
Get Gemini Assisty, luego, enEnable Cloud Assist at no cost. - ¡Y comienza a chatear!
Proporciona la siguiente instrucción detallada a Cloud Assist:
Ingresa tu idea
Generate a Python web application that uses AI to generate children's stories and illustrations. It has Python backend and React frontend host separately on Cloudrun. They communicate through Websocket. It needs to use a generative model for text and another for images. The generated images must be used by Imagen from Vertex AI and stored in a Google Cloud Storage bucket so that frontend can fetch from the bucket to render images. I do not want any load balancer or a database for the story text. We need a solution to store the API key.
Obtén el plan de tu app
- Haz clic en "Editar diseño de la app" y verás el diagrama. Haz clic en el panel superior derecho "<> Get Code" para descargar el código de Terraform.
- Cloud Assist generará un diagrama de arquitectura. Este es nuestro plano visual.
Momento clave de aprendizaje: La IA se destaca en el diseño de sistemas de alto nivel. Puede traducir al instante los requisitos en lenguaje sencillo a una arquitectura visual y profesional.
4. Desarrollo: Compila el ADK con la CLI de Gemini
Configuración inicial
Asegúrate de que usemos la CLI de Gemini para bifurcar el repositorio y preparar el espacio de trabajo:
Configuración del entorno
Ve a Cloud Shell y haz clic en el botón "Abrir terminal".
- Copia la plantilla del entorno:
cd ~/storygen-learning cp ~/storygen-learning/env.template ~/storygen-learning/.env
Cómo ver el archivo oculto en el editor si no encuentras .env
- Haz clic en Ver en la barra de menú superior.
- Selecciona Toggle Hidden Files.
Edita el archivo .env. Reemplaza los siguientes valores en .env:
GOOGLE_API_KEY=[REPLACE YOUR API KEY HERE]
GOOGLE_CLOUD_PROJECT_ID=[REPLACE YOUR PROJECT ID]
GITHUB_USERNAME=[REPLACE YOUR USERNAME]
GENMEDIA_BUCKET=[REPLACE YOUR PROJECT ID]-bucket
p.ej., si el ID de tu proyecto es testproject, debes ingresar GOOGLE_CLOUD_PROJECT_ID=testproject y GENMEDIA_BUCKET=testproject-bucket
Secuencias de comandos de configuración
Ve a 00_Starting_Here Abre una terminal nueva (no en Gemini CLI).
cd ~/storygen-learning/00_Starting_Here
Ejecuta la configuración completa:
./setup-complete.sh
Deberías ver los resultados de la configuración en la terminal
Crea tu primer agente
Ve a 01a_First_Agent_Ready. Usemos la CLI de Gemini para crear el agente del ADK:**
cd ~/storygen-learning/01a_First_Agent_Ready
Abre la CLI de Gemini
gemini
Dentro de la ventana de la CLI de Gemini, prueba la siguiente instrucción:
I need you to help me create a Google ADK (Agent Development Kit) agent for story generation. I'm working on a children's storybook app that generates creative stories with visual scenes.
Please create a complete `agent.py` file that implements an LlmAgent using Google's ADK framework. The agent should:
**Requirements:**
1. Use the `google.adk.agents.LlmAgent` class
2. Use the "gemini-2.5-flash" model (supports streaming)
3. Be named "story_agent"
4. Generate structured stories with exactly 4 scenes each
5. Output valid JSON with story text, main characters, and scene data
6. No tools needed (images are handled separately)
**Agent Specifications:**
- **Model:** gemini-2.5-flash
- **Name:** story_agent
- **Description:** "Generates creative short stories and accompanying visual keyframes based on user-provided keywords and themes."
**Story Structure Required:**
- Exactly 4 scenes: Setup → Inciting Incident → Climax → Resolution
- 100-200 words total
- Simple, charming language for all audiences
- Natural keyword integration
**JSON Output Format:**
{
"story": "Complete story text...",
"main_characters": [
{
"name": "Character Name",
"description": "VERY detailed visual description with specific colors, features, size, etc."
}
],
"scenes": [
{
"index": 1,
"title": "The Setup",
"description": "Scene action and setting WITHOUT character descriptions",
"text": "Story text for this scene"
}
// ... 3 more scenes
]
}
**Key Instructions for the Agent:**
- Extract 1-2 main characters maximum
- Character descriptions should be extremely detailed and visual
- Scene descriptions focus on ACTION and SETTING only
- Do NOT repeat character appearance in scene descriptions
- Always respond with valid JSON
Please include a complete example in the instructions showing the exact format using keywords like "tiny robot", "lost kitten", "rainy city".
The file should start with necessary imports, define an empty tools list, include a print statement for initialization, and then create the LlmAgent with all the detailed instructions.
Can you create this agent in backend/story_agent/agent.py
Cuando termines, desactiva la terminal de Gemini CLI con Control+C.
—————————————— Opcional, puedes omitir la parte de Solución——————————————–
Ahora verifica tu cambio en ADK Web
cd ~/storygen-learning/01a_First_Agent_Ready/backend
source ../../.venv/bin/activate
adk web --port 8080
Cómo poner en funcionamiento el sitio web
cd ~/storygen-learning/01a_First_Agent_Ready
./start.sh
Si el cambio no funciona, deberías ver errores en la IU web y el sitio web del ADK.
—————————————— Solución a partir de aquí ——————————————–
Solución
Finaliza el proceso anterior con Control+C o puedes abrir otra terminal:
cd ~/storygen-learning/01b_First_Agent_Done
Cómo iniciar el sitio web:
./start.sh
Verás el sitio web:
Prueba la IU del ADK: Abre otra terminal:
cd ~/storygen-learning/01b_First_Agent_Done/backend
source ../../.venv/bin/activate
adk web --port 8080
Verás la IU del ADK, en la que podrás hacerle preguntas al agente.
Antes de pasar a la siguiente sección, presiona Ctrl + C para finalizar el proceso.
5. Desarrollo: Crea tu agente personalizado con Imagen
Genera la herramienta de Imagen (segundo agente)
cd ~/storygen-learning/02a_Image_Agent_Ready
Usa la CLI de Gemini para crear el agente de generación de imágenes:
gemini generate "I need you to help me create a custom Google ADK (Agent Development Kit) agent for image generation. This is different from the story agent - this one handles image generation directly using the BaseAgent pattern for full control over tool execution.
Please create a complete `agent.py` file that implements a custom image generation agent. The agent should:
**Requirements:**
1. Use the `google.adk.agents.BaseAgent` class (NOT LlmAgent)
2. Be named "custom_image_agent"
3. Directly execute the ImagenTool without LLM intermediation
4. Handle JSON input with scene descriptions and character descriptions
5. Store results in session state for retrieval by main.py
6. Use async generators and yield Events
**Key Specifications:**
- **Class Name:** CustomImageAgent (inherits from BaseAgent)
- **Agent Name:** "custom_image_agent"
- **Tool:** Uses ImagenTool for direct image generation
- **Purpose:** Bypass LLM agent limitations and directly call ImagenTool
**Input Format:**
The agent should handle JSON input like:
{
"scene_description": "Scene action and setting",
"character_descriptions": {
"CharacterName": "detailed visual description"
}
}
**Core Method:** `async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:`
- Extract user message from `ctx.user_content.parts`
- Parse JSON input or fallback to plain text
- Extract scene_description and character_descriptions
- Build image prompt with style prefix: "Children's book cartoon illustration with bright vibrant colors, simple shapes, friendly characters."
- Include character descriptions for consistency
- Call `await self.imagen_tool.run()` directly
- Store results in `ctx.session.state["image_result"]`
- Yield Event with results
**Session State:**
- Store JSON results in `ctx.session.state["image_result"]`
- Include success/error status
- Store actual image URLs or error messages
Expected Output Structure:
- Successful results stored as JSON with image URLs
- Error results stored as JSON with error messages
- Results accessible via session state in main.py
Can you create this agent in backend/story_image_agent/agent.py
"
—————————————— Opcional, puedes omitir la parte de Solución——————————————–
Ahora verifica tu cambio en ADK Web
cd ~/storygen-learning/02a_Image_Agent_Ready/backend
source ../../.venv/bin/activate
adk web --port 8080
Cómo poner en funcionamiento el sitio web
cd ~/storygen-learning/02a_Second_Agent_Ready
./start.sh
Si el cambio no funciona, deberías ver errores en la IU web y el sitio web del ADK.
—————————————— Solución a partir de aquí ——————————————–
Solución
Finaliza el proceso anterior con Control+C o puedes abrir otra terminal:
# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done
Cómo iniciar el sitio web:
./start.sh
Verás el sitio web:
Prueba la IU del ADK: Abre otra terminal:
# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done/backend
source ../../.venv/bin/activate
adk web --port 8080
Verás la IU del ADK, en la que podrás hacerle preguntas al agente:
Antes de pasar a la siguiente sección, presiona Ctrl + C para finalizar el proceso.
6. Pruebas: Evaluación del agente
Nuestra app funciona, pero necesitamos una red de seguridad automatizada de pruebas. Esta es una tarea perfecta para delegar en nuestro copiloto de IA.
Acciones
cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend
Usa la CLI de Gemini para escribir pruebas integrales:
Abre la CLI de Gemini
gemini
Dentro de la ventana de Gemini CLI, prueba la siguiente instrucción:
I need you to create comprehensive test files for my backend/story_agent in Google ADK. I need three specific JSON files that match the testing structure used in ADK evaluation.
**Context:**
- The story agent generates structured JSON stories with exactly 4 scenes
- It uses LlmAgent with no tools, just direct LLM responses
- Input: Keywords
- Output: JSON with story, main_characters, and scenes arrays
**Files to Create:**
### 1. `story_agent_eval.evalset.json` (Comprehensive Integration Tests)
Create a comprehensive evaluation set with:
- **eval_set_id**: "story_agent_comprehensive_evalset"
- **name**: "Story Agent Comprehensive Evaluation Set"
- **description**: "Comprehensive evaluation scenarios for story_agent covering various keyword combinations, edge cases, and story quality metrics"
Each eval_case should include:
- Full conversation arrays with invocation_id, user_content, final_response
- Complete expected JSON responses with detailed stories, characters, and 4 scenes
- session_input with app_name "story_agent"
- All fields: story (narrative text), main_characters (with detailed visual descriptions), scenes (with index, title, description, text)
### 2. `story_generation.test.json` (Unit Tests)
Create basic generation tests with:
- **eval_set_id**: "story_agent_basic_generation_tests"
- **name**: "Story Agent Basic Generation Tests"
- **description**: "Unit tests for story_agent focusing on JSON structure compliance, scene generation, and keyword integration"
### 3. `test_config.json` (Evaluation Configuration)
Create test configuration with:
- **criteria**: response_match_score: 0.7, tool_trajectory_avg_score: 1.0
- **custom_evaluators**:
- json_structure_validator (validates required fields, scene count, character fields)
- story_quality_metrics (word count 80-250, keyword integration threshold 0.8)
- **evaluation_notes**: Story agent specifics and trajectory expectations
**Important Requirements:**
1. All responses must be valid, parseable JSON
2. Stories must have exactly 4 scenes with indices 1-4
3. Each scene must have: index, title, description, text
4. Main characters must have detailed visual descriptions
5. No tool_uses expected (empty arrays) since story agent uses direct LLM
6. Word count should be 100-200 words total
7. Keywords must be naturally integrated into the narrative
Please generate all three files with realistic example stories and comprehensive test coverage matching the ADK evaluation format.
—————————————— Opcional, puedes omitir la parte de Solución——————————————–
Para ver la evaluación, sigue estos pasos:
./run_adk_web_persistent.sh
Ve a la pestaña eval en la IU del ADK.
Deberías ver la IU web del ADK con capacidades de prueba persistentes
Momento clave de aprendizaje: La IA es un socio poderoso para automatizar el control de calidad. Puede controlar el código estándar de la escritura de pruebas, lo que te permite concentrarte en la creación de funciones.
—————————————— Solución a partir de aquí ——————————————–
Solución
- Ve a la carpeta de la solución:
cd ~/storygen-learning/03b_Agent_Evaluation_Done/backend
- Abre la IU web del ADK
./run_adk_web_persistent.sh
Puedes ver los casos de prueba en la pestaña Eval:
Ajusta las métricas aquí:
Consulta el resultado de la ejecución de la evaluación aquí:
7. Infraestructura como código (IaC): Construcción de una casa en la nube
Nuestro código se probó, pero necesita un lugar listo para la producción. Usaremos la "infraestructura como código" para definir nuestro entorno.
Acciones
cd ~/storygen-learning/04a_Manual_Deployment_Ready
Usa la CLI de Gemini para crear un Dockerfile para el backend: Abre la CLI de Gemini
Gemini
Dentro de Gemini CLI, prueba la siguiente instrucción:
Create a manual deployment plan for my StoryGen app with Google Cloud Platform. I have a Next.js frontend, Python backend, and Terraform infrastructure.
Generate these deployment files:
1. **01-setup.sh** - Environment setup and authentication
2. **02-build-images.sh** - Build and push Docker images to Google Container Registry
3. **03-deploy-infrastructure.sh** - Deploy with Terraform and configure services
4. **load-env.sh** - Load environment variables for deployment
**Requirements:**
- Use Google Cloud Run for both frontend and backend
- Configure Imagen API and storage buckets
- Set up proper IAM permissions
- Use environment variables from .env file
- Include error handling and status checks
Keep scripts simple, well-commented, and production-ready for manual execution.
Solución:
cd ~/storygen-learning/04b_Manual_Deployment_Done
Ejecuta lo siguiente:
source ../.venv/bin/activate
./01-setup.sh
./02-build-images.sh
./03-deploy-infrastructure.sh
Deberías ver los resultados de la implementación y la creación de la infraestructura
8. Automatización (CI/CD): La línea de ensamblaje digital
Implementar nuestra app de forma manual es lento y riesgoso. Pidámosle a nuestra IA que escriba una canalización de CI/CD completa con acciones de GitHub.
Acciones
cd ~/storygen-learning/05a_CICD_Pipeline_Ready
Usa la CLI de Gemini para compilar tu canalización de CI/CD con GitHub:
Cómo abrir Gemini CLI
Gemini
Dentro de Gemini CLI, prueba la siguiente instrucción:
Create a CI/CD pipeline for my StoryGen app using Google Cloud Build and GitHub integration.
Generate these automation files:
1. **cloudbuild.yaml** (for backend) - Automated build, test, and deploy pipeline
2. **GitHub Actions workflow** - Trigger builds on push/PR
3. **Deployment automation scripts** - Streamlined deployment process
**Requirements:**
- Auto-trigger on GitHub push to main branch
- Build and push Docker images
- Run automated tests if available
- Deploy to Google Cloud Run
- Environment-specific deployments (staging/prod)
- Notification on success/failure
Focus on fully automated deployment with minimal manual intervention. Include proper secret management and rollback capabilities.
—————————————— Solución a partir de aquí ——————————————–
Solución:
cd ~/storygen-learning/06_Final_Solution/
# Copy the GitHub workflow to parent folder
cp -r 06_Final_Solution/.github ../../../.github
Regresa a la carpeta 06_Final_Solution y ejecuta la secuencia de comandos:
cd ~/storygen-learning/06_Final_Solution/
./setup-cicd-complete.sh
Deberías ver que se completó la configuración de la canalización de CI/CD
Activa el flujo de trabajo: Confirma y envía tu código a main. Ten en cuenta que debes configurar tu correo electrónico y nombre de GitHub para permitir el permiso.
git add .
git commit -m "feat: Add backend, IaC, and CI/CD workflow"
git push origin main
Ve a la pestaña "Actions" de tu repositorio de GitHub para ver la ejecución de tu implementación automatizada.
Momento clave de aprendizaje: La IA puede generar toda la canalización de CI/CD, una parte compleja y fundamental de DevOps.
9. Operaciones: La torre de control de la IA
¡Ya estamos en vivo! Pero el viaje no termina aquí. Este es el "día 2": las operaciones. Volvamos a Cloud Assist para administrar nuestra aplicación en ejecución.
Acciones
- Navega a tu servicio de Cloud Run en la consola de Google Cloud. Interactúa con tu app en vivo para generar tráfico y registros.
- Abre el panel de Cloud Assist y úsalo como copiloto operativo con instrucciones como las siguientes:
Análisis de registros:
Summarize the errors in my Cloud Run logs for the service 'genai-backend' from the last 15 minutes.
Ajuste del rendimiento:
My Cloud Run service 'genai-backend' has high startup latency. What are common causes for a Python app and how can I investigate with Cloud Trace?
Optimización de costos:
Analyze the costs for my 'genai-backend' service and its GCS bucket. Are there any opportunities to save money?
Momento clave de aprendizaje: El SDLC de la IA es un ciclo continuo. El mismo copiloto de IA que ayudó a compilar la aplicación es un socio indispensable para supervisarla, solucionar problemas y optimizarla en producción.