Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tạo một tác nhân AI thay mặt người dùng bằng Trình quản lý danh tính và uỷ quyền của tác nhân

1. Giới thiệu

Một tác nhân có thông tin đăng nhập riêng với quyền rộng sẽ thấy dữ liệu của mọi người. Trong lớp học lập trình này, bạn sẽ tạo một tác nhân gọi API của bên thứ ba bằng thông tin đăng nhập của chính người dùng đã đăng nhập, vì vậy, tác nhân này sẽ thấy chính xác những gì người đó có thể thấy và không thấy gì khác.

Bạn sẽ xây dựng tác nhân này bằng Bộ công cụ phát triển tác nhân (ADK) của Google và Gemini Enterprise.

Cụ thể, bạn sẽ tìm hiểu cách thiết kế một cấu trúc nhận dạng kép, trong đó:

Tác nhân hành động thay mặt cho chính nó (Danh tính tác nhân): Bằng cách sử dụng Danh tính tác nhân được SPIFFE hỗ trợ, tác nhân sẽ gọi Trình quản lý xác thực, lưu trữ dữ liệu đo từ xa và gọi các Cloud API của Google.
Tác nhân hành động thay cho người dùng (Danh tính do người dùng uỷ quyền): Để truy cập vào các tài nguyên bên ngoài như GitHub, tác nhân sẽ kích hoạt quy trình đồng ý OAuth 3 chân (3LO) để truy vấn các công cụ một cách an toàn bằng thông tin đăng nhập của người dùng.

Kiến trúc nhận dạng kép

Để đạt được điều này, bạn sẽ tìm hiểu cách:

Xây dựng một ADK Agent kết nối với máy chủ Giao thức ngữ cảnh mô hình (MCP) của GitHub.
Cập nhật công cụ của tác nhân từ PAT (mã truy cập cá nhân) tĩnh trên GitHub sang quy trình OAuth 3 chiều (3LO) bằng cách sử dụng Google Cloud Auth Manager.
Triển khai tác nhân một cách an toàn đến Thời gian chạy tác nhân và cung cấp Danh tính tác nhân.
Định cấu hình các vai trò IAM để cấp quyền truy cập danh tính của tác nhân vào kho mã thông báo thay cho người dùng.
Tìm hiểu quy trình 3LO từ đầu đến cuối cho Auth Manager trong Google Cloud.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo rằng bạn có:

Một Dự án trên Google Cloud đã bật tính năng thanh toán.
Google Cloud SDK (gcloud CLI) đã được cài đặt và xác thực cho dự án trên máy cục bộ. Bạn phải dùng phiên bản 586.0.0 trở lên – chạy gcloud components update.
Đã cài đặt Python 3.10 đến 3.13 trên máy.
Trình quản lý gói uv đã cài đặt (pip install uv).
Một tài khoản GitHub để đăng ký một ứng dụng OAuth và tạo mã thông báo. Nếu không có tài khoản github, bạn có thể thay thế bằng bất kỳ máy chủ MCP nào của bên thứ ba hỗ trợ OAuth 2.0 ba chân.

2. Thiết lập dự án

1. Xác thực với Google Cloud

Xác thực với Google Cloud từ dòng lệnh cục bộ để đảm bảo môi trường của bạn có các quyền cần thiết để triển khai cho Thời gian chạy của tác nhân, cung cấp Danh tính tác nhân và định cấu hình Trình quản lý uỷ quyền trong phòng thí nghiệm này:

Chạy các lệnh sau để đăng nhập vào tài khoản Google Cloud nhằm định cấu hình Thông tin xác thực mặc định của ứng dụng (ADC):

gcloud auth login
gcloud auth application-default login

2. Bật các dịch vụ bắt buộc của Google Cloud

Bật các API cần thiết trong dự án Google Cloud để chạy bài tập thực hành này. Chạy lệnh sau trong thiết bị đầu cuối:

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

Lệnh này có thể mất một phút để thực thi; sau khi hoàn tất, lệnh này sẽ quay lại dấu nhắc lệnh để xác nhận rằng các API đang hoạt động.

3. Cài đặt CLI của tác nhân và thiết lập dự án

agents-cli là công cụ dòng lệnh dùng để tạo khung, quản lý, kiểm thử và triển khai các tác nhân ADK cho Gemini Enterprise. Cài đặt cục bộ:

uvx google-agents-cli setup

Xác minh quá trình cài đặt:

agents-cli --help

Bạn sẽ thấy trình đơn trợ giúp của CLI hiển thị các lệnh có sẵn (chẳng hạn như deploy, run và status).

Tạo giàn giáo dự án ban đầu. Bạn sẽ bắt đầu bằng một nguyên mẫu cục bộ và cải thiện nguyên mẫu đó sau này để triển khai Thời gian chạy của tác nhân:

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

Thao tác này sẽ tạo thư mục secure-agent-demo chứa mã tác nhân cơ bản, các phần phụ thuộc và tệp kiểm thử.

4. Thêm các tiện ích ADK bắt buộc

pyproject.toml được tạo sẽ gửi google-adk[gcp,otel-gcp], thiếu 2 phần bổ sung mà tác nhân này cần: mcp cho bộ công cụ GitHub và agent-identity cho Auth Manager sau này trong phòng thí nghiệm. Mở secure-agent-demo/pyproject.toml rồi thay đổi dòng google-adk thành:

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

Sau đó, hãy cài đặt:

cd secure-agent-demo
agents-cli install

3. Tạo và kiểm thử tác nhân

1. Tạo tác nhân

Trong dự án của bạn, hãy thay thế mã trong tệp agent.py bằng đoạn mã sau:

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

Tệp này xác định 3 thành phần chính của tác nhân:

Hướng dẫn hệ thống (INSTRUCTION): Thiết lập tính cách, giới hạn phạm vi của trợ lý trong việc phân loại vấn đề trên GitHub và thực thi các quy tắc an toàn nghiêm ngặt (chẳng hạn như quyền truy cập chỉ đọc và hướng dẫn người dùng xác thực nếu xảy ra lỗi).
Cấu hình tác nhân (root_agent): Khởi tạo một ADK Agent bằng mô hình gemini-3.8-flash, định cấu hình logic thử lại HTTP và trang bị cho tác nhân bộ công cụ GitHub.
Trình bao bọc ứng dụng (app): Đóng gói tác nhân gốc vào một vùng chứa ADK App, giúp triển khai được vào Thời gian chạy tác nhân.

2. Thêm Công cụ MCP của GitHub

Tác nhân kết nối với GitHub thông qua Giao thức ngữ cảnh mô hình (MCP). Tạo một tệp mới có tên là tools.py trong thư mục app/ để đăng ký các tham số kết nối cổng MCP. Sao chép và dán mã sau:

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

Hàm này tạo ra một công cụ gọi máy chủ MCP của GitHub:

MCP Toolset (McpToolset): Tự động phát hiện và đăng ký các chức năng của GitHub dưới dạng các công cụ có thể gọi của tác nhân.
Connection Parameters (Tham số kết nối) (StreamableHTTPConnectionParams): Trỏ bộ công cụ đến cổng MCP công khai của GitHub.
Tiêu đề uỷ quyền: Chèn GITHUB_TOKEN dưới dạng mã thông báo truy cập và thực thi chế độ chỉ có thể đọc (X-MCP-Readonly: true) ngay tại tầng truyền tải.

3. Kiểm thử cục bộ bằng PAT (Mã thông báo truy cập cá nhân) của GitHub

Cách chạy tác nhân cục bộ bằng thông tin đăng nhập tĩnh:

Tạo Mã truy cập cá nhân trên GitHub. Cấp cho nó quyền đọc đối với kho lưu trữ của bạn, nếu không, tác nhân chỉ có thể xem dữ liệu công khai và lời nhắc bên dưới sẽ không trả về gì.

Đặt trong môi trường của bạn:

export GITHUB_TOKEN="your_github_pat_here"

Chuyển đến thư mục secure-agent-demo. Chạy:
```
cd secure-agent-demo
agents-cli playground
```
Mở giao diện sân chơi, chọn thư mục "app" trong trình đơn thả xuống. Trong hộp trò chuyện, hãy nhập "Fetch my contributions across my private repositories over the last 6 months" và xác minh rằng trợ lý gọi công cụ GitHub và trả về dữ liệu từ các kho lưu trữ riêng tư của bạn.

4. Định cấu hình Trình quản lý xác thực

Mặc dù việc mã hoá cứng thông tin đăng nhập tĩnh (chẳng hạn như PAT) rất thuận tiện cho việc tạo mẫu, nhưng việc này khiến các ứng dụng phát hành công khai dễ bị rò rỉ thông tin đăng nhập, thời gian ngừng hoạt động làm mới mã thông báo theo cách thủ công và thiếu các chế độ kiểm soát quyền truy cập gốc trên đám mây.

Để giải quyết vấn đề này, Google Cloud cung cấp Trình quản lý xác thực danh tính của tác nhân. Trình quản lý xác thực danh tính của tác nhân là một kho lưu trữ thông tin đăng nhập được thiết kế để giúp bảo vệ thông tin đăng nhập. Thư viện này cho phép các tác nhân xác thực bằng khoá API hoặc mã ứng dụng khách và mật khẩu OAuth, hoặc thay mặt cho người dùng thông qua uỷ quyền OAuth bằng mã truy cập của người dùng cuối.

Trong Trình quản lý uỷ quyền, bạn định cấu hình các trình cung cấp dịch vụ uỷ quyền để xác định loại xác thực và thông tin đăng nhập cho các ứng dụng cụ thể của bên thứ ba. Nhà cung cấp dịch vụ Xác thực theo vùng và vùng phải khớp với vùng mà bạn triển khai tác nhân. Quy trình Auth Manager từ đầu đến cuối hoạt động như sau:

Quy trình Auth Manager

Chặn sự đồng ý linh hoạt: Khi tác nhân cố gắng thực thi một công cụ thay cho người dùng, ADK sẽ kiểm tra Trình quản lý uỷ quyền để tìm thông tin xác thực hợp lệ hiện có. Nếu không có, Auth Manager sẽ trả về một URL uỷ quyền để bắt đầu quy trình đồng ý OAuth 3 bên (3LO).
Bộ nhớ Secure Vault: Sau khi người dùng cuối uỷ quyền cho ứng dụng, Auth Manager sẽ tự động chặn lệnh gọi lại OAuth và lưu trữ quyền truy cập của người dùng cũng như mã làm mới thu được trong một bộ nhớ thông tin đăng nhập an toàn do Google quản lý.
Vòng đời mã thông báo tự động: Auth Manager hoàn toàn quản lý quá trình hết hạn và xoay vòng mã thông báo ở chế độ nền, giúp bạn không cần phải làm mới mã thông báo theo cách thủ công hoặc thời gian ngừng hoạt động.
Thực thi công cụ không cần khoá bí mật: Đối với các hành động tiếp theo, tác nhân (xác thực thông qua Danh tính tác nhân SPIFFE) sẽ yêu cầu mã truy cập được uỷ quyền của người dùng từ Trình quản lý uỷ quyền một cách linh động trong thời gian chạy, giữ cho cả mã ứng dụng và mã tác nhân hoàn toàn không cần khoá bí mật.

Bước A: Định cấu hình GitHub làm Nhà cung cấp dịch vụ uỷ quyền

Chạy lệnh gcloud sau đây để tạo một trình cung cấp dịch vụ uỷ quyền GitHub trong dự án trên đám mây của Google. Sau đó, bạn cung cấp mã ứng dụng khách và khoá bí mật: GitHub sẽ không phát hành các mã này cho đến khi biết URL gọi lại của nhà cung cấp này.

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"

Mô tả nhà cung cấp để truy xuất URL chuyển hướng OAuth đã tạo:

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

Trường này là redirectUrl, được lồng trong authProviderTypeParams.threeLeggedOauth. Cách đọc trực tiếp:

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

Có vẻ như https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback.

Bước B: Đăng ký ứng dụng OAuth trong GitHub

Chuyển đến trang Cài đặt nhà phát triển GitHub rồi nhấp vào Đăng ký ứng dụng OAuth mới.
Đối với URL trang chủ, hãy nhập URL của ứng dụng giao diện người dùng (ví dụ: http://localhost:8501 để tạo mẫu cục bộ. Sau này, bạn có thể thay đổi thành URL đã triển khai trong môi trường phát hành chính thức.
Đặt URI chuyển hướng thành redirectUrl được truy xuất ở bước trước.
Nhấp vào Register application (Đăng ký ứng dụng), sau đó nhấp vào Generate a new client secret (Tạo khoá bí mật mới của ứng dụng khách) rồi lưu cả Mã ứng dụng khách và Khoá bí mật của ứng dụng khách.

Bước C: Thêm thông tin đăng nhập GitHub vào trình cung cấp dịch vụ uỷ quyền

Thay thế mã dự án, mã ứng dụng và khoá bí mật của ứng dụng rồi chạy lệnh này:

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"

Lệnh này sẽ phản hồi nhà cung cấp bằng clientId có thể nhìn thấy; bí mật sẽ không được phản hồi.

👉 Sau khi hoàn tất bước này, Google Cloud Auth Manager của bạn hiện đã được định cấu hình đầy đủ bằng thông tin đăng nhập của ứng dụng GitHub OAuth, thiết lập Google Cloud để hoạt động như một kho lưu trữ an toàn, xử lý vòng đời của sự đồng ý và mã thông báo.

5. Chuyển mã thông báo PAT sang Trình quản lý uỷ quyền

Sau khi bạn định cấu hình hoàn toàn Trình quản lý uỷ quyền, bước tiếp theo là cập nhật mã công cụ của tác nhân. Thay thế app/tools.py bằng đoạn mã sau.

👉 Thay thế mã dự án và vị trí trong biến OAUTH_PROVIDER_NAME bên dưới.

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

Tìm hiểu về mã công cụ

Thay đổi quan trọng là auth_scheme. Việc đính kèm mã thông báo này vào bộ công cụ có nghĩa là bất cứ khi nào tác nhân gọi GitHub, ADK sẽ yêu cầu Auth Manager cung cấp mã thông báo của người dùng đó trước tiên. Nếu chưa có mã thông báo, thì ADK sẽ nhắc người dùng đăng nhập thay vì thất bại. GITHUB_TOKEN được mã hoá cứng đã hoàn toàn biến mất.

6. Triển khai Tác nhân cho Thời gian chạy tác nhân

Giờ đây, chúng ta đã cập nhật công cụ MCP của GitHub để sử dụng Trình quản lý xác thực, bước tiếp theo là triển khai tác nhân đến Thời gian chạy tác nhân. Việc triển khai với tính năng Danh tính của tác nhân được bật sẽ cung cấp một mã nhận dạng SPIFFE duy nhất cho tác nhân.

Hãy bắt đầu bằng cách khởi tạo cấu hình triển khai cho dự án. Chạy trong thiết bị đầu cuối:

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

Lệnh này kiểm tra cấu trúc dự án của bạn để đảm bảo khả năng tương thích với ADK, chuẩn bị các cấu hình đóng gói vùng chứa cơ bản và tạo một tệp agents-cli-manifest.yaml trong thư mục gốc của dự án được điền sẵn các chế độ cài đặt triển khai mặc định.

👉 Mở tệp agents-cli-manifest.yaml mới tạo và xác minh hoặc cập nhật trường region thành us-central1 để đảm bảo nhân viên hỗ trợ được triển khai ở cùng khu vực với nhà cung cấp dịch vụ uỷ quyền:

region: "us-central1"

Triển khai Tác nhân bằng Danh tính của tác nhân

Triển khai bằng adk deploy agent_engine. Thao tác này cung cấp cho tác nhân Danh tính tác nhân riêng – một danh tính mật mã duy nhất, được SPIFFE hỗ trợ, thuộc về quy trình triển khai này. Tác nhân sử dụng danh tính này để xác thực với Trình quản lý uỷ quyền và các dịch vụ khác của Google Cloud.

👉 Thay thế YOUR_PROJECT_ID trước khi chạy các lệnh này:

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

Quá trình triển khai mất vài phút để tạo và tải vùng chứa lên. Sau khi hoàn tất, CLI sẽ in tên tài nguyên đã triển khai. Ghi lại giá trị reasoningEngines/ENGINE_ID vì bạn cần giá trị này để uỷ quyền cho tác nhân và trỏ ứng dụng khách giao diện người dùng đến giá trị này.

Uỷ quyền cho danh tính của tác nhân

Giờ đây, khi đang chạy trên đám mây, tác nhân của bạn cần có quyền truy cập vào thông tin đăng nhập được lưu trữ trong Auth Manager. Theo mặc định, danh tính SPIFFE của tác nhân không có quyền truy cập vào các tài nguyên đám mây bên ngoài.

Chạy lệnh gcloud sau đây để cấp vai trò roles/agentidentity.user cho danh tính của tác nhân trên tài nguyên nhà cung cấp dịch vụ uỷ quyền. Điều này cấp cho tác nhân của bạn chính xác những quyền cần thiết để yêu cầu mã thông báo người dùng từ kho lưu trữ và không có quyền nào khác.

👉 Thay thế YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER và YOUR_ENGINE_ID (mã nhận dạng công cụ nằm trong đầu ra triển khai ở trên).

Để lấy YOUR_ORG_ID, hãy chạy lệnh bên dưới:

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"

Giờ đây, hãy cấp cho tài khoản của riêng bạn cùng vai trò đó trên nhà cung cấp. Ứng dụng giao diện người dùng mà bạn chạy trong bước tiếp theo sẽ gọi API hoàn tất thông tin xác thực bằng Thông tin xác thực mặc định của ứng dụng, vì vậy, nếu không có thông tin này, quy trình đồng ý sẽ thất bại với mã 403 trên 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. Tìm hiểu về Quy trình xác nhận sự đồng ý của bên thứ ba

Giờ đây, khi tác nhân được triển khai đến Thời gian chạy tác nhân bằng Danh tính tác nhân bảo mật, bước tiếp theo là cung cấp một giao diện người dùng tuỳ chỉnh để người dùng trò chuyện với tác nhân. Quan trọng hơn, Google Cloud Auth Manager yêu cầu trình xử lý gọi lại ứng dụng khách để hoàn tất vòng lặp xác thực.

Mặc dù Google Cloud Auth Manager quản lý thông tin đăng nhập của người dùng một cách an toàn trong một kho lưu trữ, nhưng bản thân công cụ này không thể hoàn tất quá trình trao đổi mã thông báo OAuth. Cơ chế bắt tay 3LO dựa vào ứng dụng khách để thu hẹp khoảng cách:

Khi người dùng uỷ quyền cho ứng dụng GitHub, GitHub sẽ chuyển hướng họ trở lại redirectUrl của trình cung cấp dịch vụ xác thực Danh tính của tác nhân.
Sau đó, Auth Manager sẽ chuyển hướng cửa sổ bật lên của trình duyệt người dùng trở lại URL gọi lại phía máy khách (continue_uri).
Ứng dụng khách có trách nhiệm chặn lệnh chuyển hướng này, đọc số chỉ dùng một lần từ cookie của trình duyệt và gọi điểm cuối credentials:finalize của Google Cloud để hoàn tất quy trình bắt tay.
Sau khi ứng dụng hoàn tất quá trình trao đổi, Google Cloud sẽ lưu mã thông báo một cách an toàn trong kho lưu trữ của nhà cung cấp dịch vụ uỷ quyền, cho phép tác nhân gọi công cụ GitHub.

Nếu không có máy khách tuỳ chỉnh này lưu trữ điểm cuối gọi lại, quy trình bắt tay sẽ không hoàn tất và kho lưu trữ không thể lưu trữ thông tin đăng nhập.

Quy trình OAuth 3LO tương tác trải rộng trên nhiều lớp. Sau đây là vòng đời thực thi đầy đủ của một yêu cầu về công cụ. Chúng tôi sẽ giải thích chi tiết hơn về vấn đề này ở phần dưới đây và trong bước tiếp theo.

👉 Nhấp vào hình ảnh để phóng to.

Trách nhiệm chính của Khách hàng trong thoả thuận bắt tay

Chuyển tiếp yêu cầu đồng ý (Các bước 5-6): tác nhân phát ra một adk_request_credential mang theo URL đồng ý và số chỉ dùng một lần; ứng dụng mở cửa sổ bật lên và lưu trữ số chỉ dùng một lần dưới dạng cookie.
Lưu trữ lệnh gọi lại chuyển hướng (Bước 10 – 11): /validateUserId, trong đó Trình quản lý uỷ quyền sẽ gửi cửa sổ bật lên sau khi có sự đồng ý.
Hoàn tất mã thông báo (Các bước 12-14): kết hợp trạng thái xác thực từ lệnh chuyển hướng với số chỉ dùng một lần đã lưu vào bộ nhớ đệm và gọi credentials:finalize, thao tác này sẽ lưu trữ mã thông báo trong kho lưu trữ.

Xây dựng ứng dụng khách của riêng bạn

Bạn không cần viết ứng dụng này cho phòng thí nghiệm – bước tiếp theo sẽ chạy một ứng dụng được tạo sẵn. Khi bạn triển khai việc này trong ứng dụng của riêng mình, đây là 2 thông tin tham khảo để bạn có thể tham khảo:

Cập nhật ứng dụng phía máy khách trong tài liệu Auth Manager, trong đó đề cập đến việc xử lý yêu cầu đồng ý và gọi credentials:finalize.
Ứng dụng mẫu có thể chạy trong kho lưu trữ adk-python. Đọc main.py ở đó để biết cách triển khai đầy đủ và hiệu quả 3 trách nhiệm nêu trên.

8. Chạy ứng dụng giao diện người dùng cục bộ

Như chúng ta đã theo dõi trong sơ đồ trình tự Quy trình đồng ý 3LO, Auth Manager cần chuyển hướng cửa sổ bật lên của trình duyệt trở lại điểm cuối gọi lại phía máy khách. Ứng dụng mẫu lưu trữ điểm cuối đó tại /validateUserId. Hãy chạy ứng dụng này trên thiết bị của bạn.

Sao chép tệp ứng dụng vào Local

Chuyển đến thư mục gcp_auth/client trong kho lưu trữ GitHub adk-python. Thư mục này chứa các thành phần cần thiết để tạo vùng chứa ứng dụng trò chuyện.

👉 Sao chép tất cả các tệp trong gcp_auth/client vào môi trường cục bộ:

main.py: Tập lệnh ứng dụng FastAPI chứa lệnh gọi lại hoàn tất mã thông báo (/validateUserId) mà chúng ta đã thảo luận trong phần trước.
static/: Chứa các trang HTML.

Ngoài ra, bạn cũng có thể thực hiện thao tác kiểm xuất thưa cho thư mục:

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

Chạy ứng dụng

Chuyển đến thư mục client mà bạn vừa sao chép:

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

Tạo một môi trường ảo và cài đặt các phần phụ thuộc của ứng dụng. Thư mục này có requirements.txt và không có pyproject.toml, nên uv run uvicorn ... sẽ không thành công với Failed to spawn: uvicorn:
```
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install --python .venv/bin/python -r requirements.txt
```

Trỏ máy khách đến tác nhân mà bạn đã triển khai, sau đó khởi động tác nhân trên cổng 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

Xác minh rằng máy chủ đã khởi động thành công và đang lắng nghe trên http://localhost:8501.

9. Kiểm thử quy trình OAuth

Giờ đây, khi tất cả các dịch vụ đã được triển khai, các liên kết IAM đã được định cấu hình và các biến môi trường đã được thiết lập, bạn đã sẵn sàng kiểm thử quy trình uỷ quyền an toàn từ đầu đến cuối do người dùng uỷ quyền!

Bước A: Bắt đầu thực thi công cụ

Mở một thẻ trình duyệt rồi chuyển đến URL của ứng dụng khách: http://localhost:8501.
Trong ngăn bên trái, hãy đặt Loại tác nhân thành Remote Agent Engine.
Nhập Dự án và Vị trí của bạn trên Google Cloud. Nhấp vào Load Remote Agents. Thao tác này sẽ tải tất cả các tác nhân được triển khai vào dự án của bạn.
Chọn đúng nhân viên trong trình đơn thả xuống rồi lưu chế độ cài đặt.

Trong hộp trò chuyện, hãy nhập:

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

rồi nhấn phím Enter.

Quan sát giao diện người dùng trò chuyện: Vì chưa có thông tin đăng nhập cho phiên người dùng của bạn, nên tác nhân sẽ nhận được một yêu cầu xác thực và hiển thị thẻ Cần xác thực trong chuỗi hội thoại.

Một cửa sổ bật lên riêng biệt của trình duyệt sẽ mở ra, chuyển hướng bạn thông qua Trình quản lý xác thực của Google Cloud đến trang ủy quyền OAuth của GitHub.
Xem xét các quyền được yêu cầu rồi nhấp vào Uỷ quyền.
GitHub sẽ chuyển hướng trở lại Google Cloud, sau đó chuyển hướng cửa sổ bật lên đến localhost URL gọi lại /validateUserId của bạn.
Dịch vụ gọi lại sẽ xử lý và hoàn tất quy trình bắt tay về thông tin đăng nhập.

Bước C: Tiếp tục

Sau khi cửa sổ bật lên đóng, thẻ trò chuyện của cha mẹ sẽ tự động phát hiện việc đóng này.
Giao diện người dùng gửi tải trọng tiếp tục trở lại tác nhân.
Tác nhân này sẽ truy xuất mã thông báo mới được trao đổi một cách an toàn từ Trình quản lý uỷ quyền của Google Cloud, gọi các công cụ MCP của GitHub thay cho bạn và truyền trực tiếp dữ liệu từ kho lưu trữ riêng tư của bạn trở lại cửa sổ trò chuyện – dữ liệu mà tác nhân không thể tự truy cập.

Bước D: Kiểm tra nhật ký trên đám mây

Cách xác minh rằng quá trình trao đổi và hoàn tất mã thông báo đã được xử lý một cách an toàn:

Chuyển đến Trình khám phá nhật ký của Google Cloud Console.

Tìm nhật ký máy chủ xác nhận việc trích xuất số chỉ dùng một lần và xác thực thành công:

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

Kiểm tra nhật ký thời gian chạy của tác nhân: Ngoài ra, bạn có thể xem nhật ký thực thi ngay trong Bảng điều khiển nền tảng tác nhân:
- Chuyển đến Agent Runtime Console.
- Nhấp vào tác nhân đã triển khai trong danh sách.
- Chuyển sang thẻ Playground (Sân chơi). Thẻ này sẽ hiển thị nhật ký của tác nhân trực tiếp ở ngăn dưới cùng, cho bạn thấy vòng lặp suy luận của tác nhân, thông tin chi tiết về việc thực thi công cụ và vòng đời truy xuất mã thông báo theo thời gian thực.

10. Dọn dẹp

Để tránh bị tính phí liên tục trên Google Cloud, hãy dọn dẹp các tài nguyên đã triển khai:

# 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

Dọn dẹp tệp trên thiết bị

Nếu muốn, bạn có thể dọn dẹp hoàn toàn môi trường cục bộ bằng cách:

Dừng máy chủ uvicorn cục bộ bằng cách nhấn tổ hợp phím Ctrl+C trong thiết bị đầu cuối đang chạy máy chủ đó.
Xoá các thư mục dự án đã tạo trong phòng thí nghiệm này:

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

11. Xin chúc mừng!

Bạn đã tạo và bảo mật thành công một tác nhân thay mặt cho người dùng đã đăng nhập!

Kiến thức bạn học được:

Danh tính hệ thống của tác nhân: Cách tác nhân hoạt động theo danh tính Tài khoản riêng để tương tác an toàn với cơ sở hạ tầng GCP, quản lý nhật ký đo từ xa và gọi các API hoàn tất thông tin đăng nhập.
Danh tính được uỷ quyền của người dùng: Cách tác nhân yêu cầu uỷ quyền thay mặt người dùng hành động trên các nền tảng bên ngoài (chẳng hạn như GitHub) bằng cách kích hoạt quy trình đồng ý OAuth 3 chân (3LO).
Tích hợp công cụ an toàn: Cách kết nối các Tác nhân ADK với máy chủ Giao thức ngữ cảnh mô hình (MCP) bằng Trình quản lý xác thực của Google Cloud để tìm nạp mã thông báo người dùng một cách linh động thay vì sử dụng các thông tin bí mật được mã hoá cứng.
Cấu hình chính sách IAM: Cách thiết lập các liên kết quyền chi tiết để uỷ quyền cho cả danh tính Thời gian chạy của tác nhân và tài khoản của riêng bạn trên nhà cung cấp dịch vụ uỷ quyền.

Tài liệu đọc thêm

Trình quản lý xác thực danh tính tác nhân để tìm hiểu cấu hình và phạm vi của quy trình xác thực.
Tổng quan về thời gian chạy của tác nhân
Tài liệu về ADK
Giao thức ngữ cảnh mô hình