En Agent Studio, puedes diseñar tus instrucciones y realizar iteraciones sobre ellas, así como comparar los resultados de diferentes configuraciones y modelos. Una vez que termines de diseñar tu instrucción, puedes implementarla como una aplicación web para compartirla con tus colaboradores o usuarios objetivo para que prueben la aplicación web. La aplicación web se aloja en Cloud Run y está disponible fuera de la consola de Google Cloud .
En esta guía de inicio rápido, puedes hacer lo siguiente:
- Crea una instrucción con variables
- Implementa tu instrucción como una aplicación web
- Supervisa el progreso de la implementación y prueba la aplicación implementada
- Actualiza y vuelve a implementar tu instrucción
- Envío de prueba de instrucciones con compatibilidad multimodal
Antes de comenzar
Si nunca usaste Agent Studio, puedes seguir otra guía de inicio rápido o realizar el curso de Google Cloud Skills Boost para aprender los conceptos básicos de Agent Studio. En esta guía, deberías tener lo siguiente:
- Un proyecto de Google Cloud con facturación y la API de Agent Platform habilitadas.
- Los roles necesarios para implementar una instrucción de Agent Studio como una aplicación web Si creaste un proyecto nuevo para esta guía, ya tienes los permisos necesarios.
De manera opcional, también puedes asegurarte de que la cuenta de servicio predeterminada de Compute Engine tenga los roles necesarios para la cuenta de servicio de implementación. Si tienes permiso para otorgar roles, puedes otorgar estos roles cuando implementes tu aplicación.
Roles obligatorios
Para obtener los permisos que necesitas para implementar una instrucción de Agent Studio como una aplicación web, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:
- Usuario de Agent Platform (
roles/aiplatform.user) -
Habilita las APIs necesarias:
Administrador de Service Usage (
roles/serviceusage.serviceUsageAdmin) -
Otorga los roles necesarios a la cuenta de servicio predeterminada de Compute Engine:
Administrador de IAM del proyecto (
roles/resourcemanager.projectIamAdmin) -
Implementa una aplicación de Cloud Run:
- Administrador de Cloud Run (
roles/run.admin) - Desarrollador de origen de Cloud Run (
roles/run.sourceDeveloper)
- Administrador de Cloud Run (
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.
Roles necesarios para la cuenta de servicio de implementación
Para garantizar que la cuenta de servicio predeterminada de Compute Engine tenga los permisos necesarios para ejecutar compilaciones en tu nombre, pídele a tu administrador que otorgue los siguientes roles de IAM a la cuenta de servicio predeterminada de Compute Engine en tu proyecto:
- Agente de servicio de Agent Platform (
roles/aiplatform.serviceAgent) - Cuenta de servicio de Cloud Build (
roles/cloudbuild.builds.builder)
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
Es posible que tu administrador también pueda otorgarle los permisos necesarios a la cuenta de servicio predeterminada de Compute Engine a través de roles personalizados o de otros roles predefinidos.
Si tienes permiso para otorgar roles, puedes otorgar estos roles cuando implementes tu aplicación.
Crea una instrucción con variables
Navega a la página para crear instrucciones de Agent Studio y, luego, haz clic en Agregar variable en la casilla de entrada de instrucciones.
En el diálogo Administrar variables de instrucción, ingresa un nombre de variable y asígnale un valor. Luego, haz clic en Aplicar.
En el cuadro de entrada de la instrucción, compón la instrucción con la variable y, luego, ajusta otros parámetros. Por ejemplo, puedes habilitar la Fundamentación con la Búsqueda de Google y establecer "Siempre obtén el clima actual de la Web" como las instrucciones del sistema.
Implementa tu instrucción como una aplicación web
Para implementar tu instrucción como una aplicación web, haz clic en y, luego, en Implementar como app.
Guarda la instrucción
Aparecerá el diálogo para guardar la instrucción, ya que es necesario guardarla antes de poder implementarla. El diálogo de implementación se abrirá automáticamente una vez que se haya guardado la instrucción.
Habilita las APIs para la primera implementación y otorga permisos
- Una vez que se guarde la instrucción, continuará el proceso de implementación. Si es tu primera implementación, verás un diálogo para habilitar las APIs requeridas. Haz clic en Habilitar las APIs obligatorias.
-
Después de habilitar las APIs, aparecerá el diálogo Crear una app web. Puedes elegir Exigir autenticación (a través de Identity-Aware Proxy) o Permitir acceso público.
- Si se elige la autenticación obligatoria, sigue la guía para otorgar acceso (inclúyete).
- Cuando seleccionas Permitir acceso público, significa que cualquier persona puede acceder a la app. Por lo tanto, no incluyas información sensible ni información de identificación personal (PII) en tu instrucción. Marca la casilla de verificación Entiendo que esta app se implementará de forma pública para confirmar.
- Haz clic en Crear app para iniciar la implementación.
- Si esta es tu primera implementación, aparecerá otro diálogo en el que se te pedirá que otorgues los roles necesarios a la cuenta de servicio. Haz clic en Otorgar todo para continuar.
Comienza la Deployment
Agent Studio creará un archivo ZIP que contiene el código fuente de la aplicación web y lo subirá a un bucket de Cloud Storage. Después de que se inicie la implementación, aparecerá el cuadro de diálogo Administrar app web con información sobre la implementación, como el nombre de la aplicación, la fecha de la última implementación, el estado de la implementación y mucho más.
Supervisa el estado de la implementación
Deployment tarda entre 2 y 3 minutos en completarse, y el estado de la implementación se muestra en la columna Estado del diálogo Administrar app web. Si cierras el diálogo Administrar app web, puedes volver a abrirlo desde el menú que se encuentra debajo del botón Compilar con código.
Una vez que se complete la implementación, la columna de estado cambiará a Listo y aparecerá el botón Abrir junto al nombre de la aplicación.
Control de acceso y clave secreta
Tu aplicación web se implementa con el control de acceso Permitir sin autenticar habilitado de forma predeterminada. Para desactivarla, haz clic en el botón con el ícono de lápiz . Consulta la sección Desactiva el acceso público para obtener más información.
Para brindar protección básica, la aplicación web requiere que se agregue una clave secreta a la URL para enviar la instrucción. Puedes encontrar la clave secreta en la columna Clave secreta. Si abres la aplicación web desde Agent Studio, la clave se agregará a la URL.
Abre la aplicación web y envía la instrucción
Haz clic en Abrir en el diálogo Administrar app web para acceder a la aplicación implementada. La aplicación se debe abrir con la clave secreta agregada a la URL en el formato de ?key=SECRET_KEY.
Ingresa un valor para la variable y, luego, haz clic en Enviar. Deberías poder ver los resultados a la derecha.
Abre la aplicación web desde el menú del botón Compilar con código
Si tu aplicación web está lista, también puedes abrirla desde el menú del botón Compilar con código.
Cloud Run es un servicio sin servidores, lo que significa que el contenedor de la aplicación se cerrará si no se usa de forma activa. Por lo tanto, a veces, la aplicación web puede tardar unos segundos en cargarse, o bien un envío no funcionará si dejaste la aplicación web inactiva durante demasiado tiempo. Actualizar la página debería resolver este problema.
Cómo supervisar el estado desde la campana de notificaciones
También puedes supervisar el estado desde el menú Notificaciones haciendo clic en el ícono de campana. El ícono de campana detendrá su animación de carga y mostrará un círculo verde si la implementación se completó correctamente.
Si haces clic en la notificación, se te redireccionará a la página de Cloud Run. La URL en la página de Cloud Run no tiene la clave secreta agregada. Deberás agregarlo manualmente en el formato ?key=SECRET_KEY.
Actualiza y vuelve a implementar tu instrucción
Puedes editar aún más tu instrucción en Agent Studio y convertirla en una conversación. Luego, haz clic en el botón Compilar con código y en Administrar app para abrir el diálogo Administrar app web. Haz clic en Actualizar app para volver a implementar tu aplicación web con la instrucción actualizada.
Aparecerá un cuadro de diálogo de confirmación. Te indica que, si vuelves a implementar, perderás los cambios que hayas realizado en la aplicación web implementada fuera de Agent Studio (por ejemplo, en el editor de código fuente de Cloud Run). Haz clic en Confirmar para continuar.
Volverá a aparecer el diálogo Administrar app web. El proceso es similar al de la implementación inicial. Puedes supervisar el progreso de la misma manera que la primera implementación.
Una vez que se complete la actualización, podrás volver a abrir la aplicación web. Verás la IU de conversación con la variable de instrucción. Completa el valor y escribe cualquier contenido no vacío para continuar la conversación.
Inserta contenido multimodal
Puedes insertar entradas como imágenes, videos, audio y documentos en la IU de conversación. Las entradas admitidas dependen del modelo seleccionado para la instrucción. Consulta la documentación sobre la compatibilidad multimodal para cada modelo.
Para insertar un archivo, haz clic en el botón con el ícono de clip en el cuadro de entrada de la conversación.
Podrás interactuar con el modelo con la entrada que proporciones.
Temas avanzados
Una vez que te familiarices con el proceso de implementación, puedes considerar las siguientes acciones.
Edita el código fuente en Cloud Run
Si quieres personalizar la aplicación web, puedes hacer cambios en el código fuente en Cloud Run. Abre la página del código fuente de Cloud Run desde el diálogo Administrar app web haciendo clic en el botón de ícono de más al final de la fila.
Como alternativa, también puedes navegar a la página de seguridad desde la aplicación web haciendo clic en el vínculo del editor de código fuente.
En la página del código fuente de Cloud Run, haz clic en Editar fuente para iniciar el modo de edición. Cuando termines, haz clic en Guardar y volver a implementar.
Una vez que se complete la nueva implementación, deberás abrir la aplicación desde Agent Studio. Puedes navegar a la página de Agent Studio desde el vínculo en la insignia Se implementó desde Agent Platform.
Otorgar acceso
Para otorgar acceso a la app a usuarios o grupos, sigue estos pasos:
- Abre el diálogo Administrar app web.
- Haz clic en el ícono de lápiz en la columna Control de acceso. Se abrirá la página de seguridad de Cloud Run en una pestaña nueva.
- En la página de seguridad de Cloud Run, busca la casilla de verificación de Identity-Aware Proxy (IAP). Asegúrate de que esté marcada y, luego, haz clic en Editar política.
-
Aparecerá una subtarea para que puedas editar el acceso. Ingresa los correos electrónicos de usuarios o grupos en el campo Principal.
Si eres usuario de una organización, solo puedes agregar usuarios de la misma organización.
- Deja el campo de niveles de acceso vacío.
- Haz clic en Guardar.
-
Después de cerrar la subtarea, vuelve a hacer clic en Guardar en la página de Cloud Run.
Desactiva el acceso público
Cuando no necesites que la aplicación web sea de acceso público, puedes desactivarla en Cloud Run. Abre el diálogo Administrar app web y haz clic en el ícono de lápiz en la columna Control de acceso. Se abrirá la página de seguridad de Cloud Run en una pestaña nueva.
También puedes navegar a la página de seguridad desde la aplicación web haciendo clic en el vínculo Configuración de seguridad.
En la página Seguridad del servicio de Cloud Run correspondiente a tu aplicación web, marca Usar Cloud IAM para autenticar las solicitudes entrantes y elige Requerir autenticación. Haga clic en Guardar.
Esto hará que tu aplicación web ya no sea accesible a través de la URL. Si intentas acceder a ella, verás la página Error: Forbidden.
Cómo volver a activar el acceso público
Si quieres volver a activar el acceso público, desmarca la casilla de verificación Usar Cloud IAM para autenticar las solicitudes entrantes y guarda los cambios. Si eliges la opción Permitir invocaciones no autenticadas, no funcionará si tu proyecto está en una organización. Consulta Autenticación en Cloud Run para obtener más detalles.
Configura el acceso local para el desarrollo
En la versión preliminar pública, aún no se admite el control de acceso. Por lo tanto, una vez que desactives el acceso público, la única forma de acceder a la aplicación web será configurar un proxy local. Puedes hacerlo a través de los comandos de gcloud. Primero, abre Cloud Shell con el botón del ícono de terminal en la esquina superior derecha de la consola de Google Cloud . Se te pedirá que autorices Cloud Shell. Haz clic en Autorizar para continuar.
Cuando termines, abre el diálogo Administrar app web y haz clic en el botón de ícono de más al final de la fila para ver más acciones. Haz clic en Configurar el acceso local a través de Cloud Shell.
Se agregará un comando a tu instancia de Cloud Shell. Presiona Intro y espera a que termine de imprimirse. Haz clic en el vínculo de la línea que comienza con Click on the
link to preview. Podrás ver tu solicitud. Este vínculo solo funciona cuando se ejecuta el comando de gcloud.
Problemas comunes
Error de autenticación: No hay clave secreta
Si ves el siguiente error, significa que no se agregó ninguna clave secreta a la
URL. Sigue las instrucciones para abrir la aplicación
web desde Agent Studio o copia la clave secreta del
diálogo Administrar app y agrégala a la URL con el formato
?key=SECRET_KEY.
Error de autenticación: Clave secreta no válida
El siguiente error significa que la clave agregada a la URL no es válida. La clave secreta es única para cada instrucción. Si tienes una clave secreta de otro mensaje, no funcionará. Sigue las instrucciones para abrir la aplicación web correctamente.
400 Argumento no válido: entrada vacía
El siguiente error ocurre cuando tienes entradas en la variable de instrucción, pero el chat está vacío; aparecerá un mensaje de error 400. Para solucionar este problema, escribe cualquier texto que no esté vacío y vuelve a enviarlo.
400 Invalid argument: mimeType is not supported
Si eliges un tipo de archivo que el modelo no admite, se devolverá un error 400. Esto es normal, y deberás usar otros tipos de archivos compatibles con el modelo. Consulta la documentación sobre la compatibilidad multimodal de cada modelo.
¿Qué sigue?
Descripción general de la compilación
Aprende a crear agentes en Google Agent Platform.
Guía de inicio rápido de Agent Studio: Envía instrucciones de texto a Gemini
Aprende a enviar instrucciones de texto a Gemini con Agent Studio.