ساختن «عامل هوشواره» که با «مدیر هویت و اصالت‌سنجی عامل» ازطرف کاربر عمل می‌کند

۱. مقدمه

عامل دارای اطلاعات اعتباری خود با اجازه گسترده داده‌های همه را می‌بیند. در این codelab، عاملی می‌سازید که با اطلاعات اعتباری کاربر واردشده به سیستم، یک API طرف سوم را فراخوانی می‌کند، بنابراین دقیقاً همان چیزی را می‌بیند که آن شخص می‌تواند ببیند و نه بیشتر.

آن را با Google Agent Development Kit (ADK) و Gemini Enterprise خواهید ساخت.

به‌طور خاص، با نحوه طراحی معماری هویت دوگانه آشنا خواهید شد که در آن:

  1. عامل ازطرف خود عمل می‌کند (هویت عامل): عامل بااستفاده از «هویت عامل» پشتیبانی‌شده با SPIFFE، «مدیر اصالت‌سنجی» را فرا می‌خواند، تله‌متری را ذخیره می‌کند، و «میاناهای برنامه‌سازی کاربردی Google Cloud» را فرا می‌خواند.
  2. عامل ازطرف کاربر عمل می‌کند (هویت واگذارشده کاربر): برای دسترسی به منابع خارجی مثل GitHub، عامل جریان موافقت OAuth سه‌پایه (3LO) را راه‌اندازی می‌کند تا بااستفاده از اطلاعات اعتباری کاربر، ابزارها را به‌طور ایمن پُرسمان کند.

معماری هویت دوگانه

برای رسیدن به این هدف، با روش انجام این کارها آشنا خواهید شد:

  1. «عامل ADK» بسازید که به سرور «پروتکل بافتار مدل» (MCP) GitHub متصل شود.
  2. ابزار عامل را از GitHub PAT (رمز دسترسی شخصی) ایستا به جریان OAuth سه‌پایه (3LO) بااستفاده از مدیر اصالت‌سنجی Google Cloud به‌روز کنید.
  3. عامل را به‌طور امن در زمان اجرای عامل مستقر کنید و هویت عامل را آماده کنید.
  4. نقش‌های IAM را پیکربندی کنید تا دسترسی هویت عامل به خزانه رمز را ازطرف کاربر فراهم کنید.
  5. جریان سرتاسر 3LO را برای «مدیر اصالت‌سنجی» در Google Cloud درک کنید.

پیش‌نیازها

قبل‌از شروع، مطمئن شوید که:

  • پروژه Google Cloud با صورت‌حساب فعال.
  • ‫Google Cloud SDK (gcloud CLI) در ماشین محلی‌تان نصب و برای پروژه شما اصالت‌سنجی شده باشد. نسخه ۵۸۶.۰.۰ یا جدیدتر لازم است — gcloud components update را اجرا کنید.
  • Python 3.10 تا 3.13 به‌صورت محلی نصب شده است.
  • uv مدیر بسته نصب شد (pip install uv).
  • حساب GitHub برای ثبت برنامه OAuth و ایجاد نشان‌ها. اگر حساب github ندارید، می‌توانید هر سرور MCP طرف سومی را که از OAuth 2.0 سه‌پا پشتیبانی می‌کند جایگزین کنید.

۲. راه‌اندازی پروژه

۱. اصالت‌سنجی در Google Cloud

از خط فرمان محلی‌تان در Google Cloud اصالت‌سنجی کنید تا مطمئن شوید محیطتان اجازه‌های لازم را برای استقرار در «زمان اجرای عامل»، آماده‌سازی «هویت عامل»، و پیکربندی «مدیر اصالت‌سنجی» درطول این آزمایشگاه دارد:

برای ورود به سیستم حساب Google Cloud خودتان و پیکربندی «اطلاعات اعتباری پیش‌فرض برنامه» (ADC)، فرمان‌های زیر را اجرا کنید:

gcloud auth login
gcloud auth application-default login

۲. فعال کردن «خدمات Google Cloud» موردنیاز

برای اجرای این آزمایشگاه، میاناهای برنامه‌سازی کاربردی لازم را در پروژه Google Cloud خود فعال کنید. فرمان زیر را در پایانه‌تان اجرا کنید:

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

اجرای این فرمان ممکن است یک دقیقه طول بکشد؛ پس‌از تکمیل، به پیام‌واره فرمان برمی‌گردد و فعال بودن «میاناهای برنامه‌سازی کاربردی» را تأیید می‌کند.

۳. نصب کردن CLI عامل‌ها و راه‌اندازی پروژه

agents-cli ابزار خط فرمانی است که برای چارچوب‌بندی، مدیریت، آزمایش، و استقرار عاملان ADK در Gemini Enterprise استفاده می‌شود. آن را به‌صورت محلی نصب کنید:

uvx google-agents-cli setup

نصب خود را درستی‌سنجی کنید:

agents-cli --help

باید منو راهنمای CLI را ببینید که فرمان‌های دردسترس (مثل deploy،‏ run، و status) را نمایش می‌دهد.

ساختن داربست اولیه پروژه. با یک پیش‌نمونه محلی شروع می‌کنید و بعداً آن را برای استقرار «زمان اجرای عامل» بهبود می‌دهید:

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

این کار باعث ایجاد دایرکتوری secure-agent-demo می‌شود که حاوی کد عامل پایه، وابستگی‌ها، و فایل‌های آزمایشی شما است.

۴. افزودن اضافه‌های موردنیاز «کیت توسعه‌دهندگان تبلیغات»

‫pyproject.toml تولیدشده google-adk[gcp,otel-gcp] را ارسال می‌کند که دو مورد اضافی موردنیاز این عامل را ندارد: mcp برای مجموعه ابزار GitHub و agent-identity برای «مدیر اصالت‌سنجی» در ادامه آزمایشگاه. ‫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

۳. ساختن و آزمایش عامل

۱. ایجاد عامل

در پروژه خود، کد را در فایل 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",
)

این فایل سه عنصر کلیدی عامل را تعریف می‌کند:

  • دستور سیستم (INSTRUCTION): شخصیت را تنظیم می‌کند، دستیار را به تریاژ GitHub محدود می‌کند، و قوانین ایمنی سخت‌گیرانه را اعمال می‌کند (مانند دسترسی فقط خواندنی و راهنمایی کاربران برای اصالت‌سنجی درصورت بروز خطا).
  • پیکربندی عامل (root_agent): بااستفاده از مدل gemini-3.8-flash، یک ADK Agent را نمونه‌سازی می‌کند، منطق تلاش مجدد HTTP را پیکربندی می‌کند، و عامل را به مجموعه ابزار GitHub مجهز می‌کند.
  • App Wrapper (app): عامل ریشه را در یک ظرف ADK App کپسوله می‌کند و آن را برای استقرار در Agent Runtime آماده می‌کند.

۲. افزودن «ابزار GitHub MCP»

این هوش‌یار ازطریق «پروتکل زمینه‌ای مدل» (MCP) به GitHub متصل می‌شود. برای ثبت پارامترهای اتصال دروازه MCP، فایل جدیدی به‌نام tools.py در پوشه app/ ایجاد کنید. کد زیر را کپی و جای‌گذاری کنید:

# 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 را به‌عنوان یک نشانه «حامل» تزریق می‌کند و حالت فقط خواندنی (X-MCP-Readonly: true) را مستقیماً در لایه انتقال اعمال می‌کند.

۳. آزمایش محلی با GitHub PAT (رمز دسترسی شخصی)

برای اجرای محلی عامل با اطلاعات اعتباری ایستا:

  1. GitHub Personal Access Token ایجاد کنید. به آن دسترسی خواندن مخزن‌هایتان را اعطا کنید، درغیراین‌صورت عامل فقط می‌تواند داده‌های عمومی را ببیند و پیام‌واره زیر چیزی برنمی‌گرداند.
  2. آن را در محیط خود تنظیم کنید: 
    export GITHUB_TOKEN="your_github_pat_here"
  3. به پوشه secure-agent-demo پیمایش کنید. اجرا: 
    cd secure-agent-demo
agents-cli playground
  4. میانای زمین بازی را باز کنید، پوشه «برنامه» را از منو کرکره‌ای انتخاب کنید. در چارگوش گپ، "Fetch my contributions across my private repositories over the last 6 months" را تایپ کنید و درستی‌سنجی کنید که عامل هوشواره‌ای ابزار GitHub را فرا می‌خواند و داده‌ها را از مخزن‌های خصوصی‌تان برمی‌گرداند.

۴. پیکربندی «مدیر احراز هویت»

اگرچه کدبندی سخت اطلاعات اعتباری ایستا (مثل PAT) برای نمونه‌سازی اولیه راحت است، اما برنامه‌های تولید را درمعرض نشت اطلاعات اعتباری، زمان ازکارافتادگی بازآوری دستی کد، و فقدان کنترل‌های دسترسی بومی ابری قرار می‌دهد.

برای حل این مشکل، Google Cloud مدیر اصالت هویت عامل را ارائه می‌دهد. مدیر اصالت هویت نماینده یک خزانه اطلاعات اعتباری است که برای کمک به محافظت از اطلاعات اعتباری طراحی شده است. این API به نمایندگان اجازه می‌دهد بااستفاده از کلید API یا رمز و شناسه کارخواه OAuth، یا ازطرف کاربر ازطریق واگذاری OAuth بااستفاده از کدهای دسترسی کاربر نهایی اصالت‌سنجی کنند.

در «مدیر اصالت‌سنجی»، ارائه‌دهندگان اصالت‌سنجی را پیکربندی می‌کنید که نوع اصالت‌سنجی و اطلاعات اعتباری را برای برنامه‌های طرف سوم خاص تعریف می‌کنند. ارائه‌دهندگان اصالت منطقه‌ای هستند و منطقه باید با منطقه‌ای که عامل را در آن مستقر می‌کنید مطابقت داشته باشد. گردش کار «مدیر اصالت‌سنجی» سرتاسری به این صورت عمل می‌کند:

گردش کار مدیر اصالت‌سنجی

  1. «رهگیری موافقت پویا»: وقتی نماینده‌ای تلاش می‌کند ابزاری را ازطرف کاربر اجرا کند، ADK وجود اعتبارنامه معتبر را در «مدیر اصالت‌سنجی» بررسی می‌کند. اگر هیچ‌کدام وجود نداشته باشد، «مدیر اصالت‌سنجی» نشانی وب مجوز را برای شروع جریان موافقت OAuth سه‌پایه (3LO) برمی‌گرداند.
  2. ذخیره‌سازی امن: پس‌از اینکه کاربر نهایی برنامه را مجاز کرد، «مدیر اصالت‌سنجی» به‌طور خودکار تماس برگشتی OAuth را رهگیری می‌کند و دسترسی کاربر و ژتون‌های بازآوری را در خزانه اعتبارنامه‌های امن و مدیریت‌شده توسط Google ذخیره می‌کند.
  3. چرخه حیات خودکارسازی‌شده کد: «مدیر اصالت‌سنجی» انقضا و چرخش کد را به‌طور کامل در پس‌زمینه مدیریت می‌کند و نیاز به منطق بازآوری کد دستی یا زمان توقف را ازبین می‌برد.
  4. اجرای ابزار بدون رمز: برای کنش‌های بعدی، کارگزار (که ازطریق هویت کارگزار SPIFFE خود اصالت‌سنجی می‌کند) به‌صورت پویا در زمان اجرا از Auth Manager درخواست رمز دسترسی نمایندگی‌شده کاربر را می‌کند و کد کارخواه و کارگزار را کاملاً بدون رمز نگه می‌دارد.

مرحله A: پیکربندی GitHub به‌عنوان ارائه‌دهنده اصالت‌سنجی

فرمان gcloud زیر را اجرا کنید تا ارائه‌دهنده اصالت‌سنجی GitHub را در پروژه Google Cloud خود ایجاد کنید. شناسه و رمز کارخواه را بعداً ارائه می‌کنید: GitHub آن‌ها را تا زمانی‌که نشانی وب تماس برگشتی این ارائه‌دهنده را نداند صادر نمی‌کند.

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"

ارائه‌دهنده را برای بازیابی نشانی وب هدایت 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. برای نشانی وب صفحه اصلی، نشانی وب برنامه پیش‌خوان خود را وارد کنید (برای نمونه، http://localhost:8501 برای نمونه‌سازی محلی. بعداً می‌توانید آن را به نشانی وب مستقرشده‌تان در محیط تولید تغییر دهید.
  3. نشانی وب هدایت را روی 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» شما اکنون به‌طور کامل با اطلاعات اعتباری برنامه GitHub OAuth پیکربندی شده است و Google Cloud را به‌عنوان خزانه امنی که با چرخه‌های عمر موافقت و کد عمل می‌کند راه‌اندازی می‌کند.

۵. جابه‌جایی نشان PAT به «مدیر احراز هویت»

اکنون که «مدیر اصالت‌سنجی» به‌طور کامل پیکربندی شده است، مرحله بعدی به‌روزرسانی کد ابزار کارگزار است. 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 ابتدا از «مدیر اصالت‌سنجی» نشانه آن کاربر را درخواست می‌کند و اگر هنوز نشانه‌ای وجود نداشته باشد، به‌جای اینکه با خطا مواجه شود، از کاربر می‌خواهد به سیستم وارد شود. ‫GITHUB_TOKEN کدبندی‌شده سخت به‌طور کامل برداشته شده است.

‫۶. مستقر کردن «عامل» در «زمان اجرای عامل»

اکنون که ابزار GitHub MCP را به‌روز کرده‌ایم تا به‌جای آن از Auth Manager استفاده کند، گام بعدی استقرار عامل در زمان اجرای عامل است. استقرار آن با فعال بودن «هویت عامل»، شناسه SPIFFE یکتایی برای عامل فراهم می‌کند.

بیایید با مقداردهی اولیه پیکربندی استقرار برای پروژه شروع کنیم. اجرا در پایانه:

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"

پیاده‌سازی «عامل» با «هویت عامل»

با adk deploy agent_engine مستقر کنید. این کار عامل را با هویت عامل خودش آماده می‌کند — هویتی رمزنگاری‌شده و منحصربه‌فرد با پشتیبانی SPIFFE که متعلق به این استقرار است و عامل از آن برای اصالت‌سنجی در 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"

استقرار چند دقیقه طول می‌کشد تا محتوی را بسازد و بارگذاری کند. پس‌از اتمام، CLI نام منبع مستقرشده را چاپ می‌کند. مقدار Engines/ENGINE_ID را یادداشت کنید، زیرا برای مجاز کردن عاملتان و اشاره کردن به مشتری واسط کاربر به آن نیاز دارید.

مجوز دادن به هویت عامل

اکنون که کارگزار شما در فضای ابری اجرا می‌شود، برای دسترسی به اطلاعات اعتباری ذخیره‌شده در Auth Manager به اجازه نیاز دارد. به‌طور پیش‌فرض، هویت SPIFFE عامل به منابع ابری خارجی دسترسی ندارد.

برای اعطای نقش roles/agentidentity.user به هویت کارگزارتان در منبع ارائه‌دهنده اصالت‌سنجی، فرمان gcloud زیر را اجرا کنید. این کار به عامل شما دقیقاً اجازه‌هایی را که برای درخواست کردن نشان‌های کاربر از خزانه لازم دارد می‌دهد، و نه اجازه‌های بیشتر.

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

اکنون همان نقش را در ارائه‌دهنده به حساب خودتان اعطا کنید. کارخواه میانای کاربری که در مرحله بعد اجرا می‌کنید، «میانای برنامه‌سازی کاربردی نهایی‌سازی اعتبارنامه» را با «اعتبارنامه‌های پیش‌فرض برنامه» شما فرا می‌خواند، بنابراین بدون این، جریان موافقت با خطای ۴۰۳ در 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"

‫۷. درک جریان موافقت 3LO

اکنون که عامل با «هویت عامل» امن در «زمان اجرای عامل» مستقر شده است، مرحله بعدی ارائه یک میانای جلویی سفارشی برای کاربران است تا با آن گپ بزنند. مهم‌تر از همه، ‫Google Cloud Auth Manager برای تکمیل حلقه اصالت‌سنجی به مدیریت تماس برگشتی برنامه مشتری نیاز دارد.

اگرچه Google Cloud Auth Manager اطلاعات اعتباری کاربر را به‌طور ایمن در خزانه مدیریت می‌کند، اما نمی‌تواند تبادل کد OAuth را به‌تنهایی نهایی کند. دست‌دهی 3LO برای پر کردن این شکاف به برنامه کارخواه متکی است:

  1. وقتی کاربری برنامه GitHub را مجاز می‌کند، GitHub او را به ارائه‌دهنده اصالت‌سنجی «هویت کارگزار» redirectUrl هدایت می‌کند.
  2. سپس «مدیر اصالت‌سنجی» بالاپر مرورگر کاربر را به نشانی وب برگشتی سمت مشتری (continue_uri) هدایت می‌کند.
  3. برنامه مشتری مسئول رهگیری این هدایت مجدد، خواندن عدد یک‌بارمصرف از کوکی‌های مرورگر، و فراخوانی نقطه پایانی credentials:finalize در Google Cloud برای تکمیل دست دادن است.
  4. پس‌از اینکه مشتری تبادل را نهایی کرد، Google Cloud به‌طور ایمن نشان را در خزانه ارائه‌دهنده اصالت‌سنجی ذخیره می‌کند و به کارگزار اجازه می‌دهد ابزار GitHub را فراخوانی کند.

بدون این مشتری سفارشی که میزبان نقطه پایانی تماس برگشتی است، دست دادن ناقص می‌ماند و خزانه نمی‌تواند اطلاعات اعتباری را ذخیره کند.

جریان تعاملی OAuth 3LO در چندین لایه گسترده است. در اینجا چرخه حیات کامل اجرای درخواست ابزار آورده شده است. در توضیح زیر و در مرحله بعد، این موضوع را به‌تفصیل توضیح خواهیم داد.

👈 برای بزرگ کردن تصویر، روی آن کلیک کنید.

جریان توالی OAuth سه‌پایه

مسئولیت‌های اصلی «کارخواه» در «دست دادن»

  • انتقال چالش موافقت (مراحل ۵-۶): کارگزار adk_request_credential را که حاوی نشانی وب موافقت و یک عدد تصادفی تک‌مصرف است منتشر می‌کند؛ کارخواه بالاپر را باز می‌کند و عدد تصادفی را به‌عنوان کوکی ذخیره می‌کند.
  • میزبانی کردن تماس برگشتی هدایت مجدد (مراحل ۱۰ تا ۱۱): /validateUserId، جایی که «مدیر اصالت‌سنجی» پس‌از موافقت، بالاپری را ارسال می‌کند.
  • نهایی کردن کد (مراحل ۱۲ تا ۱۴): وضعیت اعتبارسنجی را از هدایت مجدد با مقدار یک‌بارمصرف ذخیره‌شده در حافظه پنهان ترکیب کنید و credentials:finalize را فراخوانی کنید که کد را در گاوصندوق ذخیره می‌کند.

ساختن کارخواه خودتان

لازم نیست این کارخواه را برای آزمایشگاه بنویسید — مرحله بعدی کارخواه پیش‌ساخته‌ای را اجرا می‌کند. وقتی می‌خواهید این را در برنامه خودتان پیاده‌سازی کنید، این دو مرجع برای کار کردن هستند:

‫۸. اجرای محلی کارخواه واسط کاربر

همان‌طور که در نمودار توالی جریان موافقت 3LO ردیابی کردیم، «مدیر اصالت‌سنجی» باید بالاپَر مرورگر را به نقطه پایانی تماس برگشتی سمت کارخواه هدایت کند. کارخواه نمونه آن نقطه پایانی را در /validateUserId میزبانی می‌کند. بیایید آن را به‌صورت محلی اجرا کنیم.

کپی کردن فایل‌های مشتری در «محلی»

به پوشه 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 گوش می‌دهد.

‫۹. جریان OAuth را آزمایش کنید

اکنون که همه سرویس‌ها مستقر شده‌اند، پیوندهای IAM پیکربندی شده‌اند، و متغیرهای محیطی تنظیم شده‌اند، آماده‌اید تا جریان مجوز کاربر-واگذارشده امن سرتاسری را آزمایش کنید!

مرحله الف: شروع اجرای ابزار

  1. برگه مرورگری را باز کنید و به «نشانی وب کارخواه» خود بروید: http://localhost:8501.
  2. در قاب سمت راست، «نوع نماینده» را روی Remote Agent Engine تنظیم کنید.
  3. «پروژه Google Cloud» و «مکان» خود را تایپ کنید. روی Load Remote Agents کلیک کنید. با این کار، همه عامل‌های مستقرشده در پروژه شما بار می‌شود.
  4. کارگزار مناسب را از منو کرکره‌ای انتخاب کنید و تنظیمات را ذخیره کنید.
  5. در چارگوش گپ، تایپ کنید: 
    Fetch my contributions across my private repositories over the last 6 months
    و کلید Enter را فشار دهید.
  6. واسط کاربر گپ را مشاهده کنید: چون نماینده هنوز اعتبارنامه‌ای برای جلسه کاربر شما ندارد، یک چالش اصالت‌سنجی دریافت می‌کند و کارت «اصالت‌سنجی لازم است» را در رشته مکالمه نمایش می‌دهد.
  1. پنجره بالاپری مرورگر جداگانه‌ای باز می‌شود که شما را ازطریق «مدیر اصالت‌سنجی» Google Cloud به صفحه مجوز GitHub OAuth هدایت می‌کند.
  2. اجازه‌های درخواستی را مرور کنید و روی مجوز دادن کلیک کنید.
  3. ‫GitHub به Google Cloud هدایت می‌کند، که بالاپر را به localhost نشانی وب تماس برگشتی /validateUserId شما هدایت می‌کند.
  4. سرویس تماس برگشتی دست‌دهی اطلاعات اعتباری را پردازش و نهایی می‌کند.

مرحله پ: ازسر گرفتن

  1. پس‌از بسته شدن پنجره بالاپر، برگه گپ اصلی به‌طور خودکار بسته شدن را تشخیص می‌دهد.
  2. پیش‌کار پایه‌بار ازسرگیری را به نماینده برمی‌گرداند.
  3. کارگزار به‌طور ایمن نشان مبادله‌شده جدید را از Google Cloud Auth Manager بازیابی می‌کند، ابزارهای GitHub MCP را ازطرف شما فرا می‌خواند، و داده‌ها را از مخزن‌های خصوصی‌تان مستقیماً به پنجره گپ جاری‌سازی می‌کند — داده‌هایی که کارگزار به‌تنهایی نمی‌توانست به آن‌ها دسترسی پیدا کند.

مرحله D: بررسی گزارش‌های Cloud

برای درستی‌سنجی اینکه تبادل و نهایی‌سازی کد امن انجام شده است:

  1. به «کنسول Google Cloud» کاوشگر گزارش‌ها بروید.
  2. گزارش‌های سرور را که استخراج عدد یک‌بارمصرف و درستی‌سنجی موفق را تأیید می‌کند پیدا کنید: 
    INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.
  3. بازرسی گزارش‌های زمان اجرای عامل: همچنین می‌توانید گزارش‌های اجرا را مستقیماً در «کنسول پلاتفرم عامل» مشاهده کنید:
    • به کنسول زمان اجرای عامل پیمایش کنید.
    • روی عامل مستقرشده خود از فهرست کلیک کنید.
    • به برگه زمین بازی بروید؛ این کار باعث می‌شود گزارش‌های عامل زنده در قاب پایین نمایش داده شود و حلقه استدلال عامل، جزئیات اجرای ابزار، و چرخه حیات بازیابی کد در لحظه به شما نشان داده شود.

‫۱۰. پاک‌سازی

برای جلوگیری از هزینه‌های جاری در 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. با فشار دادن Ctrl+C در ترمینالی که سرور محلی uvicorn در آن اجرا می‌شود، آن را متوقف کنید.
  2. فهرست‌های پروژه ایجادشده درطول این آزمایشگاه را بردارید:
# cd to the correct folder
rm -rf secure-agent-demo client adk-python

‫۱۱. تبریک!

باموفقیت عاملی را ساخته و ایمن کرده‌اید که ازطرف کاربر واردشده به سیستم عمل می‌کند!

آنچه یاد گرفتید:

  • هویت سیستم عامل: نحوه عملکرد عامل تحت هویت «حساب» خود برای تعامل ایمن با زیرساخت GCP، مدیریت گزارش‌های تله‌متری، و فراخوانی APIهای نهایی‌سازی اطلاعات اعتباری.
  • هویت واگذارشده کاربر: نحوه درخواست مجوز نماینده برای اقدام ازطرف کاربر در پلاتفرم‌های خارجی (مانند GitHub) با راه‌اندازی جریان موافقت OAuth سه‌پایه (3LO).
  • ادغام ابزار ایمن: نحوه اتصال «عامل‌های ADK» به سرورهای «پروتکل بافتار مدل» (MCP) بااستفاده از Google Cloud Auth Manager برای واکشی پویای نشان‌های کاربر به‌جای استفاده از رمزهای سخت‌کدگذاری‌شده.
  • پیکربندی خط‌مشی IAM: نحوه تنظیم کردن اتصال‌های اجازه دقیق برای مجاز کردن هم هویت «زمان اجرای نماینده» و هم حساب خودتان در ارائه‌دهنده اصالت‌سنجی.

مطالعه بیشتر