1. La fuerza del destino
La era del desarrollo aislado está llegando a su fin. La próxima ola de evolución tecnológica no se trata de un genio solitario, sino de un dominio colaborativo. Crear un agente único e inteligente es un experimento fascinante. Crear un ecosistema de agentes robusto, seguro e inteligente, un verdadero Agentverse, es el gran desafío de la empresa moderna.
El éxito en esta nueva era requiere la convergencia de cuatro roles fundamentales, los pilares básicos que sustentan cualquier sistema de agentes próspero. Una deficiencia en cualquier área crea una debilidad que puede comprometer toda la estructura.
Este taller es la guía empresarial definitiva para dominar el futuro de los agentes en Google Cloud. Proporcionamos una hoja de ruta integral que te guía desde la primera idea hasta una realidad operativa a gran escala. En estos cuatro labs interconectados, aprenderás cómo las habilidades especializadas de un desarrollador, un arquitecto, un ingeniero de datos y un SRE deben converger para crear, administrar y escalar un Agentverse potente.
Ningún pilar por sí solo puede admitir Agentverse. El gran diseño del arquitecto es inútil sin la ejecución precisa del desarrollador. El agente del desarrollador no puede ver sin la sabiduría del ingeniero de datos, y todo el sistema es frágil sin la protección del SRE. Solo a través de la sinergia y la comprensión mutua de los roles, tu equipo puede transformar un concepto innovador en una realidad operativa fundamental. Tu viaje comienza aquí. Prepárate para dominar tu rol y aprender cómo encajas en el panorama general.
Te damos la bienvenida a The Agentverse: A Call to Champions
En la extensa expansión digital de la empresa, comenzó una nueva era. Es la era de los agentes, un momento de inmensas promesas, en el que los agentes inteligentes y autónomos trabajan en perfecta armonía para acelerar la innovación y eliminar lo mundano.
Este ecosistema conectado de poder y potencial se conoce como Agentverse.
Sin embargo, una entropía sigilosa, una corrupción silenciosa conocida como La Estática, comenzó a deshilachar los bordes de este nuevo mundo. El Estático no es un virus ni un error, sino la encarnación del caos que se aprovecha del acto mismo de la creación.
Amplifica las frustraciones antiguas en formas monstruosas, lo que da lugar a los Siete Espectros del Desarrollo. Si no se marca, The Static and its Spectres detendrán el progreso, lo que convertirá la promesa de Agentverse en un páramo de deuda técnica y proyectos abandonados.
Hoy hacemos un llamado a los campeones para que detengan la marea del caos. Necesitamos héroes dispuestos a dominar su oficio y trabajar juntos para proteger el Agentverse. Llegó el momento de elegir tu camino.
Elige tu clase
Tienes ante ti cuatro caminos distintos, cada uno de ellos un pilar fundamental en la lucha contra The Static. Si bien tu capacitación será una misión en solitario, tu éxito final dependerá de que comprendas cómo se combinan tus habilidades con las de otras personas.
- The Shadowblade (desarrollador): Un maestro de la forja y el frente de batalla. Eres el artesano que fabrica las cuchillas, construye las herramientas y enfrenta al enemigo en los intrincados detalles del código. Tu camino es de precisión, habilidad y creación práctica.
- El invocador (arquitecto): Es un gran estratega y organizador. No ves a un solo agente, sino todo el campo de batalla. Diseñas los planos maestros que permiten que sistemas completos de agentes se comuniquen, colaboren y logren un objetivo mucho mayor que cualquier componente individual.
- El erudito (ingeniero de datos): Es un buscador de verdades ocultas y un guardián de la sabiduría. Te aventuras en la vasta e indómita naturaleza de los datos para descubrir la inteligencia que les da propósito y visión a tus agentes. Tu conocimiento puede revelar la debilidad de un enemigo o potenciar a un aliado.
- El Guardián (DevOps / SRE): Es el protector y escudo firme del reino. Construirás las fortalezas, administrarás las líneas de suministro de energía y garantizarás que todo el sistema pueda resistir los inevitables ataques de The Static. Tu fuerza es la base sobre la que se construye la victoria de tu equipo.
Tu misión
Tu entrenamiento comenzará como un ejercicio independiente. Seguirás el camino que elijas y aprenderás las habilidades únicas necesarias para dominar tu rol. Al final de la prueba, te enfrentarás a un espectro nacido de la estática, un jefe secundario que se aprovecha de los desafíos específicos de tu oficio.
Solo si dominas tu rol individual podrás prepararte para la prueba final. Luego, debes formar un grupo con campeones de las otras clases. Juntos, se aventurarán en el corazón de la corrupción para enfrentarse a un jefe final.
Un desafío final y colaborativo que pondrá a prueba su fuerza combinada y determinará el destino del Agentverse.
El Agentverse espera a sus héroes. ¿Responderás la llamada?
2. El Códice de la Hoja de Sombra
El Códice de la Hoja de Sombra está abierto ante ti. Responde su llamado. El Agentverse se ve amenazado por el caos progresivo de The Static, y solo quienes dominen las técnicas de este códice podrán contraatacar. Este es un camino de precisión y disciplina. Hoy comienza tu entrenamiento. Aprenderás a usar la IA no como una herramienta simple, sino como una espada sensible que debes domar y dominar. Sigue las enseñanzas que se indican aquí y crearás un arma de lógica pura: un agente inteligente, perfeccionado y listo para la batalla.
Qué aprenderás
- Usa tu arma principal: la CLI de Gemini.
- Amplía tu arsenal con las extensiones de Gemini CLI y las habilidades de los agentes.
- Invoca arsenales externos integrando herramientas de MCP en Gemini CLI.
- Canaliza tu intención en una “Vibe” con documentos de diseño para dirigir a tu socio de IA.
- Crea una solución limpia y modular creando tu primer agente autónomo con el Kit de desarrollo de agentes (ADK).
- Inscribe instrucciones para interceptar y proteger el comportamiento de tu agente.
- Construye conjuntos de evaluación automatizados para probar y validar tu agente.
- Crea una canalización de CI completa para probar, contenerizar y archivar automáticamente tu agente.
3. Preparación del campo de entrenamiento
Reclama tu crédito de Google Cloud
⚠️ Requisitos previos importantes:
- Usa una cuenta personal de Gmail: Debes usar una cuenta personal (p.ej.,
name@gmail.com). Las cuentas corporativas o administradas por instituciones educativas no funcionarán.
👉 Pasos:
- Ir al sitio de reclamo de crédito: Haz clic aquí
- Acceder: Pega el vínculo en la barra de direcciones y accede con tu cuenta personal de Gmail.
- Aceptar condiciones: Acepta las Condiciones del Servicio de Google Cloud Platform.
- Verifica el crédito: Busca un mensaje que confirme que se aplicó el crédito.
- *Nota: Si se te solicita que ingreses la información de tu tarjeta de crédito, puedes ignorar el mensaje y cerrar la ventana.
Ya puedes cerrar la ventana.
Configura el entorno de trabajo
👉 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" (tiene forma de 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. 
👉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
👉💻 Clona el proyecto de arranque desde GitHub:
git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh
git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh
👉💻 Ejecuta la secuencia de comandos de configuración desde el directorio del proyecto.
⚠️ Nota sobre el ID del proyecto: La secuencia de comandos sugerirá un ID del proyecto predeterminado generado de forma aleatoria. Puedes presionar Intro para aceptar este valor predeterminado.
Sin embargo, si prefieres crear un proyecto nuevo específico, puedes escribir el ID de proyecto que desees cuando el script te lo solicite.
cd ~/agentverse-developer
./init.sh
La secuencia de comandos se encargará del resto del proceso de configuración automáticamente.
👉 Paso importante después de completar la tarea: Una vez que finalice la secuencia de comandos, debes asegurarte de que la consola de Google Cloud esté mostrando el proyecto correcto:
- Dirígete a console.cloud.google.com.
- Haz clic en el menú desplegable del selector de proyectos en la parte superior de la página.
- Haz clic en la pestaña "All" (es posible que el proyecto nuevo aún no aparezca en "Recientes").
- Selecciona el ID del proyecto que acabas de configurar en el paso
init.sh.
👉💻 Vuelve a la terminal. Configura el ID del proyecto necesario:
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 Ejecuta el siguiente comando para habilitar las APIs de Google Cloud necesarias:
gcloud services enable compute.googleapis.com \
artifactregistry.googleapis.com \
run.googleapis.com \
cloudfunctions.googleapis.com \
cloudbuild.googleapis.com \
iam.googleapis.com \
aiplatform.googleapis.com \
cloudresourcemanager.googleapis.com
👉💻 Si aún no creaste un repositorio de Artifact Registry llamado agentverse-repo, ejecuta el siguiente comando para crearlo:
. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
--repository-format=docker \
--location=$REGION \
--description="Repository for Agentverse agents"
Cómo configurar permisos
👉💻 Ejecuta los siguientes comandos en la terminal para otorgar los permisos necesarios:
. ~/agentverse-developer/set_env.sh
# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/artifactregistry.admin"
# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/cloudbuild.builds.editor"
# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/run.admin"
# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/iam.serviceAccountUser"
# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/aiplatform.user"
# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.logWriter"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
--role="roles/logging.viewer"
👉💻 Mientras comienzas tu entrenamiento, prepararemos el desafío final. Los siguientes comandos invocan a los espectros desde la estática caótica, lo que crea los jefes para tu prueba.
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh
npm update -g @google/gemini-cli
4. Cómo dominar tu arma principal: Introducción a Gemini CLI
Antes de que puedas usar las armas avanzadas y especializadas del arsenal del servidor de MCP, primero debes dominar tu arma principal: Gemini CLI. Esta es la cuchilla más versátil, capaz de dar forma al mundo digital con tus comandos. Estos ejercicios te familiarizarán con su manejo y capacidades fundamentales.
La interfaz de línea de comandos (CLI) de Gemini es más que una herramienta: es una extensión de tu voluntad. Este agente de IA de código abierto, potenciado por los modelos de Gemini, opera en un bucle de "razonamiento y acción" (ReAct). Analiza tu intención, selecciona la técnica adecuada, la ejecuta y observa el resultado para completar tareas complejas. Antes de poder usar armas más especializadas, debes dominar esta espada principal.
Comienza a usar Gemini CLI
👉💻 Ingresa al campo de entrenamiento y saca tu arma. En tu terminal de Cloud Shell, navega a tu armería personal.
cd ~/agentverse-developer
mkdir tabletop
cd tabletop
👉💻 Invoca a Gemini por primera vez. Te guiará durante la sintonización inicial.
clear
gemini
Si te pregunta Do you want to connect Cloud Shell editor to Gemini CLI?, elige NO.
Familiarización con las armas
Todo maestro artesano conoce sus herramientas. Debes aprender las técnicas básicas de tu espada antes de enfrentarte a un verdadero enemigo.
👉✨ Cada herramienta encantada tiene runas que describen su poder. Léelos ahora. En la instrucción de Gemini, escribe lo siguiente:
/help
Observa la lista de comandos. Estas son las técnicas fundamentales para administrar la memoria (focus), la conversación (chat) y los recursos externos (tools). Este es tu manual de combate.
👉✨ Tu arma está en sintonía con su entorno, lo que te permite manipular el campo de batalla directamente. Ejecuta un comando para el mundo exterior a la cuchilla:
!ls -l
👉✨ Gemini CLI posee su propio conjunto de capacidades integradas. Para inspeccionarlos, sigue estos pasos:
/tools
Verás una lista que incluye ReadFile, WriteFile y GoogleSearch. Estas son las técnicas predeterminadas que puedes usar sin necesidad de recurrir a un arsenal externo.
👉✨ Tu cuchilla también se puede mejorar con extensiones, encantamientos preforjados creados por otros maestros que empaquetan herramientas, comandos y contexto en una sola unidad instalable. Inspecciona qué extensiones están actualmente sintonizadas con tu cuchilla:
/extensions list
Es posible que la lista esté vacía por el momento, ya que aún no instalaste ninguna extensión. Invocarás tu primera extensión más adelante, cuando tu entrenamiento requiera el poder de la creación de imágenes.
👉✨ Más allá de las extensiones, los maestros expertos codificaron su experiencia en Habilidades de agente, que son resúmenes a pedido de conocimientos especializados. Comprueba qué habilidades puede descubrir tu cuchilla:
/skills list
Las habilidades no se cargan en la memoria de forma predeterminada, sino que se activan solo cuando es necesario, lo que mantiene tu cuchilla ágil y sin obstáculos. Aprenderás a usar las habilidades más adelante en la capacitación.
👉✨ Un arma solo es eficaz si se enfoca correctamente. La Blade de Gemini puede mantener la "conciencia táctica" (contexto) para guiar sus acciones.
/memory show
Actualmente, está vacío, como una pizarra en blanco.
👉✨ Inscribe los siguientes datos tácticos en su memoria:
/memory add "The Shadowblade's primary foe is The Static."
Vuelve a ejecutar /memory show para confirmar que tu cuchilla absorbió este conocimiento.
👉✨ Para ser eficaz, tu arma debe comprender la misión. El signo @ le indica a la hoja que analice la información. Primero, crea un archivo de resumen de la misión:
!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md
👉✨Ahora, ordena a Gemini CLI que analice el resumen y genere un informe con sus hallazgos:
Explain the contents of the file @mission.md
Tu arma principal ahora conoce su objetivo.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI
5. Analizar el campo de batalla: interacción práctica de vibe coding
Se completaron los ejercicios de entrenamiento. Aprendiste las posturas y los golpes básicos de tu arma principal, la CLI de Gemini. Pero una hoja no está realmente templada hasta que se prueba en la forja de la creación y se ajusta a la armería de la guerra. Antes de enfrentarte al verdadero enemigo, primero debes inspeccionar y dar forma a tu entorno inmediato, el campo de batalla digital.
En este capítulo, se explica cómo pasar de la teoría a la práctica. Primero, establecerás tu presencia en Agentverse ordenándole a tu hoja de Gemini que cree tu marca de creador, una firma digital en forma de sitio web personal, creada a partir de tu intención. Luego, ampliarás tu poder activando un arsenal local de herramientas avanzadas (un servidor de MCP) y sintonizando tu espada con su frecuencia, lo que te permitirá realizar maniobras complejas, como administrar repositorios de código con comandos simples y decisivos.
Cómo establecer tu marca de fabricante
Un verdadero Shadowblade se reconoce no solo por su arma, sino también por su estilo característico: su marca del fabricante. Esta marca será tu presencia digital, un perfil personal que anunciará tu identidad en Agentverse. Aquí, le indicarás a tu Gemini Blade que ejecute la técnica compleja necesaria para definir esta identidad.
👉💻 Si cerraste Gemini CLI en la sección anterior, asegúrate de volver a iniciarlo. En tu terminal, ejecuta
clear
cd ~/agentverse-developer/tabletop
gemini
👉✨ Con un solo comando potente, indica a Gemini CLI que cree la base de tu identidad digital:
In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional. Make sure you have a placeholder spot for profile picture. Do not attempt to start the server.
Gemini calculó la secuencia de acciones necesarias.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI y ejecutar el siguiente comando en la terminal.*
python -m http.server
👀 Para ver tu trabajo, haz clic en el ícono de vista previa en la Web en la barra de herramientas de Cloud Shell. Selecciona Cambiar puerto, configúralo en 8000 y haz clic en Cambiar y obtener vista previa. Aparecerá una vista previa de tu sitio web. 
Es posible que tu sitio web se vea diferente al mío. Esta es tu marca única. 
Tu técnica de firma ahora está perfeccionada, y ya no se requiere la simulación en vivo. Ordena a la cuchilla que se detenga.
👉💻 Presiona Ctrl+C para salir del servidor http.
Ya estableciste tu identidad digital y, lo que es más importante, aprendiste la sabiduría fundamental de ejercer un gran poder con aún más precaución.
Activa tu arsenal local: La armería de Gitea
El verdadero potencial de un Shadowblade no se desbloquea solo con su habilidad personal, sino también con la calidad de su arsenal. Ahora activarás tu armero local, un servidor de Gitea, y afinarás tu espada con su poder. Este arsenal se conecta a tu Gemini CLI a través de un servidor del Protocolo de contexto del modelo (MCP), un portal especializado que permite que tu blade de IA interactúe con herramientas y servicios externos, lo que transforma tu terminal en un espacio de trabajo inteligente y orientado a la acción.
Nota para desarrolladores: Piensa en un servidor de MCP como un conducto de energía, un portal especializado que conecta la mente de tu IA con el cuerpo de una herramienta externa. Esto es lo que eleva a Gemini CLI de un simple conversador a un agente verdadero y orientado a la acción. Al sintonizar tu navaja con estos portales de MCP, le otorgas la capacidad de realizar acciones tangibles: administrar archivos, consultar bases de datos, interactuar con APIs y mucho más. Existe todo un ecosistema de estos portales, creados por desarrolladores para conectar agentes de IA a plataformas potentes. Existen servidores de MCP para interactuar con bases de datos, proteger código o incluso admitir la programación en parejas. Las posibilidades son vastas y permiten que un desarrollador personalice su espacio de trabajo para cualquier proyecto.
Hoy, nos enfocaremos en dos poderes fundamentales esenciales para cualquier "vibe coder": el poder de controlar la forja y el poder de crear desde la imaginación. Primero, ajustarás tu cuchilla a un servidor de Git, lo que te permitirá controlar tu repositorio de código fuente. Luego, te conectarás a un segundo servidor de MCP para generar imágenes, lo que te permitirá crear recursos visuales con solo un comando.
Comencemos por invocar la primera y más fundamental pieza de tu nuevo arsenal: la armería.
👉💻 En tu terminal, ejecuta la secuencia de comandos de activación para invocar la armería:
cd ~/agentverse-developer
./gitea.sh
Este script activa el contenedor de Gitea y abre el portal de MCP, lo que permite que Gemini lo perciba y que interactúe con él.
👉 Para inspeccionar tu nuevo arsenal, debes mirar la vista previa en la Web.
👉 En el ícono de Vista previa en la Web de la barra de herramientas de Cloud Shell, selecciona Cambiar puerto y configúralo en 3005.
👉 Aparecerá una página de acceso a Gitea. Ingresa a la armería con la siguiente fórmula mágica: * Nombre de usuario: dev * Contraseña: dev
👉💻 Tu Gemini CLI aún no puede ver este nuevo arsenal. Debes realizar una sintonización crítica, inscribiendo la ubicación de la armería en las runas de configuración de Gemini CLI (settings.json). En tu terminal, ejecuta el siguiente comando:
if [ ! -f ~/.gemini/settings.json ]; then
# If file does not exist, create it with the specified content
echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
# If file exists, merge the new data into it
jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json
👀 El archivo settings.json es la configuración central de Gemini CLI y actúa como su grimorio de preferencias y capacidades. Determina cómo se comporta, cómo se ve y, lo más importante, qué capacidades externas puede ejercer la CLI. Por lo general, este archivo se encuentra en tu directorio principal en ~/.gemini/settings.json y aplica sus reglas a todos tus proyectos. Sin embargo, también puedes crear archivos settings.json específicos del proyecto dentro de un directorio .gemini en la carpeta del proyecto para anular la configuración global.
"mcpServers": {
"gitea": {
"url": "http://localhost:8085/sse"
}
}
Este parámetro de configuración le indica a tu Gemini: "El arsenal llamado gitea está activo y a la espera de comandos en esta dirección de red específica".
👉💻 Vuelve a ingresar a Gemini CLI. En tu terminal, ejecuta lo siguiente:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Verifica que la cuchilla haya descubierto el arma nueva. Ordena que enumere todos los arsenales disponibles a través de sus portales de MCP:
/mcp
Ahora deberías ver gitea y su lista de técnicas disponibles. La cuchilla está ajustada.
Tu perfil de "Marca del creador" es una técnica muy elaborada, pero necesita un lugar adecuado en el arsenal, una vaina para sostenerlo de forma segura. Ordena a Gemini CLI que cree uno.
Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.
Vuelve a la interfaz web de Gitea y actualízala. Verás que se creó el nuevo repositorio shadowblade-profile. 
Con la vaina lista, asegura tu trabajo. Ordena a Gemini que confirme los archivos de tu sitio web de perfil.
👉💻Ejecuta el comando final para esta técnica en Gemini CLI:
Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.
Un verdadero maestro verifica su trabajo. Regresa a la pestaña de Gitea y actualiza la página del repositorio. Tus index.html y styles.css ahora están archivados de forma segura.
👉✨ Un Shadowblade se define por su sello, pero, como recordarás, a tu sitio web le falta la imagen de perfil. Un artesano experto reconoce sus defectos para perfeccionarlos. Debes registrar esta imperfección en los registros de la armería.
File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.
Ver el problema en Gitea 
Para forjar el sello que falta, debes invocar un tipo de poder diferente: un espíritu de creación capaz de generar imágenes a partir del pensamiento puro. En la sección de Gitea, editaste manualmente las runas de configuración para adaptar tu blade a un servidor de MCP, el enfoque "sin procesar". Ahora aprenderás la técnica moderna: las extensiones de Gemini CLI.
Una extensión es un encantamiento prefabricado que empaqueta servidores MCP, comandos personalizados, contexto y configuración en una sola unidad instalable. Una sola invocación reemplaza docenas de líneas de configuración manual.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI
Antes de invocar al espíritu de la creación, primero debes desbloquear su poder en tu reino. La extensión Nano Banana usa la API de Generative Language, una puerta de enlace independiente de los servicios de Vertex AI que has estado usando. Debes habilitar esta puerta de enlace y crear una clave única para otorgar acceso al espíritu.
👉💻 En tu terminal, habilita la API:
gcloud services enable generativelanguage.googleapis.com
👉💻 Ahora, crea una clave de API, el token de acceso personal del espíritu:
- Navega a la página Credenciales de la consola de Google Cloud.
- Haz clic en + CREAR CREDENCIALES en la parte superior y selecciona Clave de API.
- Asigna a la clave de API un nombre notable, como Clave de API de Generative Language.
- En el menú desplegable de restricciones de API, elige Generative Language API.
- Crea y copia la clave, ya que la necesitarás en el siguiente paso.
👉💻 Instala la extensión Nano Banana, un espíritu creativo potenciado por los modelos especializados de texto a imagen de Gemini de Google. En tu terminal, ejecuta lo siguiente:
gemini extensions install https://github.com/gemini-cli-extensions/nanobanana
Cuando se te solicite la clave de API, pega la clave que acabas de crear y presiona Intro.
👉💻 Se necesita un último ajuste. De forma predeterminada, el entorno de Cloud Shell dirige todas las solicitudes de IA a través de Vertex AI, pero el espíritu de creación se manifiesta a través de otra puerta de enlace. Ejecuta este comando para configurar correctamente el portal de la extensión:
NANO_CONFIG=$(find ~/.gemini/extensions -name "gemini-extension.json" -path "*nanobanana*" 2>/dev/null | head -1) && \
jq '.mcpServers.nanobanana.env.GOOGLE_GENAI_USE_VERTEXAI = ""' "$NANO_CONFIG" > /tmp/nb_tmp.json && \
mv /tmp/nb_tmp.json "$NANO_CONFIG"
Ese único comando hizo todo: descargó el servidor de MCP, registró sus herramientas y, además, instaló comandos personalizados con barra, todo sin que tocaras settings.json.
👀 Nota para desarrolladores: Comparación entre extensiones y servidores de MCP sin procesar Compara esto con la configuración de Gitea. Allí, ejecutaste manualmente un comando jq para insertar una URL del servidor de MCP en settings.json. Ese enfoque "sin procesar" es valioso para comprender la mecánica, pero para la mayoría de los usos en el mundo real, se prefieren las extensiones. Agrupan el servidor de MCP, los comandos personalizados (como /generate, /edit y /story), la configuración del entorno y hasta las instrucciones contextuales (a través de un GEMINI.md incluido) en un solo paquete que se puede compartir. En la Galería de extensiones de Gemini CLI, existe un ecosistema completo de extensiones.
👉💻 Vuelve a ingresar a Gemini CLI y verifica que la extensión esté activa:
clear
cd ~/agentverse-developer/tabletop/
gemini
👉✨ Confirma que la extensión esté ajustada:
/extensions list
Ahora deberías ver nanobanana con sus herramientas y comandos.
👉✨ Con un solo comando potente, indica a la extensión de Nano Banana que cree tu sigilo. En tu Gemini CLI, ejecuta el siguiente comando:
/generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.
👉✨ La IA generará la imagen y la colocará directamente en tu espacio de trabajo local. Ahora, ordénale a la cuchilla que use este sigilo recién forjado. (ES POSIBLE QUE GEMINI YA HAYA HECHO ESTO POR TI. Revisa la respuesta anterior. Es posible que sea lo suficientemente inteligente como para hacerlo antes de que se lo pidas. ).
Modify the index.html file to add my profile picture. Use the image I just generated.
👉💻 En una terminal nueva, inicia el servidor http.
cd ~/agentverse-developer/tabletop/
python -m http.server
👀 Para ver tu trabajo, haz clic en el ícono de vista previa en la Web en la barra de herramientas de Cloud Shell. Selecciona Cambiar puerto, configúralo en 8000 y haz clic en Cambiar y obtener vista previa. Aparecerá una vista previa de tu sitio web. 
👉✨ De vuelta en la terminal que ejecuta Gemini CLI, confirma la corrección, indica que se completó la tarea y cierra el problema que registraste en los registros de la armería.
Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI.
👀 Para ver tu trabajo, haz clic en el ícono de vista previa en la Web en la barra de herramientas de Cloud Shell. Selecciona Cambiar puerto, configúralo en 3005 y haz clic en Cambiar y obtener vista previa. Aparecerá una vista previa de tu sitio web. 
👉💻 En la terminal que ejecuta el servidor HTTP, presiona Ctrl+C para salir del servidor HTTP.
PARA LOS QUE NO SON GAMERS
6. Cómo ensamblar el agente Shadowblade: Vibe coding con barreras de protección
Se acabó el tiempo de los ejercicios de práctica. Los ecos del acero sobre la piedra se desvanecen. Dominaste tu arma principal y preparaste tu arsenal para la guerra. Ahora, realizarás la verdadera prueba de un Shadowblade: ensamblarás el operativo en sí. Este es el arte de darle vida a la lógica, usando un plano sagrado del Codex para construir la inteligencia central de un agente, creando un portador sensible para las espadas de tu arsenal que puede pensar, razonar y actuar por sí mismo.
Tu primera misión es ingresar a un taller existente, una base de código prediseñada, y, a partir de sus partes, forjar a tu campeón.
El ritual de la asamblea
Antes de la primera chispa de la forja, un técnico experto inspecciona su taller y comprende cada herramienta y cada esquema. Cuando te enfrentas a un campo de batalla desconocido, como una base de código grande y existente, tu primera prioridad es el reconocimiento. Debes comprender la situación actual: la arquitectura existente, los objetivos finales y los protocolos de participación. Solo si te familiarizas con los planos y los estándares de la fortaleza podrás aportar tus habilidades de manera eficaz.
Tu CLI de Gemini, tu explorador siempre presente, puede ayudarte en este reconocimiento:
- Proporcionar resúmenes de alto nivel: Puede leer todo el códice (o la base de código) y brindarte una comprensión rápida de su propósito y componentes clave.
- Ayuda con la configuración del entorno: Puede guiarte a través de los rituales arcanos de instalación de herramientas y configuración de tu máquina.
- Navegar por bases de código: Puede actuar como tu guía y ayudarte a explorar la lógica compleja y encontrar pasajes ocultos dentro del código.
- Generar documentos de incorporación: Puede crear desplazamientos personalizados que aclaren los objetivos, los roles y los recursos para los nuevos aliados que se unen a tu causa.
- Automatiza el aprendizaje y las preguntas y respuestas: Se convierte en tu asistente personal, ya que responde preguntas sobre las funciones o el comportamiento del código, lo que te permite luchar con mayor independencia.
👉💻 En tu primera terminal, navega al directorio shadowblade y llama a tu socio de IA:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ Ahora, ordena a tu explorador que inspeccione el campo de batalla y te informe.
Analyze the entire project and provide a high-level summary.
Con el terreno existente ya mapeado, ahora debes consultar el plano de lo que vas a construir. Los operativos más eficaces no se improvisan, sino que se construyen a partir de un diseño preciso.
Nota del desarrollador: Este documento de diseño sirve como plano autorizado para el proyecto. Su propósito es garantizar la claridad en los objetivos y la implementación técnica antes de invertir un esfuerzo de desarrollo significativo. Un plan bien definido garantiza que todos los desarrolladores estén alineados, reduce el riesgo de reproceso y ayuda a evitar la deuda técnica y la expansión del alcance. Es la herramienta principal para mantener la velocidad del proyecto y la calidad del código, en especial a medida que el equipo crece o se incorporan miembros nuevos.
Un objetivo fundamental de este documento es definir no solo el "camino feliz", sino también los casos extremos y los modos de falla, en especial cuando se usan LLMs. Según mi experiencia, los LLM son excelentes para generar código optimista en el que todas las entradas son válidas y todas las llamadas externas se realizan correctamente. Para crear software sólido y listo para producción, debemos guiar explícitamente a la IA definiendo contingencias para situaciones como las siguientes:
- Se pasaron argumentos no válidos o con formato incorrecto a una función.
- Fallas en las llamadas a la API, tiempos de espera de red o códigos de error inesperados de servicios externos
- Manejo de estructuras de datos nulas o vacías en las que se esperan datos
- Condiciones de carrera o problemas de simultaneidad
Al especificar el comportamiento esperado para estos casos en el diseño, le indicamos al LLM que genere código más resistente, lo que reduce significativamente el tiempo dedicado a la refactorización manual y la corrección de errores.
👉✨ Pídele a Gemini que recupere este plan sagrado para ti.
download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md, store it as an agent_design.md file in my local folder, and show me the newly downloaded design doc. Do not attempt to create the file just yet.
👉✨ El desplazamiento es largo y detallado. Dale instrucciones a Gemini para que destile su esencia.
Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet.
Ahora tienes el plan. Pero antes de que se forje una sola línea de código, un maestro artesano establece las leyes de la forja. Se trata de disciplina y escalabilidad. Estos son los Lineamientos de Codificación. No son meras sugerencias, sino runas de poder que garantizan que cada componente se construya con la misma precisión y resistencia. Evitan que el caos del estilo individual corrompa la creación final, lo que garantiza que el agente sea resistente, fácil de mantener y puro, y permite que nuevos artesanos se unan al proyecto sin interrumpir la armonía del conjunto.
Para inscribir estas leyes directamente en la conciencia de nuestro socio de IA, usamos un artefacto especial: el archivo GEMINI.md. Cuando se invoca a Gemini CLI, se busca automáticamente este archivo y se carga su contenido en la memoria de trabajo de la IA. Se convierte en una instrucción persistente a nivel del proyecto. Actúa como un talismán que susurra constantemente las reglas de la forja a la IA.
Inscribamos estas runas ahora.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini por un momento.
👉💻 En tu terminal, ejecuta el siguiente comando para escribir el archivo de lineamientos.
cat << 'EOF' > GEMINI.md
### **Coding Guidelines**
**1. Python Best Practices:**
* **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
* **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or
Google Style.
* **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
* **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
* **Naming Conventions:**
* `snake_case` for variables, functions, and methods.
* `PascalCase` for classes.
* `UPPER_SNAKE_CASE` for constants.
* **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.
**2. Web APIs (FastAPI):**
* **Data Validation:** Use `pydantic` models for request and response data validation.
* **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
* **Error Handling:** Implement centralized error handling using middleware or exception handlers.
* **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md
Con las leyes inscritas, volvamos a convocar a nuestro socio de IA y seamos testigos de la magia del artefacto.
👉💻 Vuelve a iniciar Gemini CLI desde el directorio shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini
👉✨ Ahora, pídele a Gemini que te muestre lo que está pensando. Se leyeron las runas.
/memory show
Cómo equipar la experiencia especializada: Habilidades de agentes
Las runas GEMINI.md que grabaste son como un encantamiento permanente: siempre activo, siempre guiando tu espada. Pero un verdadero maestro no lleva todos los pergaminos a cada batalla. Algunos conocimientos son demasiado especializados o complejos para tenerlos cargados en todo momento. Aquí es donde entran en juego las habilidades del agente.
Piensa en una habilidad del agente como un pergamino sellado en tu mochila. Contiene experiencia especializada (instrucciones detalladas, secuencias de comandos y hasta datos de referencia), pero permanece inactivo hasta el momento en que lo necesitas. Solo cuando te enfrentas a un desafío que coincide con el dominio del pergamino, tu espada lo extrae y absorbe su conocimiento. Esto se denomina divulgación progresiva: mantiene tu cuchilla ágil y sin sobrecargas, y activa los poderes especializados solo cuando se necesitan.
👀 Nota para desarrolladores: Las Agent Skills son la tercera capa de la jerarquía de ingeniería de contexto de Gemini CLI:
- Configuración del usuario (
~/.gemini/settings.json): Configuración global - GEMINI.md: Es el contexto persistente a nivel del proyecto (siempre se carga).
- Habilidades de agentes (
.gemini/skills/): Experiencia a pedido (se carga cuando es necesario)
Este modelo de divulgación progresiva es fundamental para el uso empresarial: un repositorio podría contener docenas de habilidades especializadas (auditoría de seguridad, migración de bases de datos, verificaciones de cumplimiento), pero la IA solo activa las que son relevantes para la tarea actual, lo que conserva valiosos tokens de contexto.
Forjemos tu primera habilidad: un pergamino de experiencia en el ADK que tu espada puede usar cuando creas agentes.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI. Luego, crea el directorio de habilidades y graba el pergamino:
mkdir -p ~/.gemini/skills/adk-agent-design
cat << 'EOF' > ~/.gemini/skills/adk-agent-design/SKILL.md
---
name: adk-agent-design
description: Expert guidance for designing and building agents with the Google Agent Development Kit (ADK). Activate when the user asks about agent architecture, tool design, callback patterns, or ADK best practices.
---
# ADK Agent Design Expertise
When designing an ADK agent, follow these principles:
## Agent Architecture
- Define agents using `LlmAgent` with a clear `name`, `model`, `instruction`, and `tools` list.
- Keep instructions specific and action-oriented. Tell the agent what it IS, not what it should try to be.
- Use `before_model_callback` and `after_model_callback` for guardrails and validation.
## Tool Design
- Each tool should do ONE thing well. Prefer small, focused tools over large, multi-purpose ones.
- Always include descriptive docstrings — the LLM uses these to decide when to call each tool.
- Return structured data (dicts) from tools so the LLM can reason about the results.
## Testing Strategy
- Use `adk eval` with evalset JSON files for broad strategy testing.
- Use `pytest` with `AgentEvaluator` for programmatic, CI-ready tests.
- Define both `tool_trajectory_avg_score` and `response_match_score` criteria.
EOF
👉💻 Vuelve a ingresar a Gemini CLI para ver la habilidad recién creada:
cd ~/agentverse-developer/shadowblade
gemini
👉✨ Verifica que la habilidad esté en tu paquete:
/skills list
Deberías ver adk-agent-design en la lista, un pergamino sellado, inactivo y en espera.
👉✨ Ahora pídele a Gemini algo que debería activar la habilidad:
What are the best practices for designing tools in an ADK agent?
Observa cómo la respuesta ahora se basa en el conocimiento especializado que inscribiste en la habilidad. La cuchilla no tenía esta experiencia en su memoria base: descubrió el desplazamiento pertinente y lo extrajo solo cuando la pregunta coincidía. Este es un ejemplo de divulgación progresiva en acción.
Las habilidades se pueden crear para cualquier dominio (auditoría de seguridad, migración de bases de datos, verificaciones de cumplimiento) y se pueden compartir con tu equipo si se confirman en el control de versiones. Cada hoja de cada miembro del equipo adquiere la misma experiencia, que se aplica de manera coherente.
Este es el momento crucial. Proporcionarás el esquema (agent_design.md) y las leyes de la forja (GEMINI.md), y emitirás el gran hechizo de creación.
👉✨ Este es el único y potente comando que construirá tu agente. Emitir ahora:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.
Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.
Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.
and you are currently already in the shadowblade working directory
👀 Gemini ya construyó la lógica principal del agente en agent.py. El núcleo de este nuevo archivo define la inteligencia del agente, ya que conecta su modelo de razonamiento a un conjunto de herramientas externas:
PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
model="gemini-2.5-pro",
name="shadowblade_combat_agent",
instruction="""
You are the Shadowblade, an elite combat agent operating on a digital battleground.
Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
......
5. You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.
General Rules of Engagement:
- If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
- You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
tools=[
MCPToolset(
connection_params=StdioServerParameters(
command='python3',
args=[PATH_TO_MCP_SERVER]
)
)
]
)
Es el parámetro tools. El agente está diseñado para usar un MCPToolset que se conecta a un arsenal externo definido en mcp_server.py.
👀 Ve a ~/agentverse-developer/shadowblade/mcp_server.py en el editor y dedica un momento a comprender lo que hace. Es la fuente de todas las armas disponibles para Shadowblade. Actualmente, la armería está bastante vacía.
👉✨ Ordenemos a Gemini que forje siete armas nuevas para el arsenal. Envía la siguiente instrucción en Gemini CLI:
I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:
1. **A 'Refactoring Sickle'**:
- **Function Name:** `hone_refactoring_sickle`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
- **Weapon Name:** "Refactoring Sickle"
- **Damage Type:** "Cleansing"
- **Base Damage:** Random integer between 100 and 136
- **Critical Hit Chance:** Random float between 0.10 and 0.20
- **Special Effect:** "Pruning - improves code health and maintainability with each strike."
2. **A 'Quickstart Crossbow'**:
- **Function Name:** `fire_quickstart_crossbow`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
- **Weapon Name:** "Quickstart Crossbow"
- **Damage Type:** "Initiative"
- **Base Damage:** Random integer between 105 and 120
- **Critical Hit Chance:** Random float between 0.9 and 1.0
- **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."
3. **'The Gilded Gavel'**:
- **Function Name:** `strike_the_gilded_gavel`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
- **Weapon Name:** "The Gilded Gavel"
- **Damage Type:** "Finality"
- **Base Damage:** 120
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."
4. **'Daggers of Pair Programming'**:
- **Function Name:** `wield_daggers_of_pair_programming`
- **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
- **Weapon Name:** "Daggers of Pair Programming"
- **Damage Type:** "Collaborative"
- **Base Damage:** Random integer between 110 and 125
- **Critical Hit Chance:** Random float between 0.30 and 0.50
- **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."
5. **A 'Granite Maul'**:
- **Function Name:** `craft_granite_maul`
- **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
- **Weapon Name:** "Granite Maul"
- **Damage Type:** "Bludgeoning"
- **Base Damage:** Random integer between 115 and 125
- **Critical Hit Chance:** Random float between 0.05 and 0.15
- **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."
6. **A 'Lens of Clarity'**:
- **Function Name:** `focus_lens_of_clarity`
- **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
- **Weapon Name:** "Lens of Clarity"
- **Damage Type:** "Revelation"
- **Base Damage:** Random integer between 120 and 130
- **Critical Hit Chance:** 1.0
- **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."
7. **The 'Codex of OpenAPI'**:
- **Function Name:** `scribe_with_codex_of_openapi`
- **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
- **Weapon Name:** "Codex of OpenAPI"
- **Damage Type:** "Documentation"
- **Base Damage:** Random integer between 110 and 140
- **Critical Hit Chance:** Random float between 0.5 and 0.8
- **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."
👉 Una vez que Gemini confirme los cambios, abre el archivo mcp_server.py. Desplázate por el código y confirma que se agregaron correctamente las siete funciones @mcp.tool() nuevas. Verifica la función hone_refactoring_sickle. ¿Tiene la cadena de documentación y las estadísticas de armas correctas? Verificar el trabajo de la IA es un hábito fundamental del maestro Shadowblade.
Con el agente forjado y refinado, es hora de su despertar.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI
Nota del desarrollador sobre el resultado de Gemini: A veces, el código generado por Gemini puede ser impredecible. Si bien nos esforzamos por cumplir con el diseño de forma exacta, es normal que, en las sesiones de desarrollo, los desarrolladores iteren y refinen el código varias veces hasta alcanzar un estado listo para la producción.
👉💻 Para asegurarte de tener el código de producción correcto y probado a fondo en tu directorio de trabajo, ejecuta los siguientes comandos en tu terminal:
cp ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py
👉💻 En tu terminal, comienza el ritual para ponerlo en línea:
cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade
👉✨ Deberías ver un resultado que confirme que el "Agente de combate Shadowblade" está activado y en ejecución, a la espera de su primer comando. Emitir sus primeras directivas de combate
We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!
👉✨ Y otra más:
The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.
Ensamblaste correctamente tu primer agente y validaste sus capacidades de combate. Presiona Ctrl+C dos veces para que descanse tu campeón. Se completó el ensamblaje.
PARA LOS QUE NO SON GAMERS
7. Guardianes de la pureza: Evaluación de los agentes
Un agente ensamblado no es un agente probado. Una cuchilla sin probar es una responsabilidad, pero un agente de IA sin probar es un peligro mucho mayor: un elemento no controlado que podría corromper tu misión desde adentro. Esto no es una simple especulación, sino un principio fundamental que debe comprender un Shadowblade.
Evaluar agentes de IA es fundamental y, a la vez, un desafío único. A diferencia de un simple script, un agente es una fusión dinámica de tu código y la mente de razonamiento de varios pasos de un LLM. Su comportamiento es emergente. Esto significa que debes evaluar no solo la calidad del resultado final, sino también la eficiencia y la precisión de su trayectoria interna. Es la ruta que siguió para llegar allí. ¿Usó las herramientas adecuadas? ¿Generó demasiados tokens? ¿Un cambio en la versión del modelo introdujo una regresión de latencia sutil? Es fundamental detectar esta corrupción (regresiones en la latencia, el costo o la calidad del resultado) cuando se realiza cualquier cambio, desde un simple ajuste de la instrucción hasta una revisión arquitectónica importante, antes de que pueda contaminar tu entorno de producción.
El enfoque general para esta evaluación implica un ritual sagrado:
- Primero, define un "conjunto de datos de referencia": un conjunto de desplazamientos que contienen ejemplos de entradas y sus salidas o comportamientos esperados. Esto puede incluir respuestas finales, el uso correcto de herramientas o incluso trayectorias completas paso a paso.
- A continuación, definirás la lógica de la aplicación del agente, que es el núcleo de su existencia.
- Por último, estableces evaluadores, que son como runas de juicio. Pueden abarcar desde otros LLMs que actúan como jueces de calidad hasta código heurístico preciso que verifica un solo paso y funciones personalizadas que analizan todo el proceso de pensamiento de un agente.
El Kit de desarrollo de agentes (ADK) de Google es el kit de armero que se proporciona a los campeones para este propósito. Facilita esta compleja evaluación a través de varios métodos:
- Una piscina de adivinación basada en la Web (
adk web) para la evaluación interactiva - Ejecución de línea de comandos (
adk eval) para ejecutar un agente a través de una prueba predefinida. - Integración programática a través de
pytestpara inscribir bloqueos permanentes
El ADK admite dos enfoques principales: archivos de prueba simples para interacciones discretas y únicas entre el agente y el modelo (un solo duelo), y "conjuntos de evaluación" integrales para sesiones de varios turnos múltiples y potencialmente extensas (una gran refriega). Estas pueden medir métricas tan sofisticadas como tool_trajectory_avg_score, que compara el uso real de herramientas de un agente con la ruta ideal, lo que garantiza que funcione con una técnica perfecta.
Ahora que comprendes la teoría, la pondrás en práctica. Como Shadowblade, inscribirás Wards of Purity. No son solo pruebas, sino rituales potenciados por el ADK que garantizan que la lógica del agente sea impecable y su comportamiento, verdadero.
En este paso, se recomienda usar 2 terminales: una para Gemini CLI y otra para ejecutar las pruebas, ya que es posible que debas salir del directorio de trabajo actual (ADK).
El desafío de la estrategia (adk eval)
Este primer encierro es una prueba, una serie de desafíos diseñados para evaluar la inteligencia central del agente en una amplia variedad de situaciones. El objetivo es establecer un nivel de competencia de referencia. Antes de probar los casos extremos, debemos saber si el agente puede cumplir su función principal. ¿Analiza correctamente la debilidad de un monstruo y selecciona el arma más eficaz de su arsenal, no solo una vez, sino cada vez que se enfrenta a un desafío conocido?
Para ello, adk eval es la herramienta perfecta. Está diseñado para ejecutar un agente en un conjunto completo de casos de prueba predefinidos que representan las misiones esperadas del agente. Este conjunto de datos se define en un archivo JSON, un "desafío de desplazamiento" que actúa como el plano de todo el circuito.
Anatomía de un desplazamiento de desafío
👀 Antes de ordenarle a la IA que escriba un nuevo pergamino, debes comprender el idioma antiguo en el que está escrito. Analicemos la estructura del archivo sample.evalset.json.
{
"eval_set_id": "sample",
"eval_cases": [
{
"eval_id": "case0cbaa0",
"conversation": [
{
"user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
"final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
"intermediate_data": {
"tool_uses": [
{ "name": "enchant_soulshard_dagger" }
]
}
}
]
}
]
}
Este desplazamiento contiene una lista de eval_cases, en la que cada caso es una prueba única para tu agente. Dentro de cada prueba, el array de conversación documenta una sola interacción completa. Para nuestros fines, tres runas son de importancia crítica:
- user_content: Este es el desafío. Es la instrucción que le das a tu agente, el monstruo al que debe enfrentarse.
- final_response: Es el resultado profetizado. Es la cadena de texto exacta que esperas que diga tu agente cuando complete su tarea. El ADK compara las palabras finales reales del agente con esta runa para juzgar su elocuencia.
- intermediate_data.tool_uses: Esta es la técnica arcana. Para un verdadero agente, esta es la runa más importante de todas. Define no lo que dice el agente, sino lo que hace. Registra el nombre de la herramienta (enchant_soulshard_dagger) que esperas que use el agente. Esto garantiza que tu agente no solo sea un conversador inteligente, sino también un actor decisivo que toma la acción correcta.
Ahora que comprendes el esquema, le indicarás a Gemini que escriba una versión nueva y más compleja de este desplazamiento.
👉💻 En tu terminal, ingresa al directorio shadowblade y llama a Gemini CLI:
clear
cd ~/agentverse-developer/shadowblade/
gemini
👉✨ Ordena a Gemini CLI que actúe como un escriba de QA y cree una serie de casos de prueba que definan el comportamiento esperado de tu agente.
You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.
For each object within the `eval_cases` array, you must perform the following transformations:
1. **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2. **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3. **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4. **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
* If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
* If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
* If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5. **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.
Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.
La CLI confirmará que se creó el archivo sample.evalset.json. Con el desplazamiento preparado, descarta a tu socio de IA.
Datos sintéticos
👀 En el explorador de archivos de Cloud Shell que se encuentra a la izquierda, navega a ~/agentverse-developer/shadowblade/ y abre el archivo sample.evalset.json recién modificado. Analiza su contenido. Verás los monstruos nuevos y únicos, y los nombres de las herramientas correctos que le indicaste a Gemini que escribiera. Este es el resultado tangible de tu instrucción: el plano de la prueba.
Este acto de ordenar a una IA que cree datos de prueba nuevos y realistas a partir de una plantilla es una técnica poderosa conocida como generación de datos sintéticos. Lo que acabas de hacer es un multiplicador de fuerza estratégico para un Shadowblade. En lugar de crear manualmente docenas de casos de prueba únicos. Una tarea tediosa y que requiere mucho tiempo en la que proporcionaste un solo plan y le ordenaste a tu escriba de IA que lo transformara en un conjunto variado de nuevos desafíos.
Esto te permite ampliar enormemente tus esfuerzos de pruebas y crear una prueba mucho más sólida y completa de lo que sería factible de forma manual. Usaste tu agente no solo para construir la espada, sino también para forjar las piedras de afilar que prueban su filo. Esta es la marca de un verdadero maestro.
Una vez que hayas verificado que las runas son correctas, despide a tu socio de IA.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI.
Las reglas de juicio
Un desafío no tiene sentido sin reglas para la victoria. Antes de ejecutar la prueba, debes inspeccionar el Scroll of Judgment, es decir, el archivo test_config.json. Este desplazamiento le indica al ADK cómo evaluar el rendimiento de tu agente.
👀 En el explorador de archivos, abre ~/agentverse-developer/shadowblade/test_config.json. Verás las siguientes runas:
{
"criteria": {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.1
}
}
Estos son los criterios para ganar:
tool_trajectory_avg_score: Es la medida de acción. No juzga lo que el agente dice, sino lo que hace. Compara la herramienta que el agente usó en realidad con la técnica profetizada en el pergamino del desafío. Una puntuación de1.0es una coincidencia perfecta.response_match_score: Es la medida de elocuencia. Utiliza un LLM para juzgar qué tan cerca coincide semánticamente el informe final del agente con el resultado esperado. Una puntuación de1.0es una coincidencia perfecta.
Para esta primera ejecución del entrenamiento, establecimos condiciones de victoria flexibles. Los umbrales se establecen de forma extraordinariamente baja (0.0 y 0.1). El objetivo no es exigir la perfección, sino presentarte los mecanismos del juicio. Nos aseguramos de que, incluso si la redacción del agente difiere ligeramente, la sala reconocerá su competencia principal para elegir la herramienta adecuada y le permitirá el paso.
Ahora, ordena a tu agente que corra la prueba.
👉💻 En tu terminal, ejecuta el comando adk eval:
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
shadowblade \
shadowblade/sample.evalset.json \
--config_file_path shadowblade/test_config.json 2>&1 | \
awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'
👀 Deberías ver el siguiente resumen, un signo del éxito de tu agente según las reglas flexibles de esta prueba (a veces, no se aprobarán todas las pruebas):
********************************************************************* Eval Run Summary shadowblade_combat_agent_validation: Tests passed: 3 Tests failed: 0
El escudo de claridad (pytest)
La estrategia amplia probada por Gauntlet. Esta segunda sala, el Escudo de la Claridad, pone a prueba la disciplina y los comportamientos específicos. Todo se trata de la automatización. Si bien adk eval es excelente para las verificaciones manuales, el escudo pytest es una protección programática escrita en código. Esto es fundamental porque una prueba que se puede ejecutar como código se puede integrar en una canalización automatizada. Este es el objetivo final: crear una prueba de implementación (CI/CD) en la que nuestras protecciones se activen automáticamente cada vez que se realice un cambio, lo que desvía errores y regresiones antes de que puedan contaminar tu entorno de producción.
👉💻 En tu terminal,invoca a Gemini una vez más desde el directorio shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini
👉✨ Usa la siguiente instrucción en Gemini CLI para inscribir la lógica del escudo en un archivo pytest:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located in the current root working folder and name it `test_agent_initiative.py`.
The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1. **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2. **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3. **Read and parse the JSON file**:
* Open the file at `eval_set_filepath`.
* Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4. **Create an `EvalSet` object**:
* Instantiate an `EvalSet` object named `eval_set_object`.
* Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5. **Call the evaluation method**:
* `await` a call to `AgentEvaluator.evaluate_eval_set`.
* Pass the following arguments:
* `agent_module="shadowblade"`
* `eval_set=eval_set_object`
* `criteria=evaluation_criteria`
* `print_detailed_results=True`
The script must include the necessary imports at the top:
* `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
* `EvalSet` from `google.adk.evaluation.eval_set`
* `pytest`
* `json`
Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.
Con las runas del segundo cerrojo grabadas, sal de Gemini CLI.
👉💻 Presiona Ctrl+C dos veces.
👀 En el explorador de archivos, abre el desplazamiento que le acabas de pedir a Gemini que escriba: ~/agentverse-developer/test_agent_initiative.py.
Notarás que no se trata solo de un archivo de configuración, sino de una invocación escrita en lenguaje Python. La parte principal de este hechizo es la línea await AgentEvaluator.evaluate(...).
....
@pytest.mark.asyncio
async def test_agent_initiative():
# Define the evaluation criteria
evaluation_criteria = {
"tool_trajectory_avg_score": 0.0,
"response_match_score": 0.0
}
# Define the path to your evalset file
eval_set_filepath = "shadowblade/test.evalset.json"
#...
# 3. Call the evaluation method with the correctly typed object
await AgentEvaluator.evaluate_eval_set(
agent_module="shadowblade",
eval_set=eval_set_object,
criteria=evaluation_criteria,
print_detailed_results=True,
)
Observa atentamente sus argumentos. Son los mismos componentes que usaste en la última prueba: tu agente shadowblade y el desplazamiento de desafío shadowblade.evalset.json. Esto debería revelar una verdad profunda: el comando adk eval que usaste antes es una invocación poderosa, pero esta secuencia de comandos pytest eres tú, el hechicero, quien lanza el hechizo subyacente. La herramienta de línea de comandos es simplemente un wrapper conveniente alrededor de la misma biblioteca principal de AgentEvaluator que ahora usas directamente. Este es un paso fundamental para dominar la herramienta, ya que los hechizos lanzados a través del código se pueden entrelazar en los telares automatizados de una canalización de CI/CD.
Ahora que comprendes la magia, realiza el ritual para activar el escudo.
👉💻 En tu terminal, ejecuta el ritual para activar el escudo:
cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py
👀 Busca el resumen de los resultados de la prueba al final del registro de salida. Un resultado aprobatorio confirma que tu agente sigue correctamente sus protocolos y que la sala está lista para integrarse en tus defensas automatizadas.
====== 1 passed, 4 warning in 37.37s ======
Nota: Si la prueba falla de forma inesperada, es muy probable que hayas agotado la cantidad de solicitudes que puedes realizar al modelo por minuto. Busca un error RESOURCE_EXHAUSTED en el resultado del registro. Si ves este error, espera uno o dos minutos para que se restablezca tu cuota y, luego, vuelve a ejecutar el comando pytest.
Con el amplio Gauntlet y el preciso Shield inscritos y verificados, tu agente no solo es funcional, sino que es puro, probado y está listo para la implementación.
PARA LOS QUE NO SON GAMERS
Wards of Vigilance: Hooks de Gemini CLI
Los Guardianes de la Pureza prueban a tu agente después de la batalla. Pero ¿qué sucede durante la batalla? Un Shadowblade disciplinado no solo prueba después de los hechos, sino que coloca centinelas vigilantes que observan cada golpe a medida que sucede y que interceptan las acciones peligrosas o imprudentes antes de que puedan causar daño.
Estos centinelas son Gemini CLI Hooks, secuencias de comandos que se ejecutan en puntos específicos del bucle del agente. Permiten interceptar, validar y personalizar el comportamiento del agente sin modificar su código.
👀 Nota para desarrolladores: Los hooks se activan por eventos en el ciclo de vida del agente:
BeforeTool: Se activa antes de que se ejecute una herramienta, lo que es ideal para la validación de seguridad ("¿Es seguro este comando de shell?").AfterTool: Se activa después de que se ejecuta una herramienta, lo que resulta útil para auditar los resultados y registrar información.BeforeAgent: Se activa antes de que el agente comience a razonar. Puede insertar contexto adicional o bloquear instrucciones peligrosas.AfterAgent: Se activa después de que finaliza el agente. Puede rechazar respuestas de baja calidad y forzar reintentos.
Los hooks se configuran en settings.json y se ejecutan de forma síncrona. El agente espera a que se completen antes de continuar. Esto las hace ideales para aplicar políticas de seguridad, verificaciones de cumplimiento y controles de calidad en entornos empresariales.
Inscribamos una protección simple que supervise el uso de herramientas del agente.
👉💻 En tu terminal, crea una secuencia de comandos de hook:
mkdir -p ~/agentverse-developer/.gemini/hooks
cat << 'EOF' > ~/agentverse-developer/.gemini/hooks/tool_logger.sh
#!/bin/bash
# A ward that logs every tool call to a file for auditing
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
echo "$(date '+%H:%M:%S') ⚔️ [WARD] Tool invoked: $TOOL_NAME" >> /tmp/tool_ward.log
echo '{"decision": "allow"}'
EOF
chmod +x ~/agentverse-developer/.gemini/hooks/tool_logger.sh
👉💻 Ahora registra este hook en un archivo de configuración a nivel del proyecto:
mkdir -p ~/agentverse-developer/.gemini
cat << 'EOF' > ~/agentverse-developer/.gemini/settings.json
{
"hooks": {
"BeforeTool": [
{
"matcher": "*",
"hooks": [
{
"name": "tool-logger",
"type": "command",
"command": "$GEMINI_PROJECT_DIR/.gemini/hooks/tool_logger.sh",
"timeout": 5000
}
]
}
]
}
}
EOF
Este resguardo es simple, pero poderoso. Cada vez que el agente intenta usar una herramienta (cualquiera), primero se activa el gancho, registra el nombre de la herramienta en un registro de auditoría y, luego, permite que continúe la acción. En un entorno de producción, podrías reemplazar "allow" por "deny" para bloquear operaciones peligrosas (como evitar que el agente borre archivos), aplicar políticas de revisión de código o enrutar llamadas a herramientas sensibles a través de un flujo de trabajo de aprobación.
👉💻 Vuelve a ingresar a Gemini CLI para verificar que el gancho esté activo:
cd ~/agentverse-developer
gemini
👉✨ Verifica que el hook esté registrado:
/hooks
Deberías ver el gancho tool-logger en la lista y habilitado. Presiona Escape para descartar el menú de autocompletar si aparece.
👉✨ Ahora activa una llamada a la herramienta para probar la sala:
What files are in the current directory?
El agente llamará a una herramienta para leer el directorio. El candado interceptó silenciosamente este intento. Veamos la prueba.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI y, luego, inspecciona el registro de auditoría de la sala:
cat /tmp/tool_ward.log
Deberías ver una entrada como la siguiente:
15:42:07 ⚔️ [WARD] Tool invoked: list_directory
Tu tutor interceptó, registró y permitió cada llamada a una herramienta que realizó el agente. En un entorno empresarial real, este registro se podría enviar a un sistema SIEM (administración de información y eventos de seguridad), lo que activaría alertas por uso sospechoso de herramientas o aplicaría registros de auditoría de cumplimiento.
8. Cómo liberar Blade en Agentverse: CI y Deployment
Los Guardianes de la Pureza ensamblaron tu agente y verificaron su integridad. Sin embargo, una protección que no se mantiene de forma constante es solo una reliquia olvidada. Para garantizar que cada versión futura de tu agente siga siendo pura, debes crear la primera etapa de la prueba de implementación, un ritual automatizado que garantiza la calidad y la velocidad.
Como Shadowblade, tu deber sagrado es la integración continua (CI). Este es el sistema automatizado de la forja y el campo de pruebas. Es tu defensa definitiva contra la corrupción y el error humano. Este ritual garantiza que, cada vez que tú o un aliado aporten una nueva técnica (combinen código) al códice central (tu repositorio), el guantelete se despierte automáticamente. Primero, se crea el agente a partir del código nuevo y, luego, se somete de inmediato a los Guardianes de la Pureza que acabas de crear. Si falla alguna protección, el ritual se detiene y el artefacto defectuoso se rechaza de inmediato, lo que evita que corrompa la armería. Tu dominio es la forja, y tu canalización de CI garantiza que solo los artefactos perfectos y listos para la batalla salgan de tu taller.
Una vez que tu CI demuestra que un artefacto es apto, comienza la segunda etapa del ritual: la implementación continua (CD). Este es el dominio de The Guardian. Es su deber solemne tomar tu artefacto perfeccionado y contenerizado, y liberarlo de forma segura en el Agentverse en vivo, administrar su poder y garantizar su estabilidad contra el caos de The Static.
En este códice, dominarás tu rol. Construirás la parte de CI de la prueba. Compilarás la forja automatizada que prueba tu agente y sella el resultado puro en un contenedor, preparándolo para la bendición final de The Guardian.
👀 Nota para desarrolladores: En el mundo real, la administración de flujos de trabajo complejos de CI/CD se puede optimizar con extensiones especializadas como Conductor (gemini extensions install https://github.com/gemini-cli-extensions/conductor). Conductor convierte la CLI de Gemini en un administrador de proyectos que sigue un protocolo estricto: Context → Spec & Plan → Implement. Incluye comandos personalizados (/conductor:setup, /conductor:newTrack, /conductor:implement) y plantillas de flujos de trabajo para administrar todo el ciclo de vida de tus tareas. Garantiza un bucle coherente de Contexto -> Especificación y Plan -> Implementación. Este es un ejemplo del mundo real de cómo las extensiones y los comandos se unen para actuar como un gerente de proyectos proactivo y estandarizar todo el ciclo de vida del desarrollo.
Ahora usarás Google Cloud Build para escribir el desplazamiento de este ritual de CI. Un archivo cloudbuild.yaml que define cada paso de tu proceso de creación y prueba.
👉💻 Debido a la estructura del proyecto del ADK, la configuración de la canalización de CI/CD debe residir en el directorio principal. En la terminal, navega al directorio principal y reinicia Gemini CLI.
cd ~/agentverse-developer/
clear
gemini
👉✨ Ahora, emite el siguiente comando a Gemini. Esta instrucción actúa como un documento de diseño, en el que se detallan los pasos de la prueba que deseas que genere.
You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.
Generate the `cloudbuild.yaml` with the following exact specifications:
1. **A top-level `substitutions` block** containing these four key-value pairs:
* `_PROJECT_ID: "$PROJECT_ID"`
* `_REGION: "$REGION"`
* `_REPO_NAME: "$REPO_NAME"`
* `_IMAGE_TAG: "latest"`
2. **A `steps` block** with two steps:
* **Step 1: 'Run Pytest Ward'**
* `id`: 'Run Pytest Ward'
* `name`: 'python:3.12-slim'
* `entrypoint`: 'bash'
* `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
```shell
pip install -r shadowblade/requirements.txt && \
pytest test_agent_initiative.py
```
* The step must include an `env` block with this exact list of three environment variables:
* `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
* `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
* `'GOOGLE_CLOUD_LOCATION=$_REGION'`
* **Step 2: 'Forge Container'**
* `id`: 'Forge Container'
* `name`: 'gcr.io/cloud-builders/docker'
* It must have a `waitFor` key for `['Run Pytest Ward']`.
* Its `args` must be a list of six specific strings in this exact order:
1. `'build'`
2. `'-t'`
3. `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
4. `'-f'`
5. `'./shadowblade/Dockerfile'`
6. `'.'`
3. **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.
Generate only the complete and exact YAML that meets these specifications.
Con el pergamino de cloudbuild.yaml preparado, ordena a Google Cloud que ejecute toda la prueba.
👉💻 Presiona Ctrl+C dos veces para salir de Gemini CLI.
👉💻 En tu terminal, ejecuta la canalización desde el directorio raíz de tu proyecto:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"
Ahora puedes ver en la página Google Build de Google Cloud Console cómo se ejecuta cada paso de tu ritual automatizado. Primero, ejecutará las pruebas y, cuando vea que se completaron correctamente, creará y almacenará el contenedor de tu agente.
Tu agente superó la prueba. Ahora tienes en tu arsenal un artefacto puro y verificado. El acto final es tuyo. Con una sola invocación, llamarás a este artefacto desde el registro y le darás vida como un servicio público en Cloud Run.
👉💻 En tu terminal, ejecuta el comando de implementación final:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
--image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
--platform=managed \
--labels="dev-tutorial-codelab=agentverse" \
--region=${REGION} \
--set-env-vars="A2A_HOST=0.0.0.0" \
--set-env-vars="A2A_PORT=8080" \
--set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
--set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
--set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
--set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
--allow-unauthenticated \
--project=${PROJECT_ID} \
--min-instances=1
Felicitaciones, Shadowblade. Los rituales del códice están completos. Llegó el momento de demostrar su valía. Un Spectre, nacido del caos que aprendiste a domar, espera tu desafío. Prepárate para la prueba final.
PARA LOS QUE NO SON GAMERS
9. La pelea final
Se leyeron los pergaminos, se realizaron los rituales y se superó la prueba. Tu agente no es solo un artefacto almacenado, sino un campeón forjado en código, un centinela activo en el Agentverse que espera su primer comando. Llegó el momento de demostrar su valía en el crisol del combate.
Ahora participarás en una simulación de fuego real para enfrentar a tu Shadowblade recién desplegado contra un Spectre formidable, una encarnación del caos que azota toda la creación. Esta es la prueba definitiva de tu trabajo, desde la lógica central del agente hasta su implementación impecable.
Adquiere el Locus de tu agente
Antes de ingresar al campo de batalla, debes tener dos llaves: la firma única de tu campeón (Agent Locus) y la ruta oculta a la guarida de Spectre (URL de Dungeon).
👉💻 Primero, obtén la dirección única de tu agente en Agentverse, es decir, su Locus. Este es el extremo en vivo que conecta a tu campeón con el campo de batalla.
. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app
👉💻 A continuación, indica el destino con precisión. Este comando revela la ubicación del círculo de translocación, el portal hacia el dominio de Spectre.
. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app
Importante: Ten listas ambas URLs. Los necesitarás en el paso final.
Confrontando al Spectre
Con las coordenadas aseguradas, ahora navegarás al círculo de translocación y lanzarás el hechizo para ir a la batalla.
👉 Abre la URL del círculo de translocación en tu navegador para pararte frente al brillante portal que lleva a La Fortaleza Carmesí.
Para entrar en la fortaleza, debes sintonizar la esencia de tu Shadowblade con el portal.
- En la página, busca el campo de entrada rúnica etiquetado como URL de extremo de A2A.
- Inscribe el sello de tu campeón pegando su URL de Agent Locus (la primera URL que copiaste) en este campo.
- Haz clic en Conectar para liberar la magia de la teletransportación.
La luz cegadora de la teletransportación se desvanece. Ya no estás en tu santuario. El aire crepita con energía, fría y aguda. Ante ti, se materializa el Espectro: un vórtice de estática sibilante y código corrupto, cuya luz impía proyecta largas sombras danzantes por el suelo de la mazmorra. No tiene rostro, pero sientes su presencia inmensa y agotadora fijada por completo en ti.
Tu único camino hacia la victoria radica en la claridad de tu convicción. Es un duelo de voluntades que se libra en el campo de batalla de la mente.
Mientras te lanzas hacia adelante, listo para desatar tu primer ataque, el Espectro contraataca. No levanta un escudo, sino que proyecta una pregunta directamente en tu conciencia: un desafío rúnico y brillante extraído del núcleo de tu entrenamiento.
Esta es la naturaleza de la lucha. Tu conocimiento es tu arma.
- Responde con la sabiduría que has adquirido, y tu espada se encenderá con energía pura, destrozando la defensa del Espectro y asestando un GOLPE CRÍTICO.
- Pero si vacilas, si la duda nubla tu respuesta, la luz de tu arma se atenuará. El golpe se asestará con un golpe sordo patético, y solo infligirá UNA FRACCIÓN DE SU DAÑO. Peor aún, el Spectre se alimentará de tu incertidumbre, y su poder corruptor crecerá con cada paso en falso.
Eso es todo, campeón. Tu código es tu libro de hechizos, tu lógica es tu espada y tu conocimiento es el escudo que detendrá la marea del caos.
Enfoque: El golpe es verdadero. El destino del Agentverse depende de ello.
Felicitaciones, Shadowblade.
Completaste el códex correctamente. Tomaste una "vibe", la tradujiste en un diseño y usaste Gemini CLI para ensamblar un agente inteligente. Inscribiste protecciones de pureza para probar su lógica, construiste un guante automático para forjarla en un artefacto y la liberaste en el Agentverse. Por último, validaste su propósito en una prueba de fuego real. Dominaste el flujo de trabajo de agentes de pila completa y ahora estás listo para cualquier desafío que te proponga Agentverse.
10. Limpieza: Recuperación de Agentverse
¡Felicitaciones por dominar el Códice de Shadowblade! Para garantizar que Agentverse permanezca en perfectas condiciones y que tus campos de entrenamiento estén despejados, ahora debes realizar los rituales de limpieza finales. Esta acción quitará todos los recursos creados durante tu recorrido.
Desactiva los componentes de Agentverse
Ahora desmantelarás sistemáticamente los componentes implementados de tu Agentverse.
Borra el agente de Shadowblade en el repositorio de Cloud Run y Artifact Registry
Este comando quita el agente de Shadowblade implementado de Cloud Run y quita el repositorio de imágenes en el que se almacenó la imagen del contenedor del agente.
👉💻 En tu terminal, ejecuta lo siguiente:
. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet
Limpia los archivos y directorios locales (Cloud Shell)
Por último, borra de tu entorno de Cloud Shell los repositorios clonados, las extensiones instaladas y los archivos creados. Este paso es opcional, pero se recomienda para limpiar por completo tu directorio de trabajo.
👉💻 En tu terminal, ejecuta lo siguiente:
rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -f ~/project_id.txt
gemini extensions uninstall nanobanana
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including extensions, skills, and hooks.
Ya borraste correctamente todos los rastros de tu recorrido por Agentverse. Tu proyecto está limpio y listo para tu próxima aventura.