Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Créer un agent IA qui agit au nom de l'utilisateur avec le gestionnaire d'authentification et d'identité d'agent

1. Introduction

Un agent disposant de ses propres identifiants avec une autorisation étendue voit les données de tous les utilisateurs. Dans cet atelier de programmation, vous allez créer un agent qui appelle une API tierce avec les propres identifiants de l'utilisateur connecté. Il voit donc exactement ce que cette personne peut voir et rien de plus.

Vous allez le créer avec Google Agent Development Kit (ADK) et Gemini Enterprise.

Plus précisément, vous apprendrez à concevoir une architecture à double identité dans laquelle :

L'agent agit en son nom propre (identité de l'agent) : à l'aide d'une identité d'agent basée sur SPIFFE, l'agent appelle Auth Manager, stocke la télémétrie et appelle les API Google Cloud.
L'agent agit au nom de l'utilisateur (identité déléguée par l'utilisateur) : pour accéder à des ressources externes comme GitHub, l'agent déclenche un flux d'autorisation OAuth à trois étapes (3LO) afin d'interroger les outils de manière sécurisée à l'aide des identifiants de l'utilisateur.

Architecture à double identité

Pour ce faire, vous allez apprendre à :

Créez un agent ADK qui se connecte au serveur MCP (Model Context Protocol) de GitHub.
Mettez à jour l'outil de l'agent en passant d'un PAT (jeton d'accès personnel) GitHub statique à un flux OAuth à trois identifiants à l'aide de Google Cloud Auth Manager.
Déployez l'agent de manière sécurisée dans Agent Runtime et provisionnez l'identité de l'agent.
Configurez des rôles IAM pour fournir l'accès à l'identité de l'agent au coffre de jetons au nom de l'utilisateur.
Comprendre le flux 3LO de bout en bout pour le Gestionnaire d'authentification dans Google Cloud.

Prérequis

À vérifier avant de commencer :

Un projet Google Cloud pour lequel la facturation est activée.
Le Google Cloud SDK (gcloud CLI) est installé et authentifié pour votre projet sur votre ordinateur local. La version 586.0.0 ou ultérieure est requise : exécutez gcloud components update.
Python 3.10 à 3.13 installé en local.
Le gestionnaire de paquets uv est installé (pip install uv).
Un compte GitHub pour enregistrer une application OAuth et créer des jetons. Si vous n'avez pas de compte GitHub, vous pouvez utiliser n'importe quel serveur MCP tiers compatible avec OAuth 2.0 à trois identifiants.

2. Configuration du projet

1. S'authentifier sur Google Cloud

Authentifiez-vous auprès de Google Cloud depuis votre ligne de commande locale pour vous assurer que votre environnement dispose des autorisations nécessaires pour déployer Agent Runtime, provisionner Agent Identity et configurer Auth Manager au cours de cet atelier :

Exécutez les commandes suivantes pour vous connecter à votre compte Google Cloud et configurer les identifiants par défaut de l'application :

gcloud auth login
gcloud auth application-default login

2. Activer les services Google Cloud requis

Activez les API nécessaires dans votre projet Google Cloud pour exécuter cet atelier. Exécutez la commande suivante dans votre terminal :

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

L'exécution de cette commande peut prendre une minute. Une fois terminée, elle renvoie à l'invite de commande pour confirmer que les API sont actives.

3. Installer l'interface de ligne de commande des agents et configurer le projet

agents-cli est l'outil de ligne de commande utilisé pour créer, gérer, tester et déployer des agents ADK dans Gemini Enterprise. Installez-le en local :

uvx google-agents-cli setup

Vérifiez votre installation :

agents-cli --help

Le menu d'aide de la CLI doit s'afficher et lister les commandes disponibles (telles que deploy, run et status).

Générez la structure initiale du projet. Vous commencerez par un prototype local et l'améliorerez ultérieurement pour le déploiement Agent Runtime :

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

Cela crée le répertoire secure-agent-demo contenant le code de base de votre agent, les dépendances et les fichiers de test.

4. Ajouter les extras ADK requis

Le pyproject.toml généré est google-adk[gcp,otel-gcp], qui manque de deux extras dont cet agent a besoin : mcp pour l'ensemble d'outils GitHub et agent-identity pour Auth Manager plus loin dans l'atelier. Ouvrez secure-agent-demo/pyproject.toml et remplacez la ligne google-adk par :

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

Installez ensuite :

cd secure-agent-demo
agents-cli install

3. Créer et tester l'agent

1. Créer l'agent

Dans votre projet, remplacez le code du fichier agent.py par le code suivant :

# 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",
)

Ce fichier définit trois composants clés de l'agent :

Instruction système (INSTRUCTION) : définit la personnalité, limite l'assistant au triage GitHub et applique des règles de sécurité strictes (comme l'accès en lecture seule et l'invitation à s'authentifier en cas d'erreur).
Configuration de l'agent (root_agent) : instancie un ADK Agent à l'aide du modèle gemini-3.8-flash, configure la logique de nouvelle tentative HTTP et équipe l'agent de l'ensemble d'outils GitHub.
Wrapper d'application (app) : encapsule l'agent racine dans un conteneur App ADK, ce qui le rend déployable dans Agent Runtime.

2. Ajouter l'outil MCP GitHub

L'agent se connecte à GitHub via le protocole MCP (Model Context Protocol). Créez un fichier nommé tools.py dans le dossier app/ pour enregistrer les paramètres de connexion de la passerelle MCP. Copiez et collez le code suivant :

# 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",
            },
        )
    )

Cette fonction crée un outil qui appelle le serveur MCP de GitHub :

Ensemble d'outils MCP (McpToolset) : découvre et enregistre de manière dynamique les fonctionnalités GitHub en tant qu'outils d'agent appelables.
Paramètres de connexion (StreamableHTTPConnectionParams) : indique à l'ensemble d'outils la passerelle MCP publique de GitHub.
En-têtes d'autorisation : injecte GITHUB_TOKEN en tant que jeton Bearer et applique le mode lecture seule (X-MCP-Readonly: true) directement au niveau de la couche de transport.

3. Tester localement avec un jeton d'accès personnel GitHub

Pour exécuter l'agent en local avec des identifiants statiques :

Créez un jeton d'accès personnel GitHub. Accordez-lui un accès en lecture à vos dépôts. Sinon, l'agent ne pourra voir que les données publiques et la requête ci-dessous ne renverra rien.

Définissez-le dans votre environnement :

export GITHUB_TOKEN="your_github_pat_here"

Accédez au dossier secure-agent-demo : Exécutez la commande suivante :
```
cd secure-agent-demo
agents-cli playground
```
Ouvrez l'interface du bac à sable, puis sélectionnez le dossier "app" dans le menu déroulant. Dans la zone de chat, saisissez "Fetch my contributions across my private repositories over the last 6 months" et vérifiez que l'agent appelle l'outil GitHub et renvoie les données de vos dépôts privés.

4. Configurer Auth Manager

Bien que l'intégration en dur d'identifiants statiques (comme un PAT) soit pratique pour le prototypage, elle expose les applications de production à des fuites d'identifiants, à des temps d'arrêt pour l'actualisation manuelle des jetons et à un manque de contrôles d'accès cloud natifs.

Pour résoudre ce problème, Google Cloud fournit Agent Identity Auth Manager. Le gestionnaire d'authentification des identités d'agent est un coffre-fort d'identifiants conçu pour protéger les identifiants. Il permet aux agents de s'authentifier à l'aide d'une clé API ou d'un ID client et d'un code secret OAuth, ou pour le compte d'un utilisateur via la délégation OAuth à l'aide de jetons d'accès utilisateur final.

Dans le gestionnaire d'authentification, vous configurez des fournisseurs d'authentification qui définissent le type d'authentification et les identifiants pour des applications tierces spécifiques. Les fournisseurs d'authentification sont régionaux. La région doit correspondre à celle dans laquelle vous déployez l'agent. Le workflow Auth Manager de bout en bout fonctionne comme suit :

Workflow Auth Manager

Interception dynamique du consentement : lorsque l'agent tente d'exécuter un outil au nom d'un utilisateur, l'ADK recherche un identifiant valide existant dans Auth Manager. S'il n'en existe aucune, Auth Manager renvoie une URL d'autorisation pour lancer un flux de consentement OAuth à trois étapes.
Stockage sécurisé dans le coffre-fort : une fois que l'utilisateur final a autorisé l'application, Auth Manager intercepte automatiquement le rappel OAuth et stocke les jetons d'accès et d'actualisation de l'utilisateur dans un coffre-fort d'identifiants sécurisé géré par Google.
Cycle de vie automatisé des jetons : Auth Manager gère entièrement l'expiration et la rotation des jetons en arrière-plan, ce qui élimine le besoin d'une logique d'actualisation manuelle des jetons ou de temps d'arrêt.
Exécution d'outils sans code secret : pour les actions suivantes, l'agent (qui s'authentifie via son identité d'agent SPIFFE) demande dynamiquement le jeton d'accès délégué de l'utilisateur à Auth Manager lors de l'exécution, ce qui permet de garder le code client et le code de l'agent entièrement sans code secret.

Étape A : Configurer GitHub comme fournisseur d'authentification

Exécutez la commande gcloud suivante pour créer un fournisseur d'authentification GitHub dans votre projet Google Cloud. Vous fournirez l'ID client et le code secret ultérieurement : GitHub ne les émettra pas tant qu'il ne connaîtra pas l'URL de rappel de ce fournisseur.

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"

Décrivez le fournisseur pour récupérer l'URL de redirection OAuth générée :

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="${PROJECT_ID}" \
    --location="us-central1"

Le champ est redirectUrl, imbriqué sous authProviderTypeParams.threeLeggedOauth. Pour le lire directement :

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

Il se présente comme suit : https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Étape B : Enregistrez l'application OAuth dans GitHub.

Accédez à la page GitHub Developer Settings (Paramètres pour les développeurs GitHub), puis cliquez sur Register a new OAuth app (Enregistrer une application OAuth).
Pour l'URL de la page d'accueil, saisissez l'URL de votre application frontend (par exemple, http://localhost:8501 pour le prototypage local). Vous pourrez ensuite la remplacer par l'URL déployée en production.
Définissez l'URI de redirection sur redirectUrl récupéré à l'étape précédente.
Cliquez sur Register application (Enregistrer l'application), puis sur Generate a new client secret (Générer un code secret du client). Enregistrez l'ID client et le code secret du client.

Étape C : Ajoutez les identifiants GitHub au fournisseur d'authentification

Remplacez l'ID de votre projet, l'ID client et le code secret du client, puis exécutez cette commande :

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"

La commande renvoie le fournisseur avec clientId visible, mais pas le secret.

👉 Une fois cette étape terminée, votre gestionnaire d'authentification Google Cloud est entièrement configuré avec les identifiants de votre application GitHub OAuth, ce qui permet à Google Cloud d'agir en tant que coffre-fort sécurisé qui gère le consentement et les cycles de vie des jetons.

5. Passer du jeton PAT à Auth Manager

Maintenant que le gestionnaire d'authentification est entièrement configuré, l'étape suivante consiste à mettre à jour le code de l'outil de l'agent. Remplacez votre app/tools.py par le code suivant.

👉 Remplacez l'ID et l'emplacement du projet dans la variable OAUTH_PROVIDER_NAME ci-dessous.

# 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,
    )

Comprendre le code de l'outil

La principale modification est auth_scheme. En l'associant à l'ensemble d'outils, l'ADK demande d'abord le jeton de l'utilisateur au gestionnaire d'authentification chaque fois que l'agent appelle GitHub. S'il n'y en a pas encore, il invite l'utilisateur à se connecter au lieu d'échouer. Le GITHUB_TOKEN codé en dur a complètement disparu.

6. Déployer l'agent dans Agent Runtime

Maintenant que nous avons mis à jour l'outil GitHub MCP pour utiliser Auth Manager, l'étape suivante consiste à déployer l'agent sur Agent Runtime. Le déploiement avec l'identité de l'agent activée fournit un ID SPIFFE unique pour l'agent.

Commençons par initialiser la configuration du déploiement pour le projet. Exécutez la commande suivante dans le terminal :

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

Cette commande inspecte la structure de votre projet pour vérifier sa compatibilité avec l'ADK, prépare les configurations d'empaquetage du conteneur sous-jacent et génère un fichier agents-cli-manifest.yaml à la racine de votre projet, prérempli avec les paramètres de déploiement par défaut.

👉 Ouvrez le fichier agents-cli-manifest.yaml que vous venez de créer, puis vérifiez ou mettez à jour le champ region en le remplaçant par us-central1 pour vous assurer que votre agent est déployé dans la même région que votre fournisseur d'authentification :

region: "us-central1"

Déployer l'agent avec une identité d'agent

Déployez avec adk deploy agent_engine. Cela fournit à l'agent sa propre identité d'agent, à savoir une identité cryptographique unique basée sur SPIFFE appartenant à ce déploiement, que l'agent utilise pour s'authentifier auprès d'Auth Manager et d'autres services Google Cloud.

👉 Remplacez YOUR_PROJECT_ID avant d'exécuter ces commandes :

# 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"

Le déploiement prend quelques minutes pour créer et importer le conteneur. Une fois l'opération terminée, la CLI affiche le nom de la ressource déployée. Notez la valeur reasoningEngines/ENGINE_ID, car vous en aurez besoin pour autoriser votre agent et pointer le client de l'UI vers celui-ci.

Autoriser l'identité de l'agent

Maintenant que votre agent s'exécute dans le cloud, il a besoin d'une autorisation pour accéder aux identifiants stockés dans Auth Manager. Par défaut, l'identité SPIFFE de l'agent n'a pas accès aux ressources cloud externes.

Exécutez la commande gcloud suivante pour attribuer le rôle roles/agentidentity.user à l'identité de votre agent sur la ressource du fournisseur d'authentification. Cela accorde à votre agent les autorisations exactes dont il a besoin pour demander des jetons utilisateur au coffre-fort, et rien de plus.

👉 Remplacez YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER et YOUR_ENGINE_ID (l'ID du moteur se trouve dans le résultat du déploiement ci-dessus).

Pour obtenir YOUR_ORG_ID, exécutez la commande ci-dessous :

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"

Attribuez maintenant le même rôle à votre propre compte sur le fournisseur. Le client d'UI que vous exécuterez à l'étape suivante appelle l'API de finalisation des identifiants avec vos identifiants par défaut de l'application. Sans cela, le flux de consentement échoue avec un code 403 sur 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. Comprendre le parcours de consentement 3LO

Maintenant que l'agent est déployé sur Agent Runtime avec une identité d'agent sécurisée, l'étape suivante consiste à fournir une interface utilisateur personnalisée permettant aux utilisateurs de discuter avec lui. Plus important encore, Google Cloud Auth Manager nécessite un gestionnaire de rappel d'application cliente pour terminer la boucle d'authentification.

Bien que Google Cloud Auth Manager gère de manière sécurisée les identifiants utilisateur dans un coffre-fort, il ne peut pas finaliser l'échange de jetons OAuth à lui seul. La poignée de main 3LO repose sur l'application cliente pour combler le fossé :

Lorsqu'un utilisateur autorise l'application GitHub, GitHub le redirige vers redirectUrl du fournisseur d'authentification Agent Identity .
Le Gestionnaire d'authentification redirige ensuite le pop-up du navigateur de l'utilisateur vers une URL de rappel côté client (continue_uri).
Il incombe à l'application cliente d'intercepter cette redirection, de lire le nonce à partir des cookies du navigateur et d'appeler le point de terminaison credentials:finalize de Google Cloud pour terminer l'établissement de la liaison.
Une fois l'échange finalisé par le client, Google Cloud enregistre le jeton de manière sécurisée dans le coffre-fort du fournisseur d'authentification, ce qui permet à l'agent d'appeler l'outil GitHub.

Sans cet hébergement client personnalisé pour le point de terminaison de rappel, l'établissement de la liaison reste incomplet et le coffre-fort ne peut pas stocker les identifiants.

Le flux OAuth 3LO interactif s'étend sur plusieurs couches. Voici le cycle de vie complet de l'exécution d'une requête d'outil. Nous allons détailler cela dans l'explication ci-dessous et à l'étape suivante.

👉 Cliquez sur l'image pour l'agrandir.

Responsabilités principales du client dans le Handshake

Transmettez la demande de consentement (étapes 5 et 6) : l'agent émet un adk_request_credential contenant l'URL de consentement et un nonce à usage unique. Le client ouvre le pop-up et stocke le nonce sous forme de cookie.
Hébergez le rappel de redirection (étapes 10 et 11) : /validateUserId, où Auth Manager envoie le pop-up après consentement.
Finalisez le jeton (étapes 12 à 14) : combinez l'état de validation de la redirection avec le nonce mis en cache et appelez credentials:finalize, qui stocke le jeton dans le coffre.

Créer votre propre client

Vous n'avez pas besoin d'écrire ce client pour l'atelier. L'étape suivante exécute un client prédéfini. Lorsque vous implémenterez cela dans votre propre application, voici les deux références à partir desquelles travailler :

Mettez à jour votre application côté client dans la documentation Auth Manager, qui explique comment gérer la demande de consentement et appeler credentials:finalize.
L'exemple de client exécutable dans le dépôt adk-python. Consultez main.py pour obtenir une implémentation complète et fonctionnelle des trois responsabilités ci-dessus.

8. Exécuter le client d'UI en local

Comme nous l'avons vu dans le diagramme de séquence du flux de consentement 3LO, Auth Manager doit rediriger le pop-up du navigateur vers un point de terminaison de rappel côté client. L'exemple de client héberge ce point de terminaison à l'adresse /validateUserId. Exécutons-le en local.

Copier les fichiers client sur l'ordinateur local

Accédez au dossier gcp_auth/client dans le dépôt GitHub adk-python. Ce dossier contient les composants requis pour créer notre conteneur de client de chat.

👉 Copiez tous les fichiers sous gcp_auth/client dans votre environnement local :

main.py : script d'application FastAPI contenant le rappel de finalisation du jeton (/validateUserId) dont nous avons parlé dans la section précédente.
static/ : contient les pages HTML.

Vous pouvez également effectuer un checkout partiel du dossier :

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

Exécuter le client

Accédez au dossier client que vous venez de copier :

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

Créez un environnement virtuel et installez les dépendances du client. Le dossier contient un requirements.txt et aucun pyproject.toml. Par conséquent, uv run uvicorn ... seul échoue avec Failed to spawn: uvicorn :
```
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install --python .venv/bin/python -r requirements.txt
```

Pointez le client vers l'agent que vous avez déployé, puis démarrez-le sur le port 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

Vérifiez que le serveur a démarré correctement et qu'il est à l'écoute sur http://localhost:8501.

9. Tester le flux OAuth

Maintenant que tous les services sont déployés, que les liaisons IAM sont configurées et que les variables d'environnement sont définies, vous êtes prêt à tester le flux d'autorisation sécurisé de bout en bout délégué par l'utilisateur.

Étape A : Lancer l'exécution de l'outil

Ouvrez un onglet de navigateur et accédez à l'URL de votre client : http://localhost:8501.
Dans le volet de gauche, définissez le type d'agent sur Remote Agent Engine.
Saisissez votre projet et votre emplacement Google Cloud. Cliquez sur Load Remote Agents. Tous les agents déployés dans votre projet devraient se charger.
Sélectionnez l'agent approprié dans le menu déroulant, puis enregistrez les paramètres.

Dans la zone de discussion, saisissez :

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

et appuyez sur Entrée.

Observez l'interface utilisateur du chat : comme l'agent ne dispose pas encore d'identifiants pour votre session utilisateur, il reçoit une demande d'authentification et affiche la fiche "Authentification requise" dans le fil de conversation.

Une fenêtre pop-up de navigateur distincte s'ouvre, vous redirigeant via le gestionnaire d'authentification Google Cloud vers la page d'autorisation GitHub OAuth.
Consultez les autorisations demandées, puis cliquez sur Autoriser.
GitHub redirige l'utilisateur vers Google Cloud, qui redirige la fenêtre pop-up vers votre localhostURL de rappel/validateUserId.
Le service de rappel traite et finalise l'échange d'identifiants.

Étape C : Reprendre

Une fois la fenêtre pop-up fermée, l'onglet de chat parent détecte automatiquement la fermeture.
L'interface envoie une charge utile de reprise à l'agent.
L'agent récupère le jeton nouvellement échangé de manière sécurisée depuis Google Cloud Auth Manager, appelle les outils GitHub MCP en votre nom et diffuse les données de vos dépôts privés directement dans la fenêtre de chat (données auxquelles l'agent n'aurait pas pu accéder seul).

Étape D : Inspecter les journaux Cloud

Pour vérifier que l'échange et la finalisation du jeton ont été traités de manière sécurisée :

Accédez à l'explorateur de journaux de la console Google Cloud.

Recherchez les journaux du serveur confirmant l'extraction du nonce et la validation réussie :

INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.

Inspecter les journaux d'exécution de l'agent : vous pouvez également afficher les journaux d'exécution directement dans la console de la plate-forme d'agent :
- Accédez à la console Agent Runtime.
- Cliquez sur l'agent déployé dans la liste.
- Passez à l'onglet Playground. Les journaux de l'agent en direct s'affichent dans le volet inférieur, ce qui vous permet de voir en temps réel la boucle de raisonnement de l'agent, les détails de l'exécution de l'outil et le cycle de vie de la récupération des jetons.

10. Effectuer un nettoyage

Pour éviter que des frais ne soient facturés en continu sur Google Cloud, nettoyez les ressources déployées :

# 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

Libérer de l'espace sur les fichiers locaux

Si vous le souhaitez, pour nettoyer complètement votre environnement local :

Arrêtez le serveur Uvicorn local en appuyant sur Ctrl+C dans le terminal où il est en cours d'exécution.
Supprimez les répertoires de projet créés au cours de cet atelier :

# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Félicitations !

Vous avez créé et sécurisé un agent qui agit au nom de l'utilisateur connecté.

Dans cet atelier, vous avez appris à effectuer les opérations suivantes :

Identité du système d'agent : comment l'agent fonctionne sous sa propre identité de compte pour interagir de manière sécurisée avec l'infrastructure GCP, gérer les journaux de télémétrie et appeler les API de finalisation des identifiants.
Identité déléguée de l'utilisateur : façon dont l'agent demande l'autorisation d'agir au nom de l'utilisateur sur des plates-formes externes (comme GitHub) en déclenchant un flux de consentement OAuth à trois étapes (3LO).
Intégration sécurisée des outils : découvrez comment connecter des agents ADK à des serveurs MCP (Model Context Protocol) à l'aide de Google Cloud Auth Manager pour récupérer dynamiquement les jetons utilisateur au lieu d'utiliser des secrets codés en dur.
Configuration des règles IAM : découvrez comment configurer des liaisons d'autorisations précises pour autoriser à la fois l'identité de l'Agent Runtime et votre propre compte sur le fournisseur d'authentification.

Documentation complémentaire

Gestionnaire d'authentification des identités d'agent pour comprendre la configuration du flux d'authentification et les différents niveaux d'accès.
Agent Runtime Overview
Documentation ADK
Model Context Protocol