Tworzenie agenta AI, który działa w imieniu użytkownika, za pomocą Agent Identity i Menedżera uwierzytelniania

1. Wprowadzenie

Agent z własnymi danymi logowania i szerokimi uprawnieniami widzi dane wszystkich użytkowników. W tym laboratorium kodowania utworzysz agenta, który wywołuje interfejs API innej firmy przy użyciu danych logowania zalogowanego użytkownika, dzięki czemu widzi dokładnie to, co ta osoba, i nic więcej.

Utworzysz go za pomocą pakietu Agent Development Kit (ADK) Google i Gemini Enterprise.

Dowiesz się, jak zaprojektować architekturę podwójnej tożsamości, w której:

  1. Agent działa we własnym imieniu (tożsamość agenta): za pomocą tożsamości agenta opartej na SPIFFE agent wywołuje Menedżera autoryzacji, przechowuje dane telemetryczne i wywołuje interfejsy Google Cloud API.
  2. Agent działa w imieniu użytkownika (tożsamość delegowana przez użytkownika): aby uzyskać dostęp do zasobów zewnętrznych, takich jak GitHub, agent uruchamia proces uzyskiwania zgody w ramach 3-etapowego protokołu OAuth (3LO), aby bezpiecznie wysyłać zapytania do narzędzi przy użyciu danych logowania użytkownika.

Architektura podwójnej tożsamości

Aby to osiągnąć, dowiesz się, jak:

  1. Utwórz agenta ADK, który łączy się z serwerem Model Context Protocol (MCP) GitHub.
  2. Zaktualizuj narzędzie agenta ze statycznego osobistego tokena dostępu (PAT) GitHuba do przepływu 3-etapowej autoryzacji OAuth (3LO) za pomocą Menedżera autoryzacji Google Cloud.
  3. Bezpiecznie wdróż agenta w Agent Runtime i udostępnij Agent Identity.
  4. Skonfiguruj role uprawnień, aby zapewnić agentowi dostęp do skarbca tokenów w imieniu użytkownika.
  5. Poznaj kompleksowy proces 3LO w przypadku usługi Auth Manager w Google Cloud.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

  • Projekt Google Cloud z włączonymi płatnościami.
  • Pakiet SDK Google Cloud (gcloud CLI) zainstalowany i uwierzytelniony w Twoim projekcie na komputerze lokalnym. Wymagana jest wersja 586.0.0 lub nowsza – uruchom gcloud components update.
  • Python 3.10–3.13 zainstalowany lokalnie.
  • Zainstalowany uv system zarządzania pakietami (pip install uv).
  • Konto GitHub, aby zarejestrować aplikację OAuth i utworzyć tokeny. Jeśli nie masz konta GitHub, możesz użyć dowolnego serwera MCP innej firmy, który obsługuje trzyskładnikowe uwierzytelnianie OAuth 2.0.

2. Konfiguracja projektu

1. Uwierzytelnianie w Google Cloud

Uwierzytelnij się w Google Cloud z lokalnego wiersza poleceń, aby upewnić się, że Twoje środowisko ma uprawnienia niezbędne do wdrożenia w Agent Runtime, udostępnienia Agent Identity i skonfigurowania menedżera uwierzytelniania w tym module:

Aby zalogować się na konto Google Cloud i skonfigurować domyślne uwierzytelnianie aplikacji (ADC), uruchom te polecenia:

gcloud auth login
gcloud auth application-default login

2. Włączanie wymaganych usług Google Cloud

Aby przeprowadzić to ćwiczenie, włącz w projekcie Google Cloud niezbędne interfejsy API. Uruchom w terminalu to polecenie:

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

Wykonanie tego polecenia może potrwać minutę. Po zakończeniu pojawi się wiersz poleceń z potwierdzeniem, że interfejsy API są aktywne.

3. Instalowanie interfejsu wiersza poleceń agentów i konfigurowanie projektu

agents-cli to narzędzie wiersza poleceń służące do tworzenia szkieletów, zarządzania, testowania i wdrażania agentów ADK w Gemini Enterprise. Zainstaluj go lokalnie:

uvx google-agents-cli setup

Sprawdź instalację:

agents-cli --help

Powinno się wyświetlić menu pomocy interfejsu wiersza poleceń z dostępnymi poleceniami (np. deploy, run i status).

Wygeneruj początkową strukturę projektu. Zaczniesz od lokalnego prototypu, a później ulepszysz go na potrzeby wdrożenia w środowisku wykonawczym Agent Runtime:

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

Spowoduje to utworzenie katalogu secure-agent-demo zawierającego podstawowy kod agenta, zależności i pliki testowe.

4. Dodawanie wymaganych dodatków ADK

Wygenerowany pyproject.toml statek google-adk[gcp,otel-gcp] nie ma 2 dodatków, których potrzebuje ten agent: mcp do zestawu narzędzi GitHub i agent-identity do usługi Auth Manager w dalszej części laboratorium. Otwórz secure-agent-demo/pyproject.toml i zmień wiersz google-adk na:

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

Następnie zainstaluj:

cd secure-agent-demo
agents-cli install

3. Tworzenie i testowanie agenta

1. Tworzenie agenta

W projekcie zastąp kod w pliku agent.py tym kodem:

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

Ten plik określa 3 kluczowe komponenty agenta:

  • Instrukcja systemowa (INSTRUCTION): określa profil, ogranicza zakres działania asystenta do triage w GitHubie i wymusza przestrzeganie ścisłych zasad bezpieczeństwa (np. dostęp tylko do odczytu i instrukcje dla użytkowników dotyczące uwierzytelniania w przypadku wystąpienia błędów).
  • Konfiguracja agenta (root_agent): tworzy instancję ADK Agent za pomocą modelu gemini-3.8-flash, konfiguruje logikę ponawiania prób HTTP i wyposaża agenta w zestaw narzędzi GitHub.
  • App Wrapper (app): umieszcza agenta głównego w kontenerze ADK App, dzięki czemu można go wdrożyć w Agent Runtime.

2. Dodawanie narzędzia MCP GitHub

Agent łączy się z GitHubem za pomocą protokołu Model Context Protocol (MCP). Utwórz nowy plik o nazwie tools.py w folderze app/, aby zarejestrować parametry połączenia bramy MCP. Skopiuj i wklej ten kod:

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

Ta funkcja tworzy narzędzie, które wywołuje serwer MCP GitHub:

  • Zestaw narzędzi MCP (McpToolset): dynamicznie wykrywa i rejestruje funkcje GitHub jako narzędzia agenta, które można wywoływać.
  • Connection Parameters (StreamableHTTPConnectionParams): wskazuje zestaw narzędzi na publiczną bramę MCP GitHub.
  • Nagłówki autoryzacji: wstrzykuje GITHUB_TOKEN jako token Bearer i wymusza tryb tylko do odczytu (X-MCP-Readonly: true) bezpośrednio w warstwie transportowej.

3. Testowanie lokalne za pomocą osobistego tokena dostępu do GitHuba

Aby uruchomić agenta lokalnie ze statycznymi danymi logowania:

  1. Utwórz osobisty token dostępu GitHub. Przyznaj mu dostęp do odczytu repozytoriów. W przeciwnym razie agent będzie widzieć tylko dane publiczne, a poniższy prompt nie zwróci żadnych wyników.
  2. Ustaw ją w środowisku: 
    export GITHUB_TOKEN="your_github_pat_here"
  3. Przejdź do folderu secure-agent-demo. Uruchomienie: 
    cd secure-agent-demo
agents-cli playground
  4. Otwórz interfejs platformy testowej i w menu wybierz folder „app”. W oknie czatu wpisz "Fetch my contributions across my private repositories over the last 6 months" i sprawdź, czy agent wywołuje narzędzie GitHub i zwraca dane z Twoich prywatnych repozytoriów.

4. Konfigurowanie Menedżera uwierzytelniania

Zakodowanie na stałe statycznych danych logowania (np. PAT) jest wygodne w przypadku prototypowania, ale naraża aplikacje produkcyjne na wyciek danych logowania, przestoje związane z ręcznym odświeżaniem tokena i brak natywnych dla chmury mechanizmów kontroli dostępu.

Aby rozwiązać ten problem, Google Cloud udostępnia Menedżera uwierzytelniania tożsamości agenta. Menedżer uwierzytelniania tożsamości agentów to magazyn danych logowania, który pomaga chronić dane logowania. Umożliwia agentom uwierzytelnianie za pomocą klucza API lub identyfikatora klienta OAuth i tajnego klucza albo w imieniu użytkownika za pomocą przekazywania dostępu OAuth z użyciem tokenów dostępu użytkownika.

W Menedżerze uwierzytelniania możesz skonfigurować dostawców uwierzytelniania, którzy określają typ uwierzytelniania i dane logowania w przypadku konkretnych aplikacji innych firm. Dostawcy uwierzytelniania są regionalni, a region musi pasować do regionu, w którym wdrażasz agenta. Kompleksowy przepływ pracy Menedżera autoryzacji wygląda tak:

Przepływ pracy Menedżera uwierzytelniania

  1. Dynamiczne przechwytywanie zgody: gdy agent próbuje wykonać narzędzie w imieniu użytkownika, ADK sprawdza w Menedżerze autoryzacji, czy istnieją prawidłowe dane logowania. Jeśli nie istnieje, Auth Manager zwraca adres URL autoryzacji, aby rozpocząć proces wyrażania zgody OAuth z 3 etapami.
  2. Bezpieczne przechowywanie w Vault: gdy użytkownik autoryzuje aplikację, Menedżer autoryzacji automatycznie przechwytuje wywołanie zwrotne OAuth i przechowuje uzyskane tokeny dostępu i odświeżania użytkownika w bezpiecznym magazynie danych logowania zarządzanym przez Google.
  3. Automatyczny cykl życia tokena: menedżer uwierzytelniania w pełni zarządza wygasaniem i rotacją tokenów w tle, eliminując potrzebę ręcznego odświeżania tokenów lub przestojów.
  4. Wykonywanie narzędzia bez klucza tajnego: w przypadku kolejnych działań agent (uwierzytelniający się za pomocą Agent Identity SPIFFE) dynamicznie żąda od Menedżera autoryzacji tokena dostępu delegowanego użytkownika w czasie działania, dzięki czemu kod klienta i agenta pozostaje całkowicie wolny od kluczy tajnych.

Krok A. Skonfiguruj GitHub jako dostawcę uwierzytelniania

Aby utworzyć dostawcę uwierzytelniania GitHub w projekcie Google Cloud, uruchom to polecenie gcloud. Identyfikator klienta i tajny klucz podasz później: GitHub nie wyda ich, dopóki nie pozna adresu URL wywołania zwrotnego tego dostawcy.

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"

Opisz dostawcę, aby pobrać wygenerowany adres URL przekierowania OAuth:

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

Pole redirectUrl jest zagnieżdżone w polu authProviderTypeParams.threeLeggedOauth. Aby przeczytać ją bezpośrednio:

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

Wygląda na to, że https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Krok B. Zarejestruj aplikację OAuth w GitHub

  1. Otwórz stronę ustawień dewelopera GitHub i kliknij Zarejestruj nową aplikację OAuth.
  2. W polu URL strony głównej wpisz adres URL aplikacji frontendowej (np. http://localhost:8501 w przypadku lokalnego prototypowania). Możesz później zmienić go na wdrożony adres URL w środowisku produkcyjnym.
  3. Ustaw identyfikator URI przekierowania na wartość redirectUrl uzyskaną w poprzednim kroku.
  4. Kliknij Zarejestruj aplikację, a potem Wygeneruj nowy tajny klucz klienta. Zapisz identyfikator klienta i tajny klucz klienta.

Krok C. Dodaj dane logowania GitHub do dostawcy uwierzytelniania

Zastąp identyfikator projektu, identyfikator klienta i tajny klucz klienta, a następnie uruchom to polecenie:

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"

Polecenie zwraca dostawcę z parametrem clientId, ale nie zwraca klucza tajnego.

👉 Po wykonaniu tego kroku Menedżer autoryzacji Google Cloud będzie w pełni skonfigurowany przy użyciu danych logowania aplikacji OAuth na GitHubie, co umożliwi Google Cloud pełnienie roli bezpiecznego magazynu, który obsługuje zgody i cykle życia tokenów.

5. Przełączanie tokena PAT na Menedżera uwierzytelniania

Po pełnym skonfigurowaniu Menedżera autoryzacji kolejnym krokiem jest zaktualizowanie kodu narzędzia agenta. Zastąp plik app/tools.py poniższym kodem.

👉 Zastąp identyfikator projektu i lokalizację w zmiennej OAUTH_PROVIDER_NAME poniżej.

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

Informacje o kodzie narzędzia

Kluczowa zmiana to auth_scheme. Dołączenie go do zestawu narzędzi oznacza, że za każdym razem, gdy agent wywołuje GitHub, ADK najpierw prosi Menedżera autoryzacji o token użytkownika. Jeśli go nie ma, zamiast zgłaszać błąd, prosi użytkownika o zalogowanie się. Zakodowany na stałe znak GITHUB_TOKEN całkowicie zniknął.

6. Wdrażanie agenta w Agent Runtime

Po zaktualizowaniu narzędzia MCP GitHub, aby zamiast niego używać Menedżera autoryzacji, następnym krokiem jest wdrożenie agenta w środowisku wykonawczym agenta. Wdrożenie z włączoną tożsamością agenta zapewnia agentowi unikalny identyfikator SPIFFE.

Zacznijmy od zainicjowania konfiguracji wdrożenia projektu. Uruchom w terminalu:

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

To polecenie sprawdza strukturę projektu pod kątem zgodności z ADK, przygotowuje konfiguracje pakowania kontenera bazowego i generuje w katalogu głównym projektu plik agents-cli-manifest.yaml wstępnie wypełniony domyślnymi ustawieniami wdrażania.

👉 Otwórz nowo utworzony plik agents-cli-manifest.yaml i sprawdź lub zaktualizuj pole region na us-central1, aby mieć pewność, że agent jest wdrażany w tym samym regionie co dostawca uwierzytelniania:

region: "us-central1"

Wdrażanie agenta z Agent Identity

Wdróż za pomocą adk deploy agent_engine. Dzięki temu agent otrzymuje własną Agent Identity – unikalną tożsamość kryptograficzną opartą na SPIFFE, która należy do tego wdrożenia i której agent używa do uwierzytelniania w usłudze Auth Manager i innych usługach Google Cloud.

👉 Zanim uruchomisz te polecenia, zastąp symbol YOUR_PROJECT_ID:

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

Wdrożenie potrwa kilka minut, ponieważ trzeba utworzyć i przesłać kontener. Po zakończeniu interfejs CLI wyświetli nazwę wdrożonego zasobu. Zanotuj wartość Engines/ENGINE_ID, ponieważ jest ona potrzebna do autoryzacji agenta i skierowania do niego klienta interfejsu.

Autoryzowanie Agent Identity

Teraz, gdy agent działa w chmurze, potrzebuje uprawnień do uzyskiwania dostępu do danych logowania przechowywanych w usłudze Auth Manager. Domyślnie tożsamość SPIFFE agenta nie ma dostępu do zewnętrznych zasobów w chmurze.

Uruchom to polecenie gcloud, aby przyznać tożsamości agenta rolę roles/agentidentity.user w zasobie dostawcy uwierzytelniania. Dzięki temu agent uzyskuje dokładnie te uprawnienia, których potrzebuje do wysyłania do skarbca próśb o tokeny użytkowników, i nic więcej.

👉 Zastąp YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER i YOUR_ENGINE_ID (identyfikator silnika znajdziesz w danych wyjściowych wdrożenia powyżej).

Aby uzyskać identyfikator YOUR_ORG_ID, uruchom to polecenie:

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"

Teraz przypisz swojemu kontu tę samą rolę u dostawcy. Klient interfejsu, który uruchomisz w następnym kroku, wywoła interfejs API finalizacji danych logowania za pomocą domyślnego uwierzytelniania aplikacji, więc bez tego procesu zgody nie będzie można uzyskać i zwrócony zostanie błąd 403: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. Omówienie procesu uzyskiwania zgody w przypadku plików cookie innych firm

Po wdrożeniu agenta w środowisku Agent Runtime z bezpieczną tożsamością Agent Identity kolejnym krokiem jest udostępnienie użytkownikom niestandardowego interfejsu frontendu, za pomocą którego będą mogli z nim czatować. Co ważniejsze, Google Cloud Auth Manager wymaga, aby aplikacja kliencka miała procedurę obsługi wywołania zwrotnego, która umożliwia dokończenie pętli uwierzytelniania.

Menedżer uwierzytelniania Google Cloud bezpiecznie zarządza danymi logowania użytkowników w skarbcu, ale nie może samodzielnie dokończyć wymiany tokenów OAuth. Uzgadnianie połączenia 3LO polega na tym, że aplikacja kliencka wypełnia lukę:

  1. Gdy użytkownik autoryzuje aplikację GitHub, GitHub przekierowuje go z powrotem do dostawcy uwierzytelniania Agent Identity redirectUrl.
  2. Menedżer uwierzytelniania przekierowuje wyskakujące okienko przeglądarki użytkownika z powrotem do adresu URL wywołania zwrotnego po stronie klienta (continue_uri).
  3. Aplikacja kliencka musi przechwycić to przekierowanie, odczytać wartość nonce z plików cookie przeglądarki i wywołać punkt końcowy credentials:finalize Google Cloud, aby dokończyć uzgadnianie.
  4. Gdy klient zakończy wymianę, Google Cloud bezpiecznie zapisze token w skarbcu dostawcy uwierzytelniania, co umożliwi agentowi wywoływanie narzędzia GitHub.

Jeśli niestandardowy klient nie będzie hostować punktu końcowego wywołania zwrotnego, uzgadnianie połączenia pozostanie niekompletne, a magazyn nie będzie mógł przechowywać danych logowania.

Interaktywny przepływ OAuth 3LO obejmuje wiele warstw. Oto pełny cykl życia wykonania żądania narzędzia. Szczegółowe wyjaśnienie znajdziesz poniżej i w następnym kroku.

👉 Kliknij obraz, aby go powiększyć.

Przepływ sekwencji OAuth z 3 etapami

Główne obowiązki klienta w ramach umowy

  • Przekazywanie wyzwania dotyczącego zgody użytkownika (kroki 5–6): agent wysyła komunikat adk_request_credential zawierający adres URL zgody i jednorazowy numer losowy; klient otwiera wyskakujące okienko i zapisuje numer losowy jako plik cookie.
  • Hostuj wywołanie zwrotne przekierowania (kroki 10–11): /validateUserId, gdzie Menedżer autoryzacji wysyła wyskakujące okienko po uzyskaniu zgody.
  • Finalizowanie tokena (kroki 12–14): połącz stan weryfikacji z przekierowania z zapisaną w pamięci podręcznej liczbą jednorazową i wywołaj funkcję credentials:finalize, która zapisuje token w magazynie.

Tworzenie własnego klienta

Nie musisz pisać tego klienta na potrzeby modułu – w następnym kroku uruchomisz gotowego klienta. Jeśli chcesz wdrożyć to rozwiązanie w swojej aplikacji, skorzystaj z tych 2 materiałów:

8. Lokalne uruchamianie klienta interfejsu

Jak pokazaliśmy na diagramie sekwencji 3LO Consent Flow, Menedżer autoryzacji musi przekierować wyskakujące okienko przeglądarki z powrotem do punktu końcowego wywołania zwrotnego po stronie klienta. Przykładowy klient hostuje ten punkt końcowy pod adresem /validateUserId. Uruchommy go lokalnie.

Kopiowanie plików klienta na urządzenie lokalne

Otwórz folder gcp_auth/client w repozytorium GitHub adk-python. Ten folder zawiera komponenty wymagane do utworzenia kontenera klienta czatu.

👉 Skopiuj wszystkie pliki z sekcji gcp_auth/client do środowiska lokalnego:

  • main.py: skrypt aplikacji FastAPI zawierający wywołanie zwrotne finalizacji tokena (/validateUserId), o którym mówiliśmy w poprzedniej sekcji.
  • static/: zawiera strony HTML.

Możesz też wykonać rzadkie wyewidencjonowanie folderu:

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

Uruchom klienta

  1. Przejdź do skopiowanego folderu client: 
    cd adk-python/contributing/samples/integrations/gcp_auth/client
  2. Utwórz środowisko wirtualne i zainstaluj zależności klienta. Folder zawiera requirements.txt, ale nie zawiera pyproject.toml, więc samo uv run uvicorn ... kończy się niepowodzeniem z błędem 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. Skieruj klienta na wdrożonego agenta, a następnie uruchom go na porcie 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. Sprawdź, czy serwer został uruchomiony i nasłuchuje na porcie http://localhost:8501.

9. Testowanie procesu OAuth

Gdy wszystkie usługi zostaną wdrożone, powiązania IAM skonfigurowane, a zmienne środowiskowe ustawione, możesz przetestować bezpieczny kompleksowy przepływ autoryzacji delegowanej przez użytkownika.

Krok A. Zainicjuj działanie narzędzia

  1. Otwórz kartę przeglądarki i przejdź do adresu URL klienta: http://localhost:8501.
  2. W panelu po lewej stronie ustaw typ agenta na Remote Agent Engine.
  3. Wpisz projekt i lokalizację Google Cloud. Kliknij Load Remote Agents. Powinny się załadować wszystkie agenty wdrożone w Twoim projekcie.
  4. Wybierz odpowiedniego agenta z menu i zapisz ustawienia.
  5. W polu czatu wpisz: 
    Fetch my contributions across my private repositories over the last 6 months
    i naciśnij Enter.
  6. Obserwuj interfejs czatu: ponieważ agent nie ma jeszcze danych logowania do sesji użytkownika, otrzymuje test zabezpieczający logowanie i wyświetla w wątku rozmowy kartę Wymagane uwierzytelnianie.
  1. Otworzy się osobne wyskakujące okienko przeglądarki, które przekieruje Cię przez Menedżera uwierzytelniania Google Cloud na stronę autoryzacji GitHub OAuth.
  2. Sprawdź wymagane uprawnienia i kliknij Autoryzuj.
  3. GitHub przekieruje Cię z powrotem do Google Cloud, który przekieruje wyskakujące okienko na localhost adres URL wywołania zwrotnego /validateUserId.
  4. Usługa wywołania zwrotnego przetwarza i finalizuje uzgadnianie danych logowania.

Krok C. Wznów

  1. Gdy okno wyskakujące zostanie zamknięte, karta czatu rodzica automatycznie wykryje to zamknięcie.
  2. Frontend wysyła do agenta ładunek z informacjami o wznowieniu.
  3. Agent pobiera nowo wymieniony token w bezpieczny sposób z usługi Google Cloud Auth Manager, wywołuje w Twoim imieniu narzędzia GitHub MCP i przesyła strumieniowo dane z Twoich prywatnych repozytoriów bezpośrednio do okna czatu. Są to dane, do których agent nie miałby dostępu samodzielnie.

Krok D. Sprawdź logi Cloud

Aby sprawdzić, czy wymiana i finalizacja tokena zostały przetworzone w bezpieczny sposób:

  1. Otwórz Eksplorator logów w konsoli Google Cloud.
  2. Znajdź logi serwera potwierdzające wyodrębnienie nonce i pomyślną weryfikację: 
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.
  3. Sprawdzanie dzienników Agent Runtime: dzienniki wykonania możesz też wyświetlić bezpośrednio w konsoli Agent Platform:
    • Otwórz konsolę Agent Runtime.
    • Na liście kliknij wdrożonego agenta.
    • Przejdź na kartę Playground. W dolnym panelu wyświetlą się dzienniki agenta na żywo, pokazujące w czasie rzeczywistym pętlę rozumowania agenta, szczegóły wykonania narzędzia i cykl życia pobierania tokenów.

10. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, zwalniaj miejsce w wdrożonych zasobach:

# 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

Zwalnianie miejsca na pliki lokalne

Opcjonalnie, aby całkowicie zwolnić miejsce w środowisku lokalnym:

  1. Zatrzymaj lokalny serwer uvicorn, naciskając Ctrl+C w terminalu, w którym jest uruchomiony.
  2. Usuń katalogi projektu utworzone w ramach tego laboratorium:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. Gratulacje!

Udało Ci się utworzyć i zabezpieczyć agenta, który działa w imieniu zalogowanego użytkownika.

Czego się dowiedziałeś(-aś):

  • Tożsamość systemu agenta: sposób działania agenta w ramach własnej tożsamości konta, aby bezpiecznie komunikować się z infrastrukturą GCP, zarządzać dziennikami telemetrii i wywoływać interfejsy API finalizacji danych logowania.
  • Tożsamość delegowana użytkownika: sposób, w jaki agent prosi o autoryzację do działania w imieniu użytkownika na platformach zewnętrznych (np. GitHub) poprzez wywołanie procesu uzyskiwania zgody w ramach 3-etapowego protokołu OAuth (3LO).
  • Bezpieczna integracja narzędzi: jak łączyć agentów pakietu ADK z serwerami Model Context Protocol (MCP) za pomocą usługi Google Cloud Auth Manager, aby dynamicznie pobierać tokeny użytkowników zamiast używać zakodowanych na stałe kluczy tajnych.
  • Konfiguracja zasad IAM: jak skonfigurować szczegółowe powiązania uprawnień, aby autoryzować zarówno tożsamość środowiska wykonawczego agenta, jak i własne konto u dostawcy uwierzytelniania.

Więcej informacji