Membangun Agen AI yang bertindak Atas Nama pengguna dengan Identity Agen dan Auth Manager

1. Pengantar

Agen dengan kredensialnya sendiri dengan izin yang luas dapat melihat data semua orang. Dalam codelab ini, Anda akan membuat agen yang memanggil API pihak ketiga dengan kredensial pengguna yang login, sehingga agen tersebut melihat persis apa yang dapat dilihat orang tersebut dan tidak lebih.

Anda akan membangunnya dengan Google Agent Development Kit (ADK) dan Gemini Enterprise.

Secara khusus, Anda akan mempelajari cara mendesain arsitektur identitas ganda yang:

1. Agen bertindak atas namanya sendiri (Identitas Agen): Dengan Identitas Agen yang didukung SPIFFE, agen memanggil Pengelola Otorisasi, menyimpan telemetri, dan memanggil Google Cloud API.
2. Agen bertindak atas nama pengguna (Identitas yang Didelegasikan Pengguna): Untuk mengakses resource eksternal seperti GitHub, agen memicu alur izin OAuth 3-legged (3LO) untuk mengkueri alat secara aman menggunakan kredensial pengguna.

Untuk mencapainya, Anda akan mempelajari cara:

1. Bangun Agen ADK yang terhubung ke server Model Context Protocol (MCP) GitHub.
2. Perbarui alat agen dari PAT (token akses pribadi) GitHub statis ke alur OAuth 3-legged (3LO) menggunakan Google Cloud Auth Manager.
3. Deploy agen dengan aman ke Agent Runtime dan sediakan Agent Identity.
4. Konfigurasi peran IAM untuk memberikan akses identitas agen ke brankas token atas nama pengguna.
5. Memahami alur 3LO menyeluruh untuk Pengelola Auth di Google Cloud.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Project Google Cloud dengan penagihan diaktifkan.
• Google Cloud SDK (gcloud CLI) diinstal dan diautentikasi ke project Anda di mesin lokal Anda. Diperlukan versi 586.0.0 atau yang lebih baru — jalankan gcloud components update.
• Python 3.10 hingga 3.13 diinstal secara lokal.
• Pengelola paket uv telah diinstal (pip install uv).
• Akun GitHub untuk mendaftarkan aplikasi OAuth dan membuat token. Jika Anda tidak memiliki akun github, Anda dapat mengganti server MCP pihak ketiga yang mendukung three-legged OAuth 2.0.

2. Penyiapan Project

1. Lakukan autentikasi ke Google Cloud

Lakukan autentikasi ke Google Cloud dari command line lokal Anda untuk memastikan lingkungan Anda memiliki izin yang diperlukan untuk men-deploy ke Agent Runtime, menyediakan Agent Identity, dan mengonfigurasi Auth Manager selama lab ini:

Jalankan perintah berikut untuk login ke akun Google Cloud Anda guna mengonfigurasi Kredensial Default Aplikasi (ADC):

gcloud auth login
gcloud auth application-default login

2. Mengaktifkan Layanan Google Cloud yang Diperlukan

Aktifkan API yang diperlukan di project Google Cloud Anda untuk menjalankan lab ini. Jalankan perintah berikut di terminal.

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

Perintah ini mungkin memerlukan waktu satu menit untuk dieksekusi; setelah selesai, perintah ini akan kembali ke command prompt yang mengonfirmasi bahwa API sudah aktif.

3. Instal CLI agen dan siapkan project

agents-cli adalah alat command line yang digunakan untuk membuat struktur, mengelola, menguji, dan men-deploy agen ADK ke Gemini Enterprise. Instal secara lokal:

uvx google-agents-cli setup

Verifikasi penginstalan Anda:

agents-cli --help

Anda akan melihat menu bantuan CLI yang menampilkan perintah yang tersedia (seperti deploy, run, dan status).

Buat scaffolding project awal. Anda akan memulai dengan prototipe lokal dan menyempurnakannya nanti untuk deployment Agent Runtime:

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

Tindakan ini akan membuat direktori secure-agent-demo yang berisi kode agen dasar, dependensi, dan file pengujian Anda.

4. Tambahkan ekstra ADK yang diperlukan

pyproject.toml yang dihasilkan mengirimkan google-adk[gcp,otel-gcp], yang tidak memiliki dua ekstra yang dibutuhkan agen ini: mcp untuk toolset GitHub, dan agent-identity untuk Auth Manager nanti di lab. Buka secure-agent-demo/pyproject.toml dan ubah baris google-adk menjadi:

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

Kemudian, instal:

cd secure-agent-demo
agents-cli install

3. Membangun dan menguji agen

1. Membuat agen

Di dalam project Anda, ganti kode dalam file agent.py dengan kode berikut:

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

File ini menentukan tiga komponen utama agen:

• Petunjuk Sistem (INSTRUCTION): Menetapkan persona, membatasi cakupan asisten untuk penanganan masalah GitHub, dan menerapkan aturan keamanan yang ketat (seperti akses hanya baca dan memandu pengguna untuk melakukan autentikasi jika terjadi error).
• Konfigurasi Agen (root_agent): Membuat instance ADK Agent menggunakan model gemini-3.8-flash, mengonfigurasi logika percobaan ulang HTTP, dan melengkapi agen dengan toolset GitHub.
• Pembungkus Aplikasi (app): Mengenkapsulasi agen root ke dalam penampung ADK App, sehingga dapat di-deploy ke Agent Runtime.

2. Menambahkan Alat MCP GitHub

Agen terhubung ke GitHub melalui Model Context Protocol (MCP). Buat file baru bernama tools.py di folder app/ untuk mendaftarkan parameter koneksi gateway MCP. Salin-tempel kode berikut:

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

Fungsi ini membuat alat yang memanggil server MCP GitHub:

• Toolset MCP (McpToolset): Secara dinamis menemukan dan mendaftarkan kemampuan GitHub sebagai alat agen yang dapat dipanggil.
• Parameter Koneksi (StreamableHTTPConnectionParams): Mengarahkan toolset ke gateway MCP publik GitHub.
• Header Otorisasi: Menyuntikkan GITHUB_TOKEN sebagai token Bearer dan menerapkan mode hanya baca (X-MCP-Readonly: true) langsung di lapisan transport.

3. Menguji Secara Lokal dengan PAT (Personal Access Token) GitHub

Untuk menjalankan agen secara lokal dengan kredensial statis:

1. Buat Token Akses Pribadi GitHub. Berikan akses baca ke repositori Anda, jika tidak, agen hanya dapat melihat data publik dan perintah di bawah tidak akan menampilkan apa pun.
2. Tetapkan di lingkungan Anda:

   export GITHUB_TOKEN="your_github_pat_here"
   

3. Buka folder secure-agent-demo. Jalankan:

   cd secure-agent-demo
   agents-cli playground
   

4. Buka antarmuka playground, pilih folder "app" dari dropdown. Di kotak chat, ketik "Fetch my contributions across my private repositories over the last 6 months", dan verifikasi bahwa agen memanggil alat GitHub dan menampilkan data dari repositori pribadi Anda.

4. Mengonfigurasi Auth Manager

Meskipun pengodean permanen kredensial statis (seperti PAT) nyaman untuk pembuatan prototipe, hal ini membuat aplikasi produksi rentan terhadap kebocoran kredensial, periode nonaktif refresh token manual, dan kurangnya kontrol akses berbasis cloud.

Untuk mengatasi hal ini, Google Cloud menyediakan Pengelola Autentikasi Identitas Agen. Pengelola autentikasi Agent Identity adalah brankas kredensial yang dirancang untuk membantu melindungi kredensial. Agen dapat melakukan autentikasi menggunakan kunci API atau ID dan rahasia klien OAuth, atau atas nama pengguna melalui delegasi OAuth menggunakan token akses pengguna akhir.

Dalam Pengelola Auth, Anda mengonfigurasi penyedia autentikasi yang menentukan jenis dan kredensial autentikasi untuk aplikasi pihak ketiga tertentu. Penyedia autentikasi bersifat regional, dan region harus cocok dengan region tempat Anda men-deploy agen. Alur kerja Pengelola Autentikasi end-to-end beroperasi sebagai berikut:

1. Penyadapan Izin Dinamis: Saat agen mencoba menjalankan alat atas nama pengguna, ADK akan memeriksa Pengelola Autentikasi untuk menemukan kredensial valid yang ada. Jika tidak ada, Pengelola Otorisasi akan menampilkan URL otorisasi untuk memulai alur pemberian izin OAuth 3-legged (3LO).
2. Penyimpanan Vault yang Aman: Setelah pengguna akhir mengizinkan aplikasi, Pengelola Autentikasi akan otomatis mencegat callback OAuth dan menyimpan token akses dan refresh pengguna yang dihasilkan di vault kredensial yang aman dan dikelola Google.
3. Siklus Proses Token Otomatis: Pengelola Auth sepenuhnya mengelola masa berlaku dan rotasi token di latar belakang, sehingga tidak perlu logika refresh token manual atau periode nonaktif.
4. Eksekusi Alat Tanpa Secret: Untuk tindakan berikutnya, agen (yang melakukan autentikasi melalui SPIFFE Agent Identity) secara dinamis meminta token akses yang didelegasikan pengguna dari Pengelola Otorisasi saat runtime, sehingga kode klien dan agen tetap sepenuhnya tanpa secret.

Penting: Di sepanjang codelab ini, Anda akan melihat variabel placeholder yang ditulis dengan huruf kapital (seperti YOUR_PROJECT_ID, YOUR_PROJECT_NUMBER, YOUR_ORG_ID, dan YOUR_ENGINE_ID). Pastikan untuk mengganti variabel ini dengan nilai project dan resource Google Cloud Anda sendiri saat menjalankan perintah.

Langkah A: Mengonfigurasi GitHub sebagai Penyedia Auth

Jalankan perintah gcloud berikut untuk membuat penyedia autentikasi GitHub di project Google Cloud Anda. Anda akan memberikan ID dan rahasia klien nanti: GitHub tidak akan menerbitkannya hingga mengetahui URL callback penyedia ini.

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"

Jelaskan penyedia untuk mengambil URL pengalihan OAuth yang dibuat:

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

Kolomnya adalah redirectUrl, bertingkat di bawah authProviderTypeParams.threeLeggedOauth. Untuk membacanya secara langsung:

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

Sepertinya https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Langkah B: Mendaftarkan Aplikasi OAuth di GitHub

1. Buka halaman Setelan Developer GitHub, lalu klik Register a new OAuth app.
2. Untuk URL Halaman beranda, masukkan URL aplikasi frontend Anda (misalnya, http://localhost:8501 untuk pembuatan prototipe lokal. Anda dapat mengubahnya nanti menjadi URL yang di-deploy dalam produksi.
3. Tetapkan URI Pengalihan ke redirectUrl yang diambil pada langkah sebelumnya.
4. Klik Register application, lalu klik Generate a new client secret dan simpan Client ID dan Client Secret.

Langkah C: Tambahkan kredensial GitHub ke penyedia autentikasi

Ganti Project ID, Client ID, dan Client Secret Anda, lalu jalankan perintah ini:

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"

Perintah akan mengembalikan penyedia dengan clientId yang terlihat; rahasia tidak akan dikembalikan.

👉 Setelah langkah ini selesai, Google Cloud Auth Manager Anda kini sepenuhnya dikonfigurasi dengan kredensial aplikasi GitHub OAuth Anda, sehingga menyiapkan Google Cloud untuk bertindak sebagai vault aman yang menangani siklus proses izin dan token.

5. Mengalihkan token PAT ke Auth Manager

Setelah Auth Manager dikonfigurasi sepenuhnya, langkah selanjutnya adalah memperbarui kode alat agen. Ganti app/tools.py Anda dengan kode berikut.

👉 Ganti project ID dan lokasi dalam variabel OAUTH_PROVIDER_NAME di bawah.

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

Memahami Kode Alat

Perubahan utamanya adalah auth_scheme. Dengan melampirkannya ke toolset, setiap kali agen memanggil GitHub, ADK akan meminta token pengguna tersebut terlebih dahulu dari Auth Manager. Jika belum ada, ADK akan meminta pengguna untuk login, bukan gagal. GITHUB_TOKEN yang di-hardcode telah hilang sepenuhnya.

6. Men-deploy Agen ke Agent Runtime

Setelah memperbarui alat MCP GitHub untuk menggunakan Auth Manager, langkah berikutnya adalah men-deploy agen ke Agent Runtime. Men-deploy-nya dengan Identitas Agen yang diaktifkan akan menyediakan ID SPIFFE unik untuk agen.

Mari kita mulai dengan melakukan inisialisasi konfigurasi deployment untuk project. Jalankan di terminal:

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

Perintah ini memeriksa struktur project Anda untuk mengetahui kompatibilitas ADK, menyiapkan konfigurasi pengemasan container pokok, dan menghasilkan file agents-cli-manifest.yaml di root project Anda yang telah diisi sebelumnya dengan setelan deployment default.

👉 Buka file agents-cli-manifest.yaml yang baru dibuat dan verifikasi atau perbarui kolom region menjadi us-central1 untuk memastikan agen Anda di-deploy di region yang sama dengan penyedia autentikasi Anda:

region: "us-central1"

Men-deploy Agen dengan Identitas Agen

Deploy dengan adk deploy agent_engine. Hal ini menyediakan Agent Identity sendiri untuk agen — identitas kriptografi unik yang didukung SPIFFE milik deployment ini, yang digunakan agen untuk mengautentikasi ke Auth Manager dan layanan Google Cloud lainnya.

👉 Ganti YOUR_PROJECT_ID sebelum menjalankan perintah ini:

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

Deployment memerlukan waktu beberapa menit untuk membangun dan mengupload container. Setelah selesai, CLI akan mencetak nama resource yang di-deploy. Catat nilai reasoningEngines/ENGINE_ID, karena Anda akan memerlukannya untuk memberi otorisasi pada agen dan mengarahkannya ke klien UI.

Gunakan adk deploy agent_engine, bukan agents-cli deploy --agent-identity. Keduanya berhasil di-deploy, tetapi menghasilkan bentuk resource yang berbeda. agents-cli deploy membangun server penampung tanpa classMethods; klien UI yang Anda jalankan nanti akan memanggil create_session() pada agen yang di-deploy dan gagal dengan 'AgentEngine' object has no attribute 'create_session'. adk deploy agent_engine menghasilkan bentuk AdkApp yang di-pickle, yang mengekspos 13 metode yang dibutuhkan klien.

Tempat pengguna diarahkan setelah memberikan izin: setelah pengguna menyetujui akses, browser mereka akan diarahkan ke alamat di OAUTH_CONTINUE_URI, yang ditayangkan oleh aplikasi klien Anda sendiri. Di lab ini, klien berjalan di komputer Anda, sehingga agen menggunakan default yang sudah ditetapkan di app/tools.py (http://localhost:8501/validateUserId) dan Anda tidak perlu mengubah apa pun. Jika Anda kemudian menghosting klien di tempat lain, perbarui default tersebut sebelum men-deploy.

Otorisasi Agent Identity

Setelah agen Anda berjalan di cloud, agen tersebut memerlukan izin untuk mengakses kredensial yang disimpan di Auth Manager. Secara default, identitas SPIFFE agen tidak memiliki akses ke resource cloud eksternal.

Jalankan perintah gcloud berikut untuk memberikan peran roles/agentidentity.user ke identitas agen Anda di resource penyedia autentikasi. Tindakan ini memberikan izin yang tepat kepada agen Anda untuk meminta token pengguna dari vault, dan tidak lebih.

👉 Ganti YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER, dan YOUR_ENGINE_ID (ID mesin ada di output deployment di atas).

Untuk mendapatkan YOUR_ORG_ID, jalankan perintah di bawah:

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"

Sekarang, berikan peran yang sama pada penyedia ke akun Anda sendiri. Klien UI yang Anda jalankan pada langkah berikutnya memanggil API penyelesaian kredensial dengan Kredensial Default Aplikasi Anda, jadi tanpa ini, alur izin akan gagal dengan error 403 di 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"

Binding kedua ini hanya diperlukan untuk menjalankan lab secara lokal. Dengan cara ini, klien di mesin Anda dapat menyelesaikan pemberian izin menggunakan kredensial Anda sendiri. Dalam produksi, klien berjalan dengan identitasnya sendiri, dan hanya pengikatan agen di atas yang diperlukan.

7. Memahami Alur Izin 3LO

Setelah agen di-deploy ke Agent Runtime dengan Agent Identity yang aman, langkah berikutnya adalah menyediakan antarmuka frontend kustom bagi pengguna untuk melakukan chat dengannya. Yang lebih penting lagi, Pengelola Autentikasi Google Cloud memerlukan handler callback aplikasi klien untuk menyelesaikan loop autentikasi.

Meskipun Google Cloud Auth Manager mengelola kredensial pengguna dengan aman di dalam vault, layanan ini tidak dapat menyelesaikan pertukaran token OAuth dengan sendirinya. Proses handshake 3LO mengandalkan aplikasi klien untuk menjembatani kesenjangan:

1. Saat pengguna mengizinkan aplikasi GitHub, GitHub akan mengalihkan pengguna kembali ke penyedia autentikasi Identitas Agen redirectUrl.
2. Kemudian, Auth Manager mengalihkan pop-up browser pengguna kembali ke URL panggilan balik sisi klien (continue_uri).
3. Aplikasi klien bertanggung jawab untuk mencegat pengalihan ini, membaca nonce dari cookie browser, dan memanggil endpoint credentials:finalize Google Cloud untuk menyelesaikan handshake.
4. Setelah klien menyelesaikan pertukaran, Google Cloud akan menyimpan token secara aman di brankas penyedia autentikasi, sehingga memungkinkan agen memanggil alat GitHub.

Tanpa hosting klien kustom ini yang menghosting endpoint callback, handshake akan tetap tidak selesai, dan vault tidak dapat menyimpan kredensial.

Alur OAuth 3LO interaktif mencakup beberapa lapisan. Berikut adalah siklus proses eksekusi lengkap permintaan alat. Kita akan menguraikannya dalam penjelasan di bawah dan di langkah berikutnya.

👉 Klik gambar untuk memperbesar.

Tanggung Jawab Inti Klien dalam Handshake

• Meneruskan tantangan izin (Langkah 5-6): agen memancarkan adk_request_credential yang membawa URL izin dan nonce sekali pakai; klien membuka pop-up dan menyimpan nonce sebagai cookie.
• Menghosting callback pengalihan (Langkah 10-11): /validateUserId, tempat Auth Manager mengirimkan pop-up setelah izin diberikan.
• Selesaikan token (Langkah 12-14): gabungkan status validasi dari pengalihan dengan nonce yang di-cache dan panggil credentials:finalize, yang menyimpan token di vault.

Membangun klien Anda sendiri

Anda tidak perlu menulis klien ini untuk lab — langkah berikutnya menjalankan klien yang telah dibuat sebelumnya. Saat Anda menerapkan hal ini di aplikasi Anda sendiri, berikut dua referensi yang dapat digunakan:

• Perbarui aplikasi sisi klien Anda dalam dokumentasi Auth Manager, yang mencakup penanganan tantangan izin dan panggilan credentials:finalize.
• Klien sampel yang dapat dijalankan di repositori adk-python. Baca main.py di sana untuk mengetahui penerapan lengkap dan berfungsi dari tiga tanggung jawab di atas.

8. Menjalankan Klien UI Secara Lokal

Seperti yang kami lacak dalam diagram urutan Alur Izin 3LO, Pengelola Otorisasi perlu mengalihkan pop-up browser kembali ke endpoint callback sisi klien. Klien contoh menghosting endpoint tersebut di /validateUserId. Mari kita eksekusi secara lokal.

Menyalin file klien ke Lokal

Buka folder gcp_auth/client di repositori GitHub adk-python. Folder ini berisi aset yang diperlukan untuk membuat container klien chat kita.

👉 Salin semua file di gcp_auth/client ke lingkungan lokal Anda:

• main.py: Skrip aplikasi FastAPI yang berisi callback penyelesaian token (/validateUserId) yang kita bahas di bagian sebelumnya.
• static/: Berisi halaman HTML.

Atau, Anda juga dapat melakukan checkout jarang folder:

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

Menjalankan klien

1. Buka folder client yang baru saja Anda salin:

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

2. Buat lingkungan virtual dan instal dependensi klien. Folder ini mengirimkan requirements.txt dan tidak ada pyproject.toml, sehingga uv run uvicorn ... sendiri gagal dengan 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. Arahkan klien ke agen yang Anda deploy, lalu mulai di 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
   

4. Pastikan server berhasil dimulai dan memproses permintaan di http://localhost:8501.

Gunakan localhost, bukan 127.0.0.1. Pengalihan OAuth memerlukan nama host localhost; keduanya tidak dapat dipertukarkan di sini meskipun keduanya diselesaikan ke alamat yang sama.

9. Menguji Alur OAuth

Setelah semua layanan di-deploy, binding IAM dikonfigurasi, dan variabel lingkungan ditetapkan, Anda siap menguji alur otorisasi yang didelegasikan pengguna secara menyeluruh dan aman.

Langkah A: Mulai Eksekusi Alat

1. Buka tab browser, lalu buka URL Klien Anda: http://localhost:8501.
2. Di panel kiri, tetapkan Jenis Agen ke Remote Agent Engine.
3. Ketik Project dan Lokasi Google Cloud Anda. Klik Load Remote Agents. Semua agen yang di-deploy ke project Anda akan dimuat.
4. Pilih agen yang tepat dari dropdown dan simpan setelan.
5. Di kotak chat, ketik:

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

   lalu tekan Enter.
6. Amati UI chat: Karena agen belum memiliki kredensial untuk sesi pengguna Anda, agen akan menerima tantangan autentikasi dan menampilkan kartu Autentikasi Diperlukan dalam rangkaian percakapan.

Langkah B: Selesaikan Izin OAuth 3-Legged

1. Jendela pop-up browser terpisah akan terbuka, yang mengalihkan Anda melalui Pengelola Auth Google Cloud ke halaman otorisasi OAuth GitHub.
2. Tinjau izin yang diminta, lalu klik Beri otorisasi.
3. GitHub akan mengalihkan kembali ke Google Cloud, yang mengalihkan pop-up ke URL callback localhost Anda /validateUserId.
4. Layanan callback memproses dan menyelesaikan handshake kredensial.

Langkah C: Lanjutkan

1. Setelah jendela pop-up ditutup, tab chat induk akan otomatis mendeteksi penutupan.
2. Frontend mengirimkan payload resume kembali ke agen.
3. Agen mengambil token yang baru ditukar secara aman dari Google Cloud Auth Manager, memanggil alat MCP GitHub atas nama Anda, dan melakukan streaming data dari repositori pribadi Anda langsung kembali ke jendela chat — data yang tidak dapat diakses oleh agen itu sendiri.

Langkah D: Periksa Log Cloud

Untuk memverifikasi bahwa pertukaran dan penyelesaian token diproses dengan aman:

1. Buka Logs Explorer di Konsol Google Cloud.
2. Temukan log server yang mengonfirmasi ekstraksi nonce dan validasi yang berhasil:

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

3. Periksa Log Agent Runtime: Atau, Anda dapat melihat log eksekusi langsung di dalam Konsol Agent Platform:
   • Buka Agent Runtime Console.
   • Klik agen yang di-deploy dari daftar.
   • Beralih ke tab Playground; tab ini akan menampilkan log agen aktif di panel bawah, yang menunjukkan reasoning loop agen, detail eksekusi alat, dan siklus proses pengambilan token secara real time.

10. Pembersihan

Untuk menghindari biaya berkelanjutan di Google Cloud, bersihkan resource yang di-deploy:

# 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

Membersihkan File Lokal

Atau, untuk membersihkan lingkungan lokal Anda sepenuhnya:

1. Hentikan server uvicorn lokal dengan menekan Ctrl+C di terminal tempat server berjalan.
2. Hapus direktori project yang dibuat selama lab ini:

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

11. Selamat!

Anda telah berhasil membangun dan mengamankan agen yang bertindak atas nama pengguna yang login.

Hal yang telah Anda pelajari:

• Identitas Sistem Agen: Cara kerja agen dengan identitas Akunnya sendiri untuk berinteraksi secara aman dengan infrastruktur GCP, mengelola log telemetri, dan memanggil API penyelesaian kredensial.
• Identitas yang Didelegasikan Pengguna: Cara agen meminta otorisasi untuk bertindak atas nama pengguna di platform eksternal (seperti GitHub) dengan memicu alur izin OAuth 3-legged (3LO).
• Integrasi Alat yang Aman: Cara menghubungkan Agen ADK ke server Model Context Protocol (MCP) menggunakan Pengelola Autentikasi Google Cloud untuk mengambil token pengguna secara dinamis, bukan menggunakan secret yang di-hardcode.
• Konfigurasi Kebijakan IAM: Cara menyiapkan binding izin terperinci untuk mengizinkan identitas Agent Runtime dan akun Anda sendiri di penyedia autentikasi.

Bacaan Lebih Lanjut

• Agent Identity Auth Manager untuk memahami konfigurasi dan cakupan alur autentikasi.
• Ringkasan Agent Runtime
• Dokumentasi ADK
• Model Context Protocol