Crea un agente de IA que actúe en nombre del usuario con Agent Identity and Auth Manager

1. Introducción

Un agente con su propia credencial con un permiso amplio ve los datos de todos. En este codelab, compilarás un agente que llama a una API de terceros con las credenciales del usuario que accedió, de modo que vea exactamente lo que esa persona puede ver y nada más.

Lo crearás con el Kit de desarrollo de agentes (ADK) de Google y Gemini Enterprise.

Específicamente, aprenderás a diseñar una arquitectura de identidad doble en la que se cumpla lo siguiente:

  1. El agente actúa en su propio nombre (identidad del agente): Con una identidad del agente respaldada por SPIFFE, el agente invoca Auth Manager, almacena la telemetría y llama a las APIs de Google Cloud.
  2. El agente actúa en nombre del usuario (identidad delegada por el usuario): Para acceder a recursos externos como GitHub, el agente activa un flujo de consentimiento de OAuth de 3 etapas (3LO) para consultar herramientas de forma segura con las credenciales del usuario.

Arquitectura de identidad dual

Para lograrlo, aprenderás a hacer lo siguiente:

  1. Crear un agente del ADK que se conecte al servidor del Protocolo de contexto del modelo (MCP) de GitHub
  2. Actualiza la herramienta del agente de un PAT (token de acceso personal) estático de GitHub a un flujo de OAuth de 3 etapas (3LO) con Google Cloud Auth Manager.
  3. Implementar el agente de forma segura en Agent Runtime y aprovisionar Agent Identity
  4. Configura roles de IAM para proporcionar a la identidad del agente acceso a la bóveda de tokens en nombre del usuario.
  5. Comprender el flujo de 3LO de extremo a extremo para Auth Manager en Google Cloud

Requisitos previos

Antes de comenzar, asegúrate de contar con los siguientes aspectos:

  • Un proyecto de Google Cloud con la facturación habilitada.
  • El SDK de Google Cloud (CLI de gcloud) instalado y autenticado en tu proyecto en tu máquina local. Se requiere la versión 586.0.0 o una posterior: ejecuta gcloud components update.
  • Python 3.10 a 3.13 instalado de forma local
  • El administrador de paquetes uv instalado (pip install uv).
  • Una cuenta de GitHub para registrar una aplicación de OAuth y crear tokens. Si no tienes una cuenta de GitHub, puedes sustituirla por cualquier servidor de MCP de terceros que admita OAuth de tres segmentos.

2. Configuración del proyecto

1. Autentícate en Google Cloud

Autentícate en Google Cloud desde tu línea de comandos local para asegurarte de que tu entorno tenga los permisos necesarios para implementar en Agent Runtime, aprovisionar la identidad del agente y configurar Auth Manager durante este lab.

Ejecuta los siguientes comandos para acceder a tu cuenta de Google Cloud, establecer tu proyecto activo (reemplaza YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud) y configurar las credenciales predeterminadas de la aplicación (ADC):

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login

2. Habilita los servicios de Google Cloud necesarios

Habilitar las APIs necesarias en tu proyecto de Google Cloud para ejecutar este lab Ejecuta el siguiente comando en la terminal:

gcloud services enable \
    agentidentity.googleapis.com \
    agentregistry.googleapis.com \
    aiplatform.googleapis.com \
    apphub.googleapis.com

Este comando puede tardar un minuto en ejecutarse. Una vez que finalice, volverá al símbolo del sistema y confirmará que las APIs están activas.

3. Instala la CLI de agentes y configura el proyecto

agents-cli es la herramienta de línea de comandos que se usa para estructurar, administrar, probar e implementar agentes del ADK en Gemini Enterprise. Instálalo de forma local:

uvx google-agents-cli setup

Verifica la instalación:

agents-cli --help

Deberías ver el menú de ayuda de la CLI con los comandos disponibles (como deploy, run y status).

Generar la estructura inicial del proyecto Comenzarás con un prototipo local y, luego, lo mejorarás para implementarlo en Agent Runtime:

agents-cli create secure-agent-demo --prototype --yes

Esto crea el directorio secure-agent-demo, que contiene el código, las dependencias y los archivos de prueba de tu agente básico.

4. Agrega los extras de ADK requeridos

Agrega los dos extras que faltan en el pyproject.toml generado: mcp para el conjunto de herramientas de GitHub y agent-identity para Auth Manager, que se usará más adelante en el lab. Abre secure-agent-demo/pyproject.toml y reemplaza todo el

google-adk

línea de dependencia por lo siguiente:

"google-adk[agent-identity,gcp,mcp,otel-gcp]>=2.5.0,<3.0.0",

Luego, instala lo siguiente:

cd secure-agent-demo
agents-cli install

3. Compila y prueba el agente

1. Crea el agente

Dentro de tu proyecto, reemplaza el código en secure-agent-demo/app/agent.py por lo siguiente:

# app/agent.py

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import github_toolset

import os
import google.auth

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

INSTRUCTION = """You are the DevOps Assistant. You help developers list and triage their GitHub issues and pull requests.
Your capabilities: You have a GitHub MCP toolset that you can use to perform actions that the user requests.

Rules:
- NEVER write, update, or delete. You are only allowed read access.
- Act on behalf of the signed-in user.
- If a tool returns an authentication or authorization error, guide the user to sign in.
- NEVER fabricate information. Only report real issues returned by tools.
"""

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=INSTRUCTION,
    tools=[github_toolset()],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Este archivo define tres componentes clave del agente:

  • Instrucción del sistema (INSTRUCTION): Establece la personalidad, limita el alcance del asistente a la clasificación de GitHub y aplica reglas de seguridad estrictas (como el acceso de solo lectura y la orientación a los usuarios para que se autentiquen si se producen errores).
  • Configuración del agente (root_agent): Crea una instancia de un Agent del ADK con el modelo gemini-3.8-flash, configura la lógica de reintentos HTTP y equipa al agente con el conjunto de herramientas de GitHub.
  • App Wrapper (app): Encapsula el agente raíz en un contenedor de ADK App, lo que permite implementarlo en Agent Runtime.

2. Agrega la herramienta de MCP de GitHub

El agente se conecta a GitHub con el Protocolo de contexto del modelo (MCP). Crea un archivo nuevo en secure-agent-demo/app/tools.py para registrar los parámetros de conexión de la puerta de enlace de MCP. Copia y pega el siguiente código:

# app/tools.py

from __future__ import annotations
import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GITHUB_MCP_URL = "https://api.githubcopilot.com/mcp/"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")

def github_toolset() -> McpToolset:
    """Returns the McpToolset connecting to the public GitHub Copilot MCP gateway."""
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=GITHUB_MCP_URL,
            headers={
                "Authorization": f"Bearer {GITHUB_TOKEN}",
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        )
    )

Esta función crea una herramienta que llama al servidor de MCP de GitHub:

  • Conjunto de herramientas de MCP (McpToolset): Descubre y registra de forma dinámica las funciones de GitHub como herramientas de agente que se pueden llamar.
  • Parámetros de conexión (StreamableHTTPConnectionParams): Dirige el conjunto de herramientas a la puerta de enlace de MCP pública de GitHub.
  • Encabezados de autorización: Inserta el GITHUB_TOKEN como un token del portador y aplica el modo de solo lectura (X-MCP-Readonly: true) directamente en la capa de transporte.

3. Prueba de forma local con un PAT (token de acceso personal) de GitHub

Para ejecutar el agente de forma local con credenciales estáticas, haz lo siguiente:

  1. Crea un token de acceso personal detallado en la página Tokens de acceso personal de GitHub:
    • Haz clic en Generate new token y asígnale un nombre.
    • En Repository access, selecciona All repositories (o selecciona los repositorios específicos con los que quieras realizar la prueba).
    • En Permissions > Repositories, haz clic en +Add permissions y selecciona Contents, Issues y solicitudes de extracción para Read-only (Metadata se establece automáticamente en Read-only).
    • Haz clic en Generar token y copia el valor del token generado. (Como alternativa, si usas un token de acceso personal [clásico], selecciona el permiso repo).
  2. Establécela en tu entorno:
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. Navega a la carpeta secure-agent-demo (si aún no estás en ella) y, luego, inicia la zona de pruebas local:
    cd secure-agent-demo
    agents-cli playground
    
  4. Abre la interfaz de la zona de pruebas y selecciona la carpeta app en el menú desplegable. En el cuadro de chat, prueba una instrucción específica, como "Get the last 2 GitHub issues reported against my name" o "List my 3 most recently updated repositories", y verifica que el agente llame al conjunto de herramientas de MCP de GitHub y devuelva tus datos de GitHub. Para probar si el agente realmente está usando tu PAT para realizar acciones en tu nombre, intenta preguntarle sobre tus repositorios o contribuciones privados.

4. Configura Auth Manager

Si bien codificar credenciales estáticas (como un PAT) es conveniente para la creación de prototipos, expone las aplicaciones de producción a la filtración de credenciales, al tiempo de inactividad por actualización manual de tokens y a la falta de controles de acceso nativos de la nube.

Para resolverlo, Google Cloud proporciona el administrador de autenticación de Agent Identity. El administrador de autenticación de Agent Identity es una bóveda de credenciales diseñada para ayudar a proteger las credenciales. Permite que los agentes se autentiquen con una clave de API o un ID y un secreto de cliente de OAuth, o en nombre de un usuario a través de la delegación de OAuth con tokens de acceso de usuario final.

En Auth Manager, configuras los proveedores de autenticación que definen el tipo de autenticación y las credenciales para aplicaciones de terceros específicas. Los proveedores de autenticación son regionales, y la región debe coincidir con la región en la que implementas el agente. El flujo de trabajo de extremo a extremo de Auth Manager funciona de la siguiente manera:

Flujo de trabajo de Auth Manager

  1. Intercepción dinámica del consentimiento: Cuando el agente intenta ejecutar una herramienta en nombre de un usuario, el ADK verifica si existe una credencial válida en el Administrador de autenticación. Si no existe ninguna, Auth Manager devuelve una URL de autorización para iniciar un flujo de consentimiento de OAuth de 3 partes (3LO).
  2. Almacenamiento seguro en Vault: Una vez que el usuario final autoriza la aplicación, Auth Manager intercepta automáticamente la devolución de llamada de OAuth y almacena los tokens de acceso y los tokens de actualización del usuario resultantes en una bóveda de credenciales segura administrada por Google.
  3. Ciclo de vida de tokens automatizado: Auth Manager administra por completo el vencimiento y la rotación de tokens en segundo plano, lo que elimina la necesidad de una lógica de actualización manual de tokens o de tiempo de inactividad.
  4. Ejecución de herramientas sin secretos: Para las acciones posteriores, el agente (que se autentica a través de su identidad de agente de SPIFFE) solicita de forma dinámica el token de acceso delegado del usuario al administrador de autenticación en el entorno de ejecución, lo que mantiene el código del cliente y del agente completamente libre de secretos.

Paso A: Configura GitHub como proveedor de autenticación

Ejecuta el siguiente comando de gcloud para crear un proveedor de autenticación de GitHub en tu proyecto de Google Cloud. Proporcionarás el ID de cliente y el secreto más adelante: GitHub no los emitirá hasta que conozca la URL de devolución de llamada de este proveedor.

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-authorization-url="https://github.com/login/oauth/authorize" \
    --three-legged-oauth-token-url="https://github.com/login/oauth/access_token"

Describe el proveedor para recuperar la URL de redireccionamiento de OAuth generada:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1"

El campo es redirectUrl, anidado en authProviderTypeParams.threeLeggedOauth. Para leerlo directamente, haz lo siguiente:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_PROJECT_ID" --location="us-central1" \
    --format="value(authProviderTypeParams.threeLeggedOauth.redirectUrl)"

Se verá de esta forma https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Paso B: Registra la app de OAuth en GitHub

  1. Navega a la página de configuración para desarrolladores de GitHub, selecciona OAuth Apps en la barra lateral izquierda y haz clic en New OAuth App (o Register a new application si no creaste una antes).
  2. Completa los campos del formulario de la aplicación de OAuth:
    • Nombre de la aplicación: Ingresa un nombre para tu aplicación (por ejemplo, secure-agent-demo).
    • URL de la página principal: Ingresa la URL de tu aplicación de frontend (http://localhost:8501 para la creación de prototipos locales; puedes actualizarla a tu URL implementada en producción).
    • Descripción de la aplicación: Opcional (puedes dejar este campo en blanco).
    • URL de devolución de llamada de autorización (URI de redireccionamiento): Pega el redirectUrl que recuperaste en el paso A.
    • Habilitar el flujo de dispositivos: Deja esta opción sin marcar.
  3. Haz clic en Registrar aplicación.
  4. En la página de la aplicación resultante, copia el ID de cliente, haz clic en Generar un nuevo secreto del cliente y copia el secreto del cliente generado. Guarda ambos valores, ya que los usarás como YOUR_GITHUB_CLIENT_ID y YOUR_GITHUB_CLIENT_SECRET en el siguiente paso.

Paso C: Agrega las credenciales de GitHub al proveedor de autenticación

Reemplaza YOUR_PROJECT_ID, YOUR_GITHUB_CLIENT_ID y YOUR_GITHUB_CLIENT_SECRET por tus valores y ejecuta este comando:

gcloud agent-identity auth-providers update github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --three-legged-oauth-client-id="YOUR_GITHUB_CLIENT_ID" \
    --three-legged-oauth-client-secret="YOUR_GITHUB_CLIENT_SECRET"

El comando devuelve el proveedor con clientId visible; el secreto no se devuelve.

👉 Con este paso completado, tu Administrador de autenticación de Google Cloud ahora está completamente configurado con las credenciales de tu aplicación de OAuth de GitHub, lo que configura Google Cloud para que actúe como la bóveda segura que maneja los ciclos de vida de los tokens y el consentimiento.

5. Cambia el token de PAT a Auth Manager

Ahora que el administrador de autenticación está completamente configurado, el siguiente paso es actualizar el código de la herramienta del agente. Reemplaza el contenido de secure-agent-demo/app/tools.py por el siguiente código.

👉 Reemplaza el ID del proyecto y la ubicación en la variable OAUTH_PROVIDER_NAME que aparece a continuación.

# app/tools.py

from __future__ import annotations
import os
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# 1. Register the GCP Auth Provider in the global Credential Manager
CredentialManager.register_auth_provider(GcpAuthProvider())

# 2. Replace YOUR_PROJECT_ID with your project ID.
OAUTH_PROVIDER_NAME = "projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider"

# 3. The frontend callback URL where the user is redirected after authorizing GitHub. Resolved from the environment variable.
OAUTH_CONTINUE_URI = os.environ.get(
    "OAUTH_CONTINUE_URI", 
    "http://localhost:8501/validateUserId"
)

def github_toolset() -> McpToolset:
    """Returns the McpToolset using 3LO credentials retrieved via GCP Auth Manager."""
    auth_scheme = GcpAuthProviderScheme(
        name=OAUTH_PROVIDER_NAME,
        # Required to read private repositories. Auth Manager currently supports a
        # single scope for GitHub.
        scopes=["repo"],
        continue_uri=OAUTH_CONTINUE_URI,
    )
    return McpToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://api.githubcopilot.com/mcp/",
            headers={
                "X-MCP-Toolsets": "all",
                "X-MCP-Readonly": "true",
            },
        ),
        auth_scheme=auth_scheme,
    )

Comprende el código de la herramienta

El cambio clave es auth_scheme. Adjuntarlo al conjunto de herramientas significa que, cada vez que el agente llama a GitHub, el ADK primero le pide al administrador de autenticación el token de ese usuario y, si aún no hay uno, le solicita al usuario que acceda en lugar de fallar. El GITHUB_TOKEN codificado desaparece por completo.

6. Implementa el agente en Agent Runtime

Ahora que actualizamos la herramienta de MCP de GitHub para usar Auth Manager, el siguiente paso es implementar el agente en Agent Runtime. Si se implementa con la identidad del agente habilitada, se aprovisiona un ID de SPIFFE único para el agente.

Inicializa la configuración de implementación del proyecto. Asegúrate de que la terminal esté en el directorio raíz del proyecto secure-agent-demo y, luego, ejecuta lo siguiente:

agents-cli scaffold enhance . --deployment-target agent_runtime --prototype --yes

Este comando inspecciona la estructura de tu proyecto para verificar la compatibilidad con ADK, prepara las configuraciones de empaquetado de contenedores subyacentes y genera un archivo agents-cli-manifest.yaml en la raíz de tu proyecto prepropagado con la configuración de implementación predeterminada.

👉 Abre el archivo agents-cli-manifest.yaml recién creado y verifica o actualiza el campo region a us-central1 para asegurarte de que tu agente se implemente en la misma región que tu proveedor de autenticación:

region: "us-central1"

Implementa el agente con una identidad de agente

Implementa con adk deploy agent_engine. Esto aprovisiona al agente con su propia identidad de agente, una identidad criptográfica única respaldada por SPIFFE que pertenece a esta implementación, que el agente usa para autenticarse en Auth Manager y otros servicios de Google Cloud.

👉 Desde el directorio secure-agent-demo, reemplaza YOUR_PROJECT_ID y ejecuta estos comandos:

# Write a config file inside the `app/` folder instructing Agent Runtime to provision a SPIFFE-backed `AGENT_IDENTITY` for this deployment.
echo '{ "identity_type": "AGENT_IDENTITY" }' > app/.agent_engine_config.json

# Generate the dependency list the build will install
uv export --no-emit-workspace --no-hashes --format requirements.txt \
    --output-file app/requirements.txt

uv run adk deploy agent_engine app \
    --project="YOUR_PROJECT_ID" \
    --region="us-central1"

La implementación tarda unos minutos en compilar y subir el contenedor. Una vez que finaliza, la CLI imprime el nombre del recurso implementado. Toma nota del valor reasoningEngines/ENGINE_ID, ya que lo necesitas para autorizar a tu agente y dirigir el cliente de la IU hacia él.

Autoriza la identidad del agente

Ahora que tu agente se ejecuta en la nube, necesita permiso para acceder a las credenciales almacenadas en Auth Manager. De forma predeterminada, la identidad de SPIFFE del agente no tiene acceso a los recursos de nube externos.

Ejecuta el siguiente comando de gcloud para otorgar el rol roles/agentidentity.user a la identidad de tu agente en el recurso del proveedor de autenticación. Esto otorga a tu agente los permisos exactos que necesita para solicitar tokens de usuario de Vault, y nada más.

# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
  --format="value(projectNumber)"

Luego, vincula la política de IAM en el proveedor de autenticación (reemplaza YOUR_PROJECT_ID y la principal --member):

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-YOUR_ORG_ID.system.id.goog/resources/aiplatform/projects/YOUR_PROJECT_NUMBER/locations/us-central1/reasoningEngines/YOUR_ENGINE_ID"

👉 También puedes obtener el valor completo de --member="principal://..." para tu agente implementado desde la consola de Google Cloud: Navega a la consola de Agent Runtime, selecciona tu agente implementado, navega a la pestaña Identidad y copia la cadena principal://... completa directamente.

Ahora, otorga a tu propia cuenta el mismo rol en el proveedor. El cliente de IU que ejecutas en el siguiente paso llama a la API de finalización de credenciales con tus credenciales predeterminadas de la aplicación, por lo que, sin esto, el flujo de consentimiento falla con un error 403 en agentidentity.authProviders.retrieveCredentials:

gcloud agent-identity auth-providers add-iam-policy-binding github-oauth-provider \
    --project="YOUR_PROJECT_ID" \
    --location="us-central1" \
    --role="roles/agentidentity.user" \
    --member="user:YOUR_EMAIL_ADDRESS"

7. Información sobre el flujo de consentimiento de 3LO

Ahora que el agente se implementó en Agent Runtime con una identidad de agente segura, el siguiente paso es proporcionar una interfaz de frontend personalizada para que los usuarios chateen con él. Y lo que es más importante, Google Cloud Auth Manager requiere un controlador de devolución de llamada de la aplicación cliente para completar el bucle de autenticación.

Si bien Google Cloud Auth Manager administra de forma segura las credenciales de los usuarios dentro de una bóveda, no puede finalizar el intercambio de tokens de OAuth por sí solo. El protocolo de enlace de 3LO se basa en la aplicación cliente para cerrar la brecha:

  1. Cuando un usuario autoriza la app de GitHub, GitHub lo redirecciona de vuelta al redirectUrl del proveedor de autenticación de Agent Identity .
  2. Luego, Auth Manager redirecciona la ventana emergente del navegador del usuario a una URL de devolución de llamada del cliente (continue_uri).
  3. Es responsabilidad de la aplicación cliente interceptar este redireccionamiento, leer el nonce de las cookies del navegador y llamar al extremo credentials:finalize de Google Cloud para completar el protocolo de enlace.
  4. Una vez que el cliente finaliza el intercambio, Google Cloud guarda el token de forma segura en la bóveda del proveedor de autenticación, lo que permite que el agente llame a la herramienta de GitHub.

Sin este cliente personalizado que aloja el extremo de devolución de llamada, el protocolo de enlace permanece incompleto y la bóveda no puede almacenar las credenciales.

El flujo interactivo de OAuth 3LO abarca varias capas. Este es el ciclo de vida de ejecución completo de una solicitud de herramienta. Desglosaremos esto en la explicación que aparece a continuación y en el siguiente paso.

👉 Haz clic en la imagen para agrandarla.

Flujo de secuencia de OAuth de 3 segmentos

Responsabilidades principales del cliente en el acuerdo

  • Transmitir el desafío de consentimiento (pasos 5 y 6): El agente emite un adk_request_credential que contiene la URL de consentimiento y un nonce de un solo uso. El cliente abre la ventana emergente y almacena el nonce como una cookie.
  • Aloja la devolución de llamada de redireccionamiento (pasos 10 y 11): /validateUserId, donde el administrador de autenticación envía la ventana emergente después del consentimiento.
  • Finaliza el token (pasos 12 a 14): Combina el estado de validación del redireccionamiento con el nonce almacenado en caché y llama a credentials:finalize, que almacena el token en la bóveda.

Cómo compilar tu propio cliente

No es necesario que escribas este cliente para el lab; en el siguiente paso, se ejecuta uno compilado previamente. Cuando implementes esto en tu propia aplicación, estas son las dos referencias con las que debes trabajar:

8. Ejecuta el cliente de IU de forma local

Como se indica en el diagrama de secuencia del flujo de consentimiento de 3LO, el Administrador de autenticación redirecciona la ventana del navegador a un extremo de devolución de llamada del cliente. El cliente de ejemplo en el repositorio adk-python aloja ese extremo en /validateUserId. Descárgala y ejecútala de forma local con los siguientes pasos.

Descarga los archivos del cliente

El directorio contributing/samples/integrations/gcp_auth/client en adk-python contiene tres recursos clave:

  • main.py: Es el backend de FastAPI que se conecta a tu Agent Engine implementado y aloja el extremo de devolución de llamada /validateUserId para finalizar los tokens de OAuth.
  • static/: Son los archivos HTML y JavaScript para la IU de chat del navegador.
  • requirements.txt: Son los paquetes de Python necesarios para ejecutar el servidor cliente.

Como adk-python es un repositorio grande, usa la función de confirmación de compra dispersa de Git para descargar solo la carpeta contributing/samples/integrations/gcp_auth/client:

  1. Primero, sube un directorio fuera de secure-agent-demo para clonar el cliente en una carpeta hermana:
    cd ..
    
  2. Ejecuta los siguientes comandos para clonar los metadatos del repositorio sin descargar todos los archivos (--no-checkout), restringir la ruta de acceso de confirmación a contributing/samples/integrations/gcp_auth/client y confirmar solo esa carpeta:
    git clone --filter=blob:none --no-checkout https://github.com/google/adk-python.git
    cd adk-python
    git sparse-checkout init --cone
    git sparse-checkout set contributing/samples/integrations/gcp_auth/client
    git checkout
    

Ejecuta el cliente

  1. Desde el directorio adk-python al que acabas de ingresar, navega a la carpeta client:
    cd contributing/samples/integrations/gcp_auth/client
    
  2. Crea y activa un entorno virtual de Python y, luego, instala las dependencias del cliente desde requirements.txt:
    uv venv --python 3.13 .venv
    source .venv/bin/activate
    uv pip install --python .venv/bin/python -r requirements.txt
    
  3. Configura las variables de entorno que apuntan al cliente en tu proyecto de Google Cloud, la región (us-central1) y el ID de Agent Engine implementado (YOUR_ENGINE_ID). Luego, inicia el servidor local de FastAPI en el puerto 8501:
    export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=us-central1
    export AGENT_ID=YOUR_ENGINE_ID
    
    .venv/bin/uvicorn main:app --port 8501
    
  4. Verifica que el servidor se haya iniciado correctamente y que esté escuchando en http://localhost:8501.

9. Prueba el flujo de OAuth

Ahora que se implementaron todos los servicios, se configuraron las vinculaciones de IAM y se establecieron las variables de entorno, todo está listo para probar el flujo seguro de autorización delegada por el usuario de extremo a extremo.

Paso A: Iniciar la ejecución de la herramienta

  1. Abre una pestaña del navegador y navega a la URL del cliente: http://localhost:8501.
  2. En el panel izquierdo, en Configuration Settings, establece Agent Type en Remote Agent (Vertex AI) (o Remote Agent Engine).
  3. Ingresa el ID del proyecto y la ubicación (us-central1) de Google Cloud y, luego, haz clic en Cargar agentes remotos. Esto carga los agentes implementados en tu proyecto.
  4. Selecciona tu agente de app implementado en el menú desplegable Seleccionar motor y haz clic en Guardar y aplicar configuración.
  5. En el cuadro de chat, escribe una consulta segmentada (como recuperar tus problemas o repositorios recientes):
    Get the last 2 GitHub issues reported against my name
    
    (O prueba con "List my 3 most recently updated repositories") y presiona Intro.
  6. Observa la IU del chat: Como el agente aún no tiene credenciales para tu sesión de usuario, recibe un desafío de autenticación y muestra la tarjeta Se requiere autenticación en el hilo de conversación.
  1. Se abrirá una ventana emergente independiente del navegador, que te redireccionará a través del Administrador de autenticación de Google Cloud a la página de autorización de OAuth de GitHub.
  2. Revisa los permisos solicitados y haz clic en Autorizar.
  3. GitHub te redireccionará a Google Cloud, que redireccionará la ventana emergente a tu URL de devolución de llamada de localhost /validateUserId.
  4. El servicio de devolución de llamada procesa y finaliza el protocolo de enlace de credenciales.

Paso C: Reanuda

  1. Una vez que se cierra la ventana emergente, la pestaña de chat principal detecta automáticamente el cierre.
  2. El frontend envía una carga útil de reanudación al agente.
  3. El agente recupera de forma segura el token recién intercambiado de Google Cloud Auth Manager, llama a las herramientas de MCP de GitHub en tu nombre y transmite tus datos de GitHub directamente a la ventana de chat, datos a los que el agente no podría haber accedido por sí solo.

Paso D: Inspecciona los registros de Cloud

Para verificar que el intercambio y la finalización del token se hayan procesado de forma segura, haz lo siguiente:

  1. Ve al Explorador de registros de la consola de Google Cloud.
  2. Busca los registros del servidor que confirman la extracción del nonce y la validación correcta:
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
    INFO:secure-agent-client:Successfully finalized auth provider credentials.
    
  3. Inspecciona los registros de Agent Runtime: Como alternativa, puedes ver los registros de ejecución directamente en la consola de Agent Platform:
    • Navega a la consola de Agent Runtime.
    • Haz clic en el agente implementado en la lista.
    • Cambia a la pestaña Playground. Esto mostrará los registros del agente en vivo en el panel inferior, lo que te permitirá ver el bucle de razonamiento del agente, los detalles de la ejecución de la herramienta y el ciclo de vida de la recuperación de tokens en tiempo real.

10. Limpieza

Para evitar que se generen cargos continuos en Google Cloud, limpia los recursos implementados:

# Follow the instructions here to delete the deployed Agent Runtime resource
# https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/manage-deployed-agents#console_3

# Delete the auth provider
gcloud agent-identity auth-providers delete github-oauth-provider \
    --project=YOUR_PROJECT_ID --location=us-central1

# Note: deleted providers sit in soft-delete for 30 days, and the name is not
# reusable until roughly a day after that. Pick a fresh name if you repeat this lab.

# Optionally, you could also delete your Google Cloud Project
gcloud projects delete YOUR_PROJECT_ID

# Optionally, delete the GitHub PAT Token and the OAuth app: 
# https://github.com/settings/personal-access-tokens

Cómo limpiar archivos locales

De manera opcional, para limpiar por completo tu entorno local, haz lo siguiente:

  1. Detén el servidor uvicorn local presionando Ctrl + C en la terminal en la que se está ejecutando.
  2. Quita los directorios del proyecto que se crearon durante este lab:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. ¡Felicitaciones!

Creaste y protegiste correctamente un agente que actúa en nombre del usuario que accedió.

Qué aprendió:

  • Identidad del sistema del agente: Cómo opera el agente con su propia identidad de cuenta para interactuar de forma segura con la infraestructura de GCP, administrar los registros de telemetría y llamar a las APIs de finalización de credenciales.
  • Identidad delegada del usuario: Es la forma en que el agente solicita autorización para actuar en nombre del usuario en plataformas externas (como GitHub) activando un flujo de consentimiento de OAuth de 3 etapas (3LO).
  • Integración segura de herramientas: Cómo conectar agentes del ADK a servidores del Protocolo de contexto del modelo (MCP) con Google Cloud Auth Manager para recuperar tokens de usuario de forma dinámica en lugar de usar secretos codificados de forma rígida.
  • Configuración de la política de IAM: Cómo configurar vinculaciones de permisos detalladas para autorizar tanto la identidad de Agent Runtime como tu propia cuenta en el proveedor de autenticación.

Lecturas adicionales