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

1. Introducción

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

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

Específicamente, aprenderás a diseñar una arquitectura de doble identidad en la que se cumplan las siguientes condiciones:

1. El agente actúa en su propio nombre (identidad del agente): Con una identidad del agente respaldada por SPIFFE, el agente invoca el Administrador de autorización, 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 segmentos (3LO) para consultar herramientas de forma segura con las credenciales del usuario.

Para lograrlo, aprenderás a hacer lo siguiente:

1. Crea 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 al flujo de OAuth de 3 segmentos (3LO) con Google Cloud Auth Manager.
3. Implementa el agente de forma segura en Agent Runtime y aprovisiona Agent Identity.
4. Configura roles de IAM para proporcionar acceso de identidad del agente a la bóveda de tokens en nombre del usuario.
5. Comprender el flujo de 3LO de extremo a extremo para el Administrador de autorización 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 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 externo que admita OAuth 2.0 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 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 y configurar las credenciales predeterminadas de la aplicación (ADC):

gcloud auth login
gcloud auth application-default login

2. Habilita los servicios de Google Cloud obligatorios

Habilita 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 para confirmar que las APIs están activas.

3. Instala la CLI de Agents y configura el proyecto

agents-cli es la herramienta de línea de comandos que se usa para crear la estructura, administrar, probar y, luego, 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).

Genera la estructura inicial del proyecto. Comenzarás con un prototipo local y lo mejorarás más adelante para la implementación 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 básicos del agente.

4. Agrega los elementos adicionales del ADK necesarios

El pyproject.toml generado envía google-adk[gcp,otel-gcp], al que le faltan dos elementos adicionales que necesita este agente: mcp para el conjunto de herramientas de GitHub y agent-identity para Auth Manager más adelante en el lab. Abre secure-agent-demo/pyproject.toml y cambia la línea google-adk a 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. Crea y prueba el agente

1. Crea el agente

Dentro de tu proyecto, reemplaza el código en el archivo 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 el arquetipo, limita el asistente a la clasificación de GitHub y aplica reglas de seguridad estrictas (como acceso de solo lectura y guía 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.
• Wrapper de la app (app): Encapsula el agente raíz en un contenedor App del ADK, lo que permite implementarlo en Agent Runtime.

2. Agrega la herramienta de MCP de GitHub

El agente se conecta a GitHub a través del Protocolo de contexto del modelo (MCP). Crea un archivo nuevo llamado tools.py en la carpeta app/ 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 capacidades de GitHub como herramientas de agentes invocables.
• Parámetros de conexión (StreamableHTTPConnectionParams): Dirige el conjunto de herramientas a la puerta de enlace pública de MCP de GitHub.
• Encabezados de autorización: Inserta el GITHUB_TOKEN como un token de portador y aplica el modo de solo lectura (X-MCP-Readonly: true) directamente en la capa de transporte.

3. Prueba localmente 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 de GitHub. Otorga acceso de lectura a tus repositorios; de lo contrario, el agente solo podrá ver datos públicos y la instrucción a continuación no devolverá nada.
2. Establécelo en tu entorno:

   export GITHUB_TOKEN="your_github_pat_here"
   

3. Navega a la carpeta secure-agent-demo. Ejecución:

   cd secure-agent-demo
   agents-cli playground
   

4. Abre la interfaz del Playground y selecciona la carpeta "app" en el menú desplegable. En el cuadro de chat, escribe "Fetch my contributions across my private repositories over the last 6 months" y verifica que el agente llame a la herramienta de GitHub y muestre datos de tus repositorios privados.

4. Configura Auth Manager

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

Para resolver este problema, Google Cloud proporciona Agent Identity Auth Manager. El administrador de autenticación de identidad del agente es una bóveda de credenciales diseñada para ayudar a protegerlas. 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 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 del Administrador de autorización funciona de la siguiente manera:

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

Importante: A lo largo de este codelab, verás variables de marcador de posición en mayúsculas (como YOUR_PROJECT_ID, YOUR_PROJECT_NUMBER, YOUR_ORG_ID y YOUR_ENGINE_ID). Asegúrate de reemplazarlas por los valores de tu propio proyecto y recursos de Google Cloud cuando ejecutes los comandos.

Paso A: Configura GitHub como proveedor de autenticación

Ejecuta el siguiente comando gcloud para crear un proveedor de autenticación de GitHub en tu proyecto de Google Cloud. Proporcionarás el ID y el secreto del cliente 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="${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="${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="${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 y haz clic en Registrar una nueva app de OAuth.
2. En URL de la página principal, ingresa la URL de tu aplicación de frontend (p.ej., http://localhost:8501 para la creación de prototipos locales). Más adelante, puedes cambiarla a la URL implementada en producción.
3. Establece el URI de redireccionamiento en el redirectUrl recuperado en el paso anterior.
4. Haz clic en Registrar aplicación, luego en Generar un nuevo secreto del cliente y guarda el ID de cliente y el secreto del cliente.

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

Reemplaza tu ID del proyecto, ID de cliente y secreto del cliente, 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 muestra el proveedor con clientId visible, pero no muestra el secreto.

👉 Una vez que completes este paso, tu Administrador de autenticación de Google Cloud estará completamente configurado con las credenciales de tu aplicación de OAuth de GitHub, lo que permitirá que Google Cloud actúe como la bóveda segura que controla el consentimiento y los ciclos de vida de los tokens.

5. Cambia el token de PAT a Auth Manager

Ahora que el Administrador de autorización está completamente configurado, el siguiente paso es actualizar el código de la herramienta del agente. Reemplaza tu app/tools.py por el siguiente código.

👉 Reemplaza el ID del proyecto y la ubicación en la variable OAUTH_PROVIDER_NAME que se muestra 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,
    )

Cómo comprender el código de la herramienta

El cambio clave es auth_scheme. Adjuntarlo al conjunto de herramientas significa que, cada vez que el agente llame a GitHub, el ADK primero le pedirá al Administrador de autorización el token de ese usuario y, si aún no hay uno, le pedirá al usuario que acceda en lugar de fallar. El GITHUB_TOKEN codificado ya no existe.

6. Implementa el agente en Agent Runtime

Ahora que actualizamos la herramienta de MCP de GitHub para que use el Administrador de autorización, el siguiente paso es implementar el agente en Agent Runtime. Implementarlo con la identidad del agente habilitada aprovisiona un ID de SPIFFE único para el agente.

Comencemos por inicializar la configuración de implementación del proyecto. Ejecuta en la terminal:

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

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

👉 Abre el archivo agents-cli-manifest.yaml que acabas de crear 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 del agente, una identidad criptográfica única respaldada por SPIFFE que pertenece a esta implementación y que el agente usa para autenticarse en Auth Manager y otros servicios de Google Cloud.

👉 Reemplaza YOUR_PROJECT_ID antes de ejecutar estos comandos:

# Request 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 finalice, la CLI imprimirá el nombre del recurso implementado. Toma nota del valor de reasoningEngines/ENGINE_ID, ya que lo necesitarás para autorizar tu agente y para dirigir el cliente de la IU hacia él.

Usa adk deploy agent_engine, no agents-cli deploy --agent-identity. Ambos se implementan correctamente, pero producen diferentes formas de recursos. agents-cli deploy compila un servidor de contenedores sin classMethods; el cliente de la IU que ejecutas más adelante llama a create_session() en el agente implementado y falla con 'AgentEngine' object has no attribute 'create_session'. adk deploy agent_engine produce la forma serializada de AdkApp, que expone los 13 métodos que necesita el cliente.

Dónde llega el usuario después de dar su consentimiento: Una vez que un usuario aprueba el acceso, su navegador se envía a la dirección en OAUTH_CONTINUE_URI, que proporciona tu propia aplicación cliente. En este lab, el cliente se ejecuta en tu máquina, por lo que el agente usa el valor predeterminado ya establecido en app/tools.py (http://localhost:8501/validateUserId) y no necesitas cambiar nada. Si más adelante alojas el cliente en otro lugar, actualiza ese valor predeterminado antes de la implementación.

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 SPIFFE del agente no tiene acceso a los recursos externos de la nube.

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

👉 Reemplaza YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER y YOUR_ENGINE_ID (el ID del motor se encuentra en el resultado de la implementación anterior).

Para obtener YOUR_ORG_ID, ejecuta el siguiente comando:

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

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"

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"

Esta segunda vinculación solo es necesaria para ejecutar el lab de forma local. Permite que el cliente de tu máquina finalice el consentimiento con tus propias credenciales. En producción, el cliente se ejecuta con su propia identidad, y solo se requiere la vinculación del agente anterior.

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. 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 del usuario 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 al redirectUrl del proveedor de autenticación de Agent Identity .
2. Luego, el Administrador de autenticación 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 handshake.
4. Una vez que el cliente finaliza el intercambio, Google Cloud guarda de forma segura el token 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, la confirmación de conexión permanece incompleta y la bóveda no puede almacenar las credenciales.

El flujo interactivo de OAuth 3LO abarca varias capas. A continuación, se muestra el ciclo de vida completo de ejecución de una solicitud de herramienta. Desglosaremos esto en la explicación a continuación y en el siguiente paso.

👉 Haz clic en la imagen para agrandarla.

Responsabilidades principales del cliente en el acuerdo

• Transmite 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 autorizació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 crear tu propio cliente

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

• Actualiza tu aplicación del cliente en la documentación de Auth Manager, que abarca el control del desafío de consentimiento y la llamada a credentials:finalize.
• El cliente de muestra ejecutable en el repositorio adk-python Lee main.py para obtener una implementación completa y funcional de las tres responsabilidades anteriores.

8. Ejecuta el cliente de IU de forma local

Como vimos en el diagrama de secuencia del Flujo de consentimiento de 3LO, el Administrador de autorización debe redireccionar la ventana emergente del navegador a un extremo de devolución de llamada del cliente. El cliente de ejemplo aloja ese extremo en /validateUserId. Ejecutémoslo de forma local.

Copia archivos del cliente en Local

Navega a la carpeta gcp_auth/client en el repositorio de GitHub de adk-python. Esta carpeta contiene los recursos necesarios para compilar nuestro contenedor de cliente de chat.

👉 Copia todos los archivos de gcp_auth/client en tu entorno local:

• main.py: Es el script de la aplicación FastAPI que contiene la devolución de llamada de finalización del token (/validateUserId) que analizamos en la sección anterior.
• static/: Contiene las páginas HTML.

Como alternativa, también puedes realizar una extracción dispersa de la 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. Navega a la carpeta client que acabas de copiar:

   cd adk-python/contributing/samples/integrations/gcp_auth/client
   

2. Crea un entorno virtual y, luego, instala las dependencias del cliente. La carpeta incluye un requirements.txt y no un pyproject.toml, por lo que uv run uvicorn ... por sí solo falla con Failed to spawn: uvicorn:

   uv venv --python 3.13 .venv
   source .venv/bin/activate
   uv pip install --python .venv/bin/python -r requirements.txt
   

3. Dirige el cliente al agente que implementaste y, luego, inícialo 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 esté escuchando en http://localhost:8501.

Usa localhost, no 127.0.0.1. El redireccionamiento de OAuth requiere el nombre de host localhost; los dos no son intercambiables aquí, aunque se resuelvan en la misma dirección.

9. Prueba el flujo de OAuth

Ahora que todos los servicios están implementados, las vinculaciones de IAM están configuradas y las variables de entorno están establecidas, todo está listo para probar el flujo de autorización seguro de extremo a extremo delegado por el usuario.

Paso A: Inicia 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, establece el tipo de agente en Remote Agent Engine.
3. Escribe tu proyecto y ubicación de Google Cloud. Haz clic en Load Remote Agents: Deberían cargarse todos los agentes implementados en tu proyecto.
4. Selecciona el agente correcto en el menú desplegable y guarda la configuración.
5. En el cuadro de chat, escribe lo siguiente:

   Fetch my contributions across my private repositories over the last 6 months
   

   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.

Paso B: Completa el consentimiento de OAuth de 3 segmentos

1. Se abrirá una ventana emergente del navegador independiente 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 redireccionará a Google Cloud, que redireccionará la ventana emergente a tu URL de devolución de llamada localhost /validateUserId.
4. El servicio de devolución de llamada procesa y finaliza el protocolo de enlace de credenciales.

Paso C: Reanudar

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 del Administrador de autenticación de Google Cloud, llama a las herramientas de MCP de GitHub en tu nombre y transmite datos de tus repositorios privados 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 procesaron de forma segura, haz lo siguiente:

1. Ve al Explorador de registros de la consola de Google Cloud.
2. Ubica los registros del servidor que confirmen 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. Inspeccionar 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 que implementaste en la lista.
   • Cambia a la pestaña Playground para ver los registros del agente en vivo en el panel inferior, que te muestran el bucle de razonamiento del agente, los detalles de ejecución de la herramienta y el ciclo de vida de recuperación de tokens en tiempo real.

10. Limpieza

Para evitar que se apliquen 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

Liberar espacio en archivos locales

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

1. Presiona Ctrl + C en la terminal en la que se ejecuta para detener el servidor local de Uvicorn.
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: Es la forma en que el agente opera bajo 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 por el 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 segmentos (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 de forma dinámica tokens de usuario en lugar de usar secretos codificados.
• Configuración de la política de IAM: Cómo configurar vinculaciones de permisos detallados para autorizar la identidad de Agent Runtime y tu propia cuenta en el proveedor de autenticación

Lecturas adicionales

• Agent Identity Auth Manager para comprender la configuración y los alcances del flujo de autenticación
• Descripción general de Agent Runtime
• Documentación del ADK
• Protocolo de contexto del modelo