สร้าง AI Agent ที่ดำเนินการในนามของผู้ใช้ด้วย Agent Identity และ Auth Manager

1. บทนำ

Agent ที่มีข้อมูลเข้าสู่ระบบของตัวเองพร้อมสิทธิ์แบบกว้างจะเห็นข้อมูลของทุกคน ในโค้ดแล็บนี้ คุณจะได้สร้างเอเจนต์ที่เรียกใช้ API ของบุคคลที่สามด้วยข้อมูลเข้าสู่ระบบของผู้ใช้ที่ลงชื่อเข้าใช้เอง เพื่อให้เอเจนต์เห็นเฉพาะสิ่งที่ผู้ใช้เห็นเท่านั้น

คุณจะสร้างโดยใช้ Google Agent Development Kit (ADK) และ Gemini Enterprise

โดยเฉพาะอย่างยิ่ง คุณจะได้เรียนรู้วิธีออกแบบสถาปัตยกรรมแบบ 2 ตัวตนในกรณีต่อไปนี้

  1. เอเจนต์ดำเนินการในนามของตนเอง (ข้อมูลประจำตัวของเอเจนต์): เอเจนต์จะเรียกใช้ Auth Manager, จัดเก็บข้อมูลการวัดและส่งข้อมูล และเรียกใช้ Google Cloud APIs โดยใช้ข้อมูลประจำตัวของเอเจนต์ที่ได้รับการสนับสนุนจาก SPIFFE
  2. เอเจนต์ดำเนินการในนามของผู้ใช้ (ข้อมูลประจำตัวที่มอบสิทธิ์โดยผู้ใช้): หากต้องการเข้าถึงแหล่งข้อมูลภายนอก เช่น GitHub เอเจนต์จะทริกเกอร์โฟลว์ความยินยอม OAuth แบบ 3 ขา (3LO) เพื่อค้นหาเครื่องมืออย่างปลอดภัยโดยใช้ข้อมูลเข้าสู่ระบบของผู้ใช้

สถาปัตยกรรมแบบ 2 อัตลักษณ์

โดยคุณจะได้เรียนรู้วิธีต่อไปนี้

  1. สร้าง Agent ADK ที่เชื่อมต่อกับเซิร์ฟเวอร์ Model Context Protocol (MCP) ของ GitHub
  2. อัปเดตเครื่องมือของตัวแทนจาก PAT (โทเค็นเพื่อการเข้าถึงส่วนบุคคล) แบบคงที่ของ GitHub เป็นโฟลว์ OAuth แบบ 3 ทาง (3LO) โดยใช้ Google Cloud Auth Manager
  3. ทำให้ Agent ใช้งานได้อย่างปลอดภัยใน Agent Runtime และจัดสรร Agent Identity
  4. กำหนดค่าบทบาท IAM เพื่อให้สิทธิ์เข้าถึงข้อมูลประจำตัวของเอเจนต์ไปยังที่เก็บโทเค็นในนามของผู้ใช้
  5. ทำความเข้าใจโฟลว์ 3LO แบบครบวงจรสำหรับ Auth Manager ใน Google Cloud

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น โปรดตรวจสอบว่าคุณมีสิ่งต่อไปนี้

  • โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
  • Google Cloud SDK (gcloud CLI) ติดตั้งและตรวจสอบสิทธิ์ในโปรเจ็กต์ในเครื่องของคุณ ต้องใช้เวอร์ชัน 586.0.0 ขึ้นไป — เรียกใช้ gcloud components update
  • ติดตั้ง Python 3.10 ถึง 3.13 ในเครื่อง
  • ติดตั้งuvเครื่องมือจัดการแพ็กเกจ (pip install uv)
  • บัญชี GitHub เพื่อลงทะเบียนแอปพลิเคชัน OAuth และสร้างโทเค็น หากไม่มีบัญชี GitHub คุณสามารถใช้เซิร์ฟเวอร์ MCP ของบุคคลที่สามที่รองรับ OAuth 2.0 แบบ 3 ขาแทนได้

2. การตั้งค่าโปรเจ็กต์

1. ตรวจสอบสิทธิ์ไปยัง Google Cloud

ตรวจสอบสิทธิ์ไปยัง Google Cloud จากบรรทัดคำสั่งในเครื่องเพื่อให้แน่ใจว่าสภาพแวดล้อมของคุณมีสิทธิ์ที่จำเป็นในการติดตั้งใช้งาน Agent Runtime จัดสรรข้อมูลประจำตัวของ Agent และกำหนดค่า Auth Manager ในระหว่างแล็บนี้

เรียกใช้คำสั่งต่อไปนี้เพื่อเข้าสู่ระบบบัญชี Google Cloud เพื่อกำหนดค่าข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน (ADC)

gcloud auth login
gcloud auth application-default login

2. เปิดใช้บริการ Google Cloud ที่จำเป็น

เปิดใช้ API ที่จำเป็นในโปรเจ็กต์ Google Cloud เพื่อเรียกใช้ Lab นี้ เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัล

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

คำสั่งนี้อาจใช้เวลา 1 นาทีในการดำเนินการ เมื่อเสร็จแล้ว ระบบจะกลับไปที่ Command Prompt เพื่อยืนยันว่า API ใช้งานได้

3. ติดตั้ง CLI ของ Agent และตั้งค่าโปรเจ็กต์

agents-cli เป็นเครื่องมือบรรทัดคำสั่งที่ใช้ในการจัดโครงสร้าง จัดการ ทดสอบ และติดตั้งใช้งาน Agent ของ ADK ใน Gemini Enterprise ติดตั้งในเครื่อง

uvx google-agents-cli setup

ตรวจสอบการติดตั้ง

agents-cli --help

คุณควรเห็นเมนูความช่วยเหลือของ CLI ที่แสดงคำสั่งที่ใช้ได้ (เช่น deploy, run และ status)

สร้างโครงร่างเริ่มต้นของโปรเจ็กต์ คุณจะเริ่มต้นด้วยต้นแบบในเครื่องและปรับปรุงในภายหลังเพื่อการติดตั้งใช้งาน Agent Runtime โดยทำดังนี้

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

ซึ่งจะสร้างไดเรกทอรี secure-agent-demo ที่มีโค้ดเอเจนต์พื้นฐาน การอ้างอิง และไฟล์ทดสอบ

4. เพิ่มส่วนเสริม ADK ที่จำเป็น

pyproject.toml ที่สร้างขึ้นgoogle-adk[gcp,otel-gcp]ไม่มีส่วนเสริม 2 รายการที่ Agent นี้ต้องการ ได้แก่ mcp สำหรับชุดเครื่องมือ GitHub และ agent-identity สำหรับ Auth Manager ในภายหลังในห้องทดลอง เปิด secure-agent-demo/pyproject.toml แล้วเปลี่ยนบรรทัด google-adk เป็น

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

จากนั้นให้ติดตั้งโดยทำดังนี้

cd secure-agent-demo
agents-cli install

3. สร้างและทดสอบ Agent

1. สร้างเอเจนต์

ในโปรเจ็กต์ ให้แทนที่โค้ดในไฟล์ agent.py ด้วยโค้ดต่อไปนี้

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

ไฟล์นี้กำหนดองค์ประกอบสำคัญ 3 อย่างของเอเจนต์ ได้แก่

  • คำสั่งของระบบ (INSTRUCTION): กำหนดลักษณะตัวตน ขอบเขตผู้ช่วยในการจัดลำดับความสำคัญของ GitHub และบังคับใช้กฎความปลอดภัยที่เข้มงวด (เช่น สิทธิ์เข้าถึงแบบอ่านอย่างเดียว และแนะนำให้ผู้ใช้ตรวจสอบสิทธิ์หากเกิดข้อผิดพลาด)
  • การกำหนดค่าเอเจนต์ (root_agent): สร้างอินสแตนซ์ ADK Agent โดยใช้โมเดล gemini-3.8-flash กำหนดค่าตรรกะการลองใหม่ของ HTTP และติดตั้งชุดเครื่องมือ GitHub ให้กับเอเจนต์
  • App Wrapper (app): ห่อหุ้มเอเจนต์รูทไว้ในคอนเทนเนอร์ ADK App เพื่อให้สามารถนำไปใช้กับ Agent Runtime ได้

2. เพิ่มเครื่องมือ MCP ของ GitHub

เอเจนต์เชื่อมต่อกับ GitHub ผ่าน Model Context Protocol (MCP) สร้างไฟล์ใหม่ชื่อ tools.py ในโฟลเดอร์ app/ เพื่อลงทะเบียนพารามิเตอร์การเชื่อมต่อเกตเวย์ MCP คัดลอกและวางโค้ดต่อไปนี้

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

ฟังก์ชันนี้จะสร้างเครื่องมือที่เรียกเซิร์ฟเวอร์ MCP ของ GitHub ดังนี้

  • ชุดเครื่องมือ MCP (McpToolset): ค้นพบและลงทะเบียนความสามารถของ GitHub แบบไดนามิกเป็นเครื่องมือเอเจนต์ที่เรียกใช้ได้
  • พารามิเตอร์การเชื่อมต่อ (StreamableHTTPConnectionParams): ชี้ชุดเครื่องมือไปยังเกตเวย์ MCP สาธารณะของ GitHub
  • ส่วนหัวการให้สิทธิ์: แทรก GITHUB_TOKEN เป็นโทเค็น Bearer และบังคับใช้โหมดอ่านอย่างเดียว (X-MCP-Readonly: true) ที่เลเยอร์การขนส่งโดยตรง

3. ทดสอบในเครื่องด้วย PAT (โทเค็นการเข้าถึงส่วนบุคคล) ของ GitHub

วิธีเรียกใช้เอเจนต์ในเครื่องด้วยข้อมูลเข้าสู่ระบบแบบคงที่

  1. สร้างโทเค็นเพื่อการเข้าถึงส่วนบุคคลของ GitHub ให้สิทธิ์อ่านแก่ที่เก็บของคุณ มิฉะนั้นเอเจนต์จะเห็นได้เฉพาะข้อมูลสาธารณะและพรอมต์ด้านล่างจะไม่แสดงผลใดๆ
  2. ตั้งค่าในสภาพแวดล้อมของคุณ 
    export GITHUB_TOKEN="your_github_pat_here"
  3. ไปที่โฟลเดอร์ secure-agent-demo วิ่ง 
    cd secure-agent-demo
agents-cli playground
  4. เปิดอินเทอร์เฟซ Playground แล้วเลือกโฟลเดอร์ "app" จากเมนูแบบเลื่อนลง ในแชทบ็อกซ์ ให้พิมพ์ "Fetch my contributions across my private repositories over the last 6 months" แล้วตรวจสอบว่าเอเจนต์เรียกใช้เครื่องมือ GitHub และส่งคืนข้อมูลจากที่เก็บส่วนตัว

4. กำหนดค่า Auth Manager

แม้ว่าการฮาร์ดโค้ดข้อมูลเข้าสู่ระบบแบบคงที่ (เช่น PAT) จะสะดวกสำหรับการสร้างต้นแบบ แต่ก็ทำให้แอปพลิเคชันเวอร์ชันที่ใช้งานจริงเสี่ยงต่อการรั่วไหลของข้อมูลเข้าสู่ระบบ เวลาหยุดทำงานในการรีเฟรชโทเค็นด้วยตนเอง และการขาดการควบคุมการเข้าถึงแบบ Cloud-Native

Google Cloud มี Agent Identity Auth Manager เพื่อแก้ปัญหานี้ Agent Identity Auth Manager คือห้องเก็บข้อมูลเข้าสู่ระบบที่ออกแบบมาเพื่อช่วยปกป้องข้อมูลเข้าสู่ระบบ ซึ่งช่วยให้ตัวแทนตรวจสอบสิทธิ์ได้โดยใช้คีย์ API หรือรหัสไคลเอ็นต์และรหัสลับ OAuth หรือในนามของผู้ใช้ผ่านการมอบสิทธิ์ OAuth โดยใช้โทเค็นการเข้าถึงของผู้ใช้ปลายทาง

ใน Auth Manager คุณจะกำหนดค่าผู้ให้บริการการตรวจสอบสิทธิ์ที่กำหนดประเภทการตรวจสอบสิทธิ์และข้อมูลเข้าสู่ระบบสำหรับแอปพลิเคชันของบุคคลที่สามที่เฉพาะเจาะจง ผู้ให้บริการการตรวจสอบสิทธิ์เป็นระดับภูมิภาค และภูมิภาคต้องตรงกับภูมิภาคที่คุณติดตั้งใช้งาน Agent เวิร์กโฟลว์ Auth Manager แบบครบวงจรทํางานดังนี้

เวิร์กโฟลว์ของ Auth Manager

  1. การสกัดกั้นความยินยอมแบบไดนามิก: เมื่อเอเจนต์พยายามเรียกใช้เครื่องมือในนามของผู้ใช้ ADK จะตรวจสอบ Auth Manager เพื่อหาข้อมูลเข้าสู่ระบบที่ถูกต้องที่มีอยู่ หากไม่มี Auth Manager จะแสดง URL การให้สิทธิ์เพื่อเริ่มขั้นตอนความยินยอมแบบ OAuth 3 ขา (3LO)
  2. ที่เก็บห้องนิรภัยที่ปลอดภัย: เมื่อผู้ใช้ปลายทางให้สิทธิ์แอปพลิเคชันแล้ว Auth Manager จะสกัดกั้นการเรียกกลับของ OAuth โดยอัตโนมัติ และจัดเก็บโทเค็นการเข้าถึงและการรีเฟรชของผู้ใช้ที่ได้ในห้องนิรภัยสำหรับข้อมูลเข้าสู่ระบบที่ปลอดภัยซึ่ง Google จัดการ
  3. วงจรโทเค็นอัตโนมัติ: Auth Manager จะจัดการการหมดอายุและการหมุนเวียนโทเค็นอย่างเต็มรูปแบบในเบื้องหลัง จึงไม่จำเป็นต้องมีตรรกะการรีเฟรชโทเค็นด้วยตนเองหรือช่วงหยุดทำงาน
  4. การดำเนินการเครื่องมือแบบไม่มีรหัสลับ: สำหรับการดำเนินการในภายหลัง เอเจนต์ (ตรวจสอบสิทธิ์ผ่านข้อมูลประจำตัวของ SPIFFE Agent) จะขอโทเค็นเพื่อการเข้าถึงที่ได้รับมอบหมายของผู้ใช้จาก Auth Manager แบบไดนามิกในขณะรันไทม์ ซึ่งจะทำให้ทั้งโค้ดไคลเอ็นต์และโค้ดเอเจนต์ไม่มีรหัสลับโดยสมบูรณ์

ขั้นตอนที่ ก: กำหนดค่า GitHub เป็นผู้ให้บริการการตรวจสอบสิทธิ์

เรียกใช้gcloudคำสั่งต่อไปนี้เพื่อสร้างผู้ให้บริการการตรวจสอบสิทธิ์ GitHub ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google คุณจะระบุรหัสไคลเอ็นต์และรหัสลับในภายหลังได้ GitHub จะไม่สร้างรหัสเหล่านี้จนกว่าจะทราบ URL เรียกกลับของผู้ให้บริการรายนี้

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"

อธิบายผู้ให้บริการเพื่อดึง URL เปลี่ยนเส้นทาง OAuth ที่สร้างขึ้น

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

ฟิลด์คือ redirectUrl ซึ่งซ้อนอยู่ภายใต้ authProviderTypeParams.threeLeggedOauth หากต้องการอ่านโดยตรง ให้ทำดังนี้

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

ดูเหมือนว่า https://agentidentitycredentials.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/authProviders/github-oauth-provider/oauthcallback

ขั้นตอนที่ ข: ลงทะเบียนแอป OAuth ใน GitHub

  1. ไปที่หน้าการตั้งค่าสำหรับนักพัฒนาซอฟต์แวร์ของ GitHub แล้วคลิกลงทะเบียนแอป OAuth ใหม่
  2. สำหรับ URL ของหน้าแรก ให้ป้อน URL ของแอปพลิเคชันฟรอนท์เอนด์ (เช่น http://localhost:8501 สำหรับการสร้างต้นแบบในเครื่อง) คุณสามารถเปลี่ยนเป็น URL ที่ใช้งานจริงในภายหลังได้
  3. ตั้งค่า URI การเปลี่ยนเส้นทางเป็น redirectUrl ที่ดึงข้อมูลมาในขั้นตอนก่อนหน้า
  4. คลิกลงทะเบียนแอปพลิเคชัน จากนั้นคลิกสร้างรหัสลับไคลเอ็นต์ใหม่ แล้วบันทึกทั้งรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์

ขั้นตอนที่ ค: เพิ่มข้อมูลเข้าสู่ระบบ GitHub ลงในผู้ให้บริการการตรวจสอบสิทธิ์

แทนที่รหัสโปรเจ็กต์ รหัสไคลเอ็นต์ และรหัสลับไคลเอ็นต์ แล้วเรียกใช้คำสั่งนี้

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"

คำสั่งจะส่งกลับไปยังผู้ให้บริการพร้อมกับ clientId ที่มองเห็นได้ แต่จะไม่ส่งกลับความลับ

👉 เมื่อทำขั้นตอนนี้เสร็จแล้ว Google Cloud Auth Manager จะได้รับการกำหนดค่าอย่างเต็มรูปแบบด้วยข้อมูลเข้าสู่ระบบของแอปพลิเคชัน GitHub OAuth ซึ่งจะตั้งค่า Google Cloud ให้ทำหน้าที่เป็นที่เก็บข้อมูลที่ปลอดภัยซึ่งจัดการวงจรความยินยอมและโทเค็น

5. เปลี่ยนโทเค็น PAT เป็น Auth Manager

เมื่อกำหนดค่า Auth Manager เสร็จสมบูรณ์แล้ว ขั้นตอนถัดไปคือการอัปเดตโค้ดเครื่องมือของตัวแทน แทนที่ app/tools.py ด้วยโค้ดต่อไปนี้

👉 แทนที่รหัสโปรเจ็กต์และสถานที่ตั้งในตัวแปร OAUTH_PROVIDER_NAME ด้านล่าง

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

ทำความเข้าใจโค้ดเครื่องมือ

การเปลี่ยนแปลงที่สำคัญคือ auth_scheme การแนบโทเค็นกับชุดเครื่องมือหมายความว่าเมื่อใดก็ตามที่ตัวแทนเรียกใช้ GitHub ทาง ADK จะขอโทเค็นของผู้ใช้จาก Auth Manager ก่อน และหากยังไม่มีโทเค็น ระบบจะแจ้งให้ผู้ใช้ลงชื่อเข้าใช้แทนที่จะล้มเหลว GITHUB_TOKEN ที่ฮาร์ดโค้ดจะหายไปโดยสิ้นเชิง

6. ทำให้ Agent ใช้งานได้กับ Agent Runtime

ตอนนี้เราได้อัปเดตเครื่องมือ MCP ของ GitHub ให้ใช้ Auth Manager แทนแล้ว ขั้นตอนถัดไปคือการติดตั้งใช้งานเอเจนต์ในAgent Runtime การติดตั้งใช้งานโดยเปิดใช้ข้อมูลระบุตัวตนของ Agent จะจัดสรร SPIFFE ID ที่ไม่ซ้ำกันสำหรับ Agent

มาเริ่มด้วยการเริ่มต้นการกำหนดค่าการติดตั้งใช้งานสำหรับโปรเจ็กต์กัน เรียกใช้ในเทอร์มินัล

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

คำสั่งนี้จะตรวจสอบโครงสร้างโปรเจ็กต์ของคุณเพื่อดูความเข้ากันได้ของ ADK เตรียมการกำหนดค่าการแพ็กเกจคอนเทนเนอร์พื้นฐาน และสร้างไฟล์ agents-cli-manifest.yaml ในรูทของโปรเจ็กต์ที่กำหนดค่าการติดตั้งใช้งานเริ่มต้นไว้ล่วงหน้า

👉 เปิดagents-cli-manifest.yamlไฟล์ที่สร้างขึ้นใหม่ แล้วยืนยันหรืออัปเดตฟิลด์ region เป็น us-central1 เพื่อให้แน่ใจว่าได้ติดตั้งใช้งานตัวแทนในภูมิภาคเดียวกับผู้ให้บริการตรวจสอบสิทธิ์

region: "us-central1"

ติดตั้งใช้งาน Agent ด้วยข้อมูลระบุตัวตนของ Agent

ทําให้ใช้งานได้ด้วย adk deploy agent_engine ซึ่งจะจัดสรร Agent Identity ของตัวเองให้กับเอเจนต์ ซึ่งเป็นข้อมูลประจำตัวแบบเข้ารหัสที่ SPIFFE สนับสนุนและเป็นของ Deployment นี้ โดยเอเจนต์จะใช้เพื่อตรวจสอบสิทธิ์กับ Auth Manager และบริการอื่นๆ ของ Google Cloud

👉 แทนที่ 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"

การติดตั้งใช้งานจะใช้เวลา 2-3 นาทีในการสร้างและอัปโหลดคอนเทนเนอร์ เมื่อเสร็จแล้ว CLI จะพิมพ์ชื่อทรัพยากรที่ติดตั้งใช้งาน จดค่า reasoningEngines/ENGINE_ID ไว้ เนื่องจากคุณจะต้องใช้ค่านี้เพื่อให้สิทธิ์ตัวแทนและชี้ไคลเอ็นต์ UI ไปยังค่าดังกล่าว

ให้สิทธิ์ข้อมูลระบุตัวตนของ Agent

เมื่อเอเจนต์ทำงานในระบบคลาวด์แล้ว เอเจนต์จะต้องมีสิทธิ์เข้าถึงข้อมูลเข้าสู่ระบบที่จัดเก็บไว้ใน Auth Manager โดยค่าเริ่มต้น ข้อมูลประจำตัว SPIFFE ของ Agent จะไม่มีสิทธิ์เข้าถึงทรัพยากรระบบคลาวด์ภายนอก

เรียกใช้gcloudคำสั่งต่อไปนี้เพื่อมอบบทบาท roles/agentidentity.user ให้กับข้อมูลประจำตัวของเอเจนต์ในทรัพยากรผู้ให้บริการการตรวจสอบสิทธิ์ ซึ่งจะให้สิทธิ์ที่แน่นอนแก่เอเจนต์ในการขอโทเค็นผู้ใช้จากห้องนิรภัย และไม่มีสิทธิ์ที่กว้างกว่านั้น

👉 แทนที่ YOUR_PROJECT_ID, YOUR_ORG_ID, YOUR_PROJECT_NUMBER และ YOUR_ENGINE_ID (รหัสเครื่องมืออยู่ในเอาต์พุตการติดตั้งใช้งานด้านบน)

หากต้องการรับ YOUR_ORG_ID ให้เรียกใช้คำสั่งด้านล่าง

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"

ตอนนี้ให้บทบาทเดียวกันในผู้ให้บริการแก่บัญชีของคุณเอง ไคลเอ็นต์ UI ที่คุณเรียกใช้ในขั้นตอนถัดไปจะเรียกใช้ API การสรุปข้อมูลเข้าสู่ระบบด้วยข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน ดังนั้นหากไม่มีข้อมูลนี้ ขั้นตอนความยินยอมจะล้มเหลวโดยมีข้อผิดพลาด 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. ทำความเข้าใจขั้นตอนความยินยอมของบุคคลที่สาม

เมื่อทำให้ Agent ใช้งานได้ใน Agent Runtime ด้วยข้อมูลประจำตัวของ Agent ที่ปลอดภัยแล้ว ขั้นตอนถัดไปคือการจัดเตรียมอินเทอร์เฟซส่วนหน้าแบบกำหนดเองเพื่อให้ผู้ใช้แชทกับ Agent ได้ ที่สำคัญกว่านั้นคือ Google Cloud Auth Manager ต้องมี Callback Handler ของแอปพลิเคชันไคลเอ็นต์เพื่อดำเนินการลูปการตรวจสอบสิทธิ์ให้เสร็จสมบูรณ์

แม้ว่า Google Cloud Auth Manager จะจัดการข้อมูลเข้าสู่ระบบของผู้ใช้ภายในห้องนิรภัยอย่างปลอดภัย แต่ก็ไม่สามารถทำการแลกเปลี่ยนโทเค็น OAuth ให้เสร็จสมบูรณ์ได้ด้วยตัวเอง การแฮนด์เชค 3LO อาศัยแอปพลิเคชันไคลเอ็นต์เพื่อเชื่อมช่องว่าง

  1. เมื่อผู้ใช้ให้สิทธิ์แอป GitHub แล้ว GitHub จะเปลี่ยนเส้นทางผู้ใช้กลับไปยัง redirectUrl ของผู้ให้บริการตรวจสอบสิทธิ์ข้อมูลประจำตัวของ Agent
  2. จากนั้น Auth Manager จะเปลี่ยนเส้นทางป๊อปอัปของเบราว์เซอร์ของผู้ใช้กลับไปยัง URL ของ Callback ฝั่งไคลเอ็นต์ (continue_uri)
  3. แอปพลิเคชันไคลเอ็นต์มีหน้าที่สกัดกั้นการเปลี่ยนเส้นทางนี้ อ่าน Nonce จากคุกกี้ของเบราว์เซอร์ และเรียกใช้credentials:finalizeปลายทางของ Google Cloud เพื่อทำการแฮนด์เชคให้เสร็จสมบูรณ์
  4. เมื่อไคลเอ็นต์สรุปการแลกเปลี่ยนแล้ว Google Cloud จะบันทึกโทเค็นอย่างปลอดภัยในห้องนิรภัยของผู้ให้บริการตรวจสอบสิทธิ์ ซึ่งจะช่วยให้ตัวแทนเรียกใช้เครื่องมือ GitHub ได้

หากไม่มีไคลเอ็นต์ที่กำหนดเองนี้ซึ่งโฮสต์ปลายทางการเรียกกลับ การแฮนด์เชคจะไม่สมบูรณ์ และห้องนิรภัยจะจัดเก็บข้อมูลเข้าสู่ระบบไม่ได้

ขั้นตอน OAuth 3LO แบบอินเทอร์แอกทีฟครอบคลุมหลายเลเยอร์ วงจรการดำเนินการทั้งหมดของคำขอเครื่องมือมีดังนี้ เราจะอธิบายเรื่องนี้ในคำอธิบายด้านล่างและในขั้นตอนถัดไป

👉 คลิกรูปภาพเพื่อขยาย

โฟลว์ลำดับ OAuth แบบ 3 ขา

ความรับผิดชอบหลักของลูกค้าในการจับมือ

  • ส่งต่อการท้าทายเรื่องความยินยอม (ขั้นตอนที่ 5-6): เอเจนต์จะส่ง adk_request_credential ที่มี URL ความยินยอมและ Nonce แบบใช้ครั้งเดียว ไคลเอ็นต์จะเปิดป๊อปอัปและจัดเก็บ Nonce เป็นคุกกี้
  • โฮสต์การเรียกกลับการเปลี่ยนเส้นทาง (ขั้นตอนที่ 10-11): /validateUserId ซึ่ง Auth Manager จะส่งป๊อปอัปหลังจากได้รับความยินยอม
  • สร้างโทเค็นให้เสร็จสมบูรณ์ (ขั้นตอนที่ 12-14): รวมสถานะการตรวจสอบจากการเปลี่ยนเส้นทางกับ Nonce ที่แคชไว้ แล้วเรียกใช้ credentials:finalize ซึ่งจะจัดเก็บโทเค็นไว้ใน Vault

การสร้างไคลเอ็นต์ของคุณเอง

คุณไม่จำเป็นต้องเขียนไคลเอ็นต์นี้สำหรับแล็บ เนื่องจากขั้นตอนถัดไปจะเรียกใช้ไคลเอ็นต์ที่สร้างไว้ล่วงหน้า เมื่อคุณจะนำไปใช้ในแอปพลิเคชันของคุณเอง คุณสามารถใช้ข้อมูลอ้างอิง 2 รายการต่อไปนี้

8. เรียกใช้ไคลเอ็นต์ UI ในเครื่อง

ดังที่เราได้ติดตามในแผนภาพลำดับโฟลว์ความยินยอม 3LO Auth Manager ต้องเปลี่ยนเส้นทางป๊อปอัปของเบราว์เซอร์กลับไปยังปลายทางการเรียกกลับฝั่งไคลเอ็นต์ ไคลเอ็นต์ตัวอย่างโฮสต์ปลายทางนั้นที่ /validateUserId มาเรียกใช้ในเครื่องกัน

คัดลอกไฟล์ไคลเอ็นต์ไปยัง Local

ไปที่โฟลเดอร์ gcp_auth/client ในที่เก็บ GitHub ของ adk-python โฟลเดอร์นี้มีชิ้นงานที่จำเป็นต่อการสร้างคอนเทนเนอร์ไคลเอ็นต์แชท

👉 คัดลอกไฟล์ทั้งหมดใน gcp_auth/client ไปยังสภาพแวดล้อมในเครื่อง

  • main.py: สคริปต์แอปพลิเคชัน FastAPI ที่มีโค้ดเรียกกลับการสรุปโทเค็น (/validateUserId) ที่เราพูดถึงในส่วนก่อนหน้า
  • static/: มีหน้า HTML

หรือจะทำการชำระเงินแบบกระจัดกระจายของโฟลเดอร์ก็ได้

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

เรียกใช้ไคลเอ็นต์

  1. ไปที่โฟลเดอร์ client ที่คุณเพิ่งคัดลอก 
    cd adk-python/contributing/samples/integrations/gcp_auth/client
  2. สร้างสภาพแวดล้อมเสมือนและติดตั้งการอ้างอิงของไคลเอ็นต์ โฟลเดอร์จะส่ง requirements.txt และไม่มี pyproject.toml ดังนั้น uv run uvicorn ... เพียงอย่างเดียวจึงล้มเหลวด้วย 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. ชี้ไคลเอ็นต์ไปยังเอเจนต์ที่คุณติดตั้งใช้งาน แล้วเริ่มในพอร์ต 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. ตรวจสอบว่าเซิร์ฟเวอร์เริ่มต้นเรียบร้อยแล้วและกำลังรอรับการเชื่อมต่อที่ http://localhost:8501

9. ทดสอบโฟลว์ OAuth

ตอนนี้เมื่อได้ติดตั้งใช้งานบริการทั้งหมด กำหนดค่าการเชื่อมโยง IAM และตั้งค่าตัวแปรสภาพแวดล้อมแล้ว คุณก็พร้อมที่จะทดสอบโฟลว์การให้สิทธิ์ที่ผู้ใช้มอบหมายแบบครบวงจรที่ปลอดภัยแล้ว

ขั้นตอน ก: เริ่มการดำเนินการเครื่องมือ

  1. เปิดแท็บเบราว์เซอร์แล้วไปที่ URL ของไคลเอ็นต์: http://localhost:8501
  2. ในแผงด้านซ้าย ให้ตั้งค่าประเภทเอเจนต์เป็น Remote Agent Engine
  3. พิมพ์โปรเจ็กต์ Google Cloud และสถานที่ตั้ง คลิก Load Remote Agents ซึ่งควรโหลด Agent ทั้งหมดที่ติดตั้งใช้งานในโปรเจ็กต์ของคุณ
  4. เลือกเอเจนต์ที่เหมาะสมจากเมนูแบบเลื่อนลง แล้วบันทึกการตั้งค่า
  5. พิมพ์ข้อความต่อไปนี้ในกล่องแชท 
    Fetch my contributions across my private repositories over the last 6 months
    แล้วกด Enter
  6. สังเกต UI ของแชท: เนื่องจากเอเจนต์ยังไม่มีข้อมูลเข้าสู่ระบบสำหรับเซสชันของผู้ใช้ จึงได้รับคำถามในการตรวจสอบสิทธิ์และแสดงการ์ด "ต้องมีการตรวจสอบสิทธิ์" ในเธรดการสนทนา
  1. หน้าต่างป๊อปอัปของเบราว์เซอร์แยกต่างหากจะเปิดขึ้น ซึ่งจะเปลี่ยนเส้นทางคุณผ่าน Auth Manager ของ Google Cloud ไปยังหน้าการให้สิทธิ์ OAuth ของ GitHub
  2. ตรวจสอบสิทธิ์ที่ขอ แล้วคลิกให้สิทธิ์
  3. GitHub จะเปลี่ยนเส้นทางกลับไปยัง Google Cloud ซึ่งจะเปลี่ยนเส้นทางป๊อปอัปไปยัง localhost URL เรียกกลับ /validateUserId ของคุณ
  4. บริการเรียกกลับจะประมวลผลและดำเนินการจับมือกับข้อมูลเข้าสู่ระบบให้เสร็จสมบูรณ์

ขั้นตอนที่ ค: กลับมาเป็นสมาชิก

  1. เมื่อหน้าต่างป๊อปอัปปิดลง แท็บแชทหลักจะตรวจหาการปิดโดยอัตโนมัติ
  2. ส่วนหน้าจะส่งเพย์โหลดการดำเนินการต่อกลับไปยังตัวแทน
  3. Agent จะดึงโทเค็นที่แลกเปลี่ยนใหม่จาก Google Cloud Auth Manager อย่างปลอดภัย เรียกใช้เครื่องมือ GitHub MCP ในนามของคุณ และสตรีมข้อมูลจากที่เก็บส่วนตัวกลับไปยังหน้าต่างแชทโดยตรง ซึ่งเป็นข้อมูลที่ Agent ไม่สามารถเข้าถึงได้ด้วยตนเอง

ขั้นตอนที่ ง: ตรวจสอบบันทึกของระบบคลาวด์

วิธียืนยันว่าระบบประมวลผลการแลกเปลี่ยนโทเค็นและการสรุปอย่างปลอดภัย

  1. ไปที่ Logs Explorer ในคอนโซล Google Cloud
  2. ค้นหาบันทึกเซิร์ฟเวอร์ที่ยืนยันการแยกค่า Nonce และการตรวจสอบที่สำเร็จ 
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.
  3. ตรวจสอบบันทึกรันไทม์ของ Agent: หรือจะดูบันทึกการดำเนินการใน Agent Platform Console โดยตรงก็ได้
    • ไปที่คอนโซล Agent Runtime
    • คลิกเอเจนต์ที่ใช้งานแล้วจากรายการ
    • สลับไปที่แท็บ Playground ซึ่งจะแสดงบันทึกของตัวแทนแบบเรียลไทม์ในบานหน้าต่างด้านล่าง โดยจะแสดงลูปการให้เหตุผลของตัวแทน รายละเอียดการดำเนินการเครื่องมือ และวงจรการดึงข้อมูลโทเค็นแบบเรียลไทม์

10. ล้าง

หากไม่ต้องการให้มีการเรียกเก็บเงินอย่างต่อเนื่องใน Google Cloud ให้ล้างข้อมูลทรัพยากรที่ติดตั้งใช้งานโดยทำดังนี้

# 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

ล้างไฟล์ในเครื่อง

หากต้องการล้างข้อมูลสภาพแวดล้อมในเครื่องให้หมด คุณสามารถทำดังนี้

  1. หยุดเซิร์ฟเวอร์ uvicorn ในเครื่องโดยกด Ctrl+C ในเทอร์มินัลที่เซิร์ฟเวอร์กำลังทำงานอยู่
  2. นำไดเรกทอรีโปรเจ็กต์ที่สร้างขึ้นระหว่างแล็บนี้ออก
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

11. ยินดีด้วย

คุณสร้างและรักษาความปลอดภัยของเอเจนต์ที่ดำเนินการในนามของผู้ใช้ที่ลงชื่อเข้าใช้เรียบร้อยแล้ว

สิ่งที่คุณได้เรียนรู้

  • ข้อมูลประจำตัวของระบบตัวแทน: วิธีที่ตัวแทนดำเนินการภายใต้ข้อมูลประจำตัวของบัญชีของตนเองเพื่อเชื่อมต่อกับโครงสร้างพื้นฐานของ GCP อย่างปลอดภัย จัดการบันทึกการวัดและส่งข้อมูลทางไกล และเรียกใช้ API การสรุปข้อมูลเข้าสู่ระบบ
  • ข้อมูลประจำตัวที่ได้รับมอบหมายจากผู้ใช้: วิธีที่เอเจนต์ขอสิทธิ์เพื่อดำเนินการในนามของผู้ใช้บนแพลตฟอร์มภายนอก (เช่น GitHub) โดยการเรียกใช้ขั้นตอนความยินยอม OAuth แบบ 3 ทาง (3LO)
  • การผสานรวมเครื่องมือที่ปลอดภัย: วิธีเชื่อมต่อ Agent ADK กับเซิร์ฟเวอร์ Model Context Protocol (MCP) โดยใช้ Google Cloud Auth Manager เพื่อดึงโทเค็นของผู้ใช้แบบไดนามิกแทนการใช้ข้อมูลลับที่ฮาร์ดโค้ด
  • การกำหนดค่านโยบาย IAM: วิธีตั้งค่าการเชื่อมโยงสิทธิ์แบบละเอียดเพื่อให้สิทธิ์ทั้งข้อมูลประจำตัวของ Agent Runtime และบัญชีของคุณเองในผู้ให้บริการการตรวจสอบสิทธิ์

อ่านเพิ่มเติม