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

۱. مقدمه

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

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

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

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

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

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

  1. ساختن «عامل ADK» که به سرور «پروتکل بافت مدل» (MCP) در GitHub متصل می‌شود.
  2. ابزار عامل را از PAT (کد دسترسی شخصی) GitHub ایستا به جریان OAuth سه‌پایه (3LO) بااستفاده از مدیر اصالت‌سنجی Google Cloud به‌روز کنید.
  3. عامل را به‌طور ایمن در Agent Runtime مستقر کنید و Agent Identity را فراهم کنید.
  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 اصالت‌سنجی کنید تا مطمئن شوید محیط شما اجازه‌های لازم را برای استقرار در Agent Runtime، تدارک Agent Identity، و پیکربندی Auth Manager دارد.

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

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
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) را نمایش می‌دهد.

تولید داربست اولیه پروژه. با یک نمونه اولیه محلی شروع خواهید کرد و بعداً آن را برای استقرار Agent Runtime بهبود خواهید داد:

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

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

۴. اضافه‌های ADK موردنیاز را اضافه کنید

دو مورد اضافی جاافتاده را در pyproject.toml تولیدشده اضافه کنید: 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

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

۱. ایجاد کردن عامل

در پروژه‌تان، کد secure-agent-demo/app/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): یک ADK Agent را بااستفاده از مدل gemini-3.8-flash نمونه‌سازی می‌کند، منطق تلاش مجدد HTTP را پیکربندی می‌کند، و عامل را به مجموعه ابزار GitHub مجهز می‌کند.
  • پوشاننده برنامه (app): عامل ریشه را در یک محفظه ADK App کپسوله می‌کند و آن را برای Agent Runtime قابل‌استقرار می‌سازد.

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

عامل بااستفاده از «پروتکل بافت مدل» (MCP) به GitHub متصل می‌شود. فایل جدیدی در secure-agent-demo/app/tools.py ایجاد کنید تا پارامترهای اتصال درگاه 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 را به‌عنوان رمزیاب دارنده تزریق می‌کند و حالت فقط خواندنی (X-MCP-Readonly: true) را مستقیماً در لایه انتقال اعمال می‌کند.

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

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

  1. در صفحه کدهای دسترسی شخصی GitHub، یک کد دسترسی شخصی دقیق ایجاد کنید:
    • روی تولید کردن کد جدید کلیک کنید و نامی برای کدتان انتخاب کنید.
    • در بخش دسترسی به مخزن، همه مخزن‌ها را انتخاب کنید (یا مخزن‌های خاصی را که می‌خواهید با آن‌ها آزمایش کنید انتخاب کنید).
    • در بخش اجازه‌ها > مخزن‌ها، روی +افزودن اجازه‌ها کلیک کنید و محتوا، مشکلات، و درخواست‌های Pull را روی فقط خواندنی تنظیم کنید (فراداده به‌طور خودکار روی «فقط خواندنی» تنظیم می‌شود).
    • روی تولید کردن کد کلیک کنید و مقدار کد تولیدشده را کپی کنید. (یا اگر از کد دسترسی شخصی (کلاسیک) استفاده می‌کنید، دامنه repo را انتخاب کنید.)
  2. آن را در محیط خود تنظیم کنید:
    export GITHUB_TOKEN="your_github_pat_here"
    
  3. به پوشه secure-agent-demo بروید (اگر ازقبل در آن نیستید) و زمین بازی محلی را شروع کنید:
    cd secure-agent-demo
    agents-cli playground
    
  4. میانای زمین بازی را باز کنید و پوشه app را از منو کرکره‌ای انتخاب کنید. در چارگوش گپ، پیام‌واره هدفمندی مثل "Get the last 2 GitHub issues reported against my name" یا "List my 3 most recently updated repositories" را امتحان کنید و بررسی کنید که عامل مجموعه ابزار MCP مربوط به GitHub را فراخوانی می‌کند و داده‌های GitHub شما را برمی‌گرداند. برای آزمایش اینکه آیا نماینده واقعاً از توکن PAT شما برای اقدام ازجانب شما استفاده می‌کند یا نه، از آن درباره مخازن خصوصی یا مشارکت‌هایتان سؤال کنید.

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

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

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

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

گردش کار مدیر احراز هویت

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

مرحله الف: پیکربندی GitHub به‌عنوان ارائه‌دهنده Auth

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

gcloud agent-identity auth-providers create github-oauth-provider \
    --project="YOUR_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="YOUR_PROJECT_ID" \
    --location="us-central1"

فیلد redirectUrl است، که در authProviderTypeParams.threeLeggedOauth تودرتو شده است. برای خواندن مستقیم آن:

gcloud agent-identity auth-providers describe github-oauth-provider \
    --project="YOUR_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 را در نوار کناری سمت راست انتخاب کنید، و روی برنامه OAuth جدید (یا ثبت برنامه جدید اگر قبلاً برنامه‌ای ایجاد نکرده‌اید) کلیک کنید.
  2. فیلدهای فرم درخواست OAuth را پر کنید:
    • نام برنامه: نامی برای برنامه‌تان وارد کنید (برای مثال، secure-agent-demo).
    • نشانی وب صفحه اصلی: نشانی وب برنامه پیش‌نمای خود را وارد کنید (http://localhost:8501 برای نمونه‌سازی محلی؛ می‌توانید آن را به نشانی وب مستقرشده خود در تولید به‌روز کنید).
    • شرح درخواست: اختیاری (می‌توانید این قسمت را خالی بگذارید).
    • نشانی وب فراخوانی مجوز (URI هدایت): redirectUrl بازیابی‌شده در «مرحله الف» را جای‌گذاری کنید.
    • فعال کردن جریان دستگاه: علامت نزنید.
  3. روی ثبت برنامه کلیک کنید.
  4. در صفحه برنامه حاصل، شناسه کارخواه را کپی کنید، سپس روی تولید رمز کارخواه جدید کلیک کنید و رمز کارخواه تولیدشده را کپی کنید. هر دو مقدار را ذخیره کنید — در مرحله بعد از آن‌ها به‌عنوان YOUR_GITHUB_CLIENT_ID و YOUR_GITHUB_CLIENT_SECRET استفاده خواهید کرد.

مرحله ۳: افزودن اطلاعات کاربری GitHub به ارائه‌دهنده احراز هویت

YOUR_PROJECT_ID، YOUR_GITHUB_CLIENT_ID، و YOUR_GITHUB_CLIENT_SECRET را با مقادیر خودتان جایگزین کنید و این فرمان را اجرا کنید:

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 به «مدیر اصالت‌سنجی»

اکنون که «مدیر اصالت‌سنجی» کاملاً پیکربندی شده است، مرحله بعدی به‌روزرسانی کد ابزار عامل است. محتویات secure-agent-demo/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 در محل به‌روز کرده‌ایم، گام بعدی استقرار عامل در Agent Runtime است. استقرار آن با فعال بودن «هویت عامل»، یک شناسه SPIFFE یکتا برای عامل فراهم می‌کند.

پیکربندی استقرار را برای پروژه مقداردهی اولیه کنید. مطمئن شوید پایانه شما در دایرکتوری ریشه پروژه secure-agent-demo باشد، سپس این دستور را اجرا کنید:

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 استفاده می‌کند.

👉 از فهرست راهنمای secure-agent-demo، YOUR_PROJECT_ID را جایگزین کنید و این فرمان‌ها را اجرا کنید:

# Write a config file inside the `app/` folder instructing Agent Runtime to provision 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 نام منبع مستقرشده را چاپ می‌کند. مقدار reasoningEngines/ENGINE_ID را یادداشت کنید، زیرا برای صدور مجوز برای عامل و هدایت کردن کارخواه واسط کاربر به آن به این مقدار نیاز دارید.

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

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

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

# Get YOUR_ORG_ID
gcloud projects get-ancestors $(gcloud config get-value project) \
  --filter="type=organization" \
  --format="value(id)"

# Get YOUR_PROJECT_NUMBER
gcloud projects describe $(gcloud config get-value project) \
  --format="value(projectNumber)"

سپس خط‌مشی IAM را به ارائه‌دهنده احراز هویت متصل کنید (YOUR_PROJECT_ID و مدیر --member را جایگزین کنید):

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"

👉 همچنین می‌توانید مقدار کامل --member="principal://..." را برای عامل مستقرشده‌تان از «کنسول Google Cloud» دریافت کنید: به کنسول زمان اجرای عامل بروید، عامل مستقرشده‌تان را انتخاب کنید، به برگه هویت بروید و رشته کامل principal://... را مستقیماً کپی کنید.

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

اکنون که عامل با «هویت عامل» امن در Agent Runtime مستقر شده است، گام بعدی ارائه یک میانای پیشانه سفارشی برای کاربران است تا بتوانند با آن گپ بزنند. مهم‌تر اینکه 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 ردیابی شده است، «مدیر اصالت‌سنجی» پنجره مرورگر را به نقطه پایانی فراخوان سمت کارخواه هدایت می‌کند. نمونه کارخواه در مخزن adk-python آن نقطه پایانی را در /validateUserId میزبانی می‌کند. بااستفاده از مراحل زیر، آن را بارگیری و به‌صورت محلی اجرا کنید.

بارگیری فایل‌های کارخواه

دایرکتوری contributing/samples/integrations/gcp_auth/client در adk-python شامل سه دارایی کلیدی است:

  • main.py: باطن FastAPI که به Agent Engine مستقرشده شما متصل می‌شود و نقطه پایان فراخوانی برگشتی /validateUserId را برای نهایی کردن کدهای OAuth میزبانی می‌کند.
  • static/: فایل‌های HTML و جاوا اسکریپت برای واسط کاربر گپ مرورگر.
  • requirements.txt: بسته‌های Python موردنیاز برای اجرای سرور کارخواه.

چون adk-python مخزن بزرگی است، از ویژگی تسویه‌حساب پراکنده Git استفاده کنید تا فقط پوشه contributing/samples/integrations/gcp_auth/client را بارگیری کنید:

  1. ابتدا، یک دایرکتوری از secure-agent-demo بالاتر بروید تا کارخواه را در پوشه هم‌سطح شبیه‌سازی کنید:
    cd ..
    
  2. فرمان‌های زیر را اجرا کنید تا فراداده مخزن را بدون بارگیری همه فایل‌ها (--no-checkout) شبیه‌سازی کنید، مسیر بررسی را به contributing/samples/integrations/gcp_auth/client محدود کنید، و فقط آن پوشه را بررسی کنید:
    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. از داخل دایرکتوری adk-python که به‌تازگی وارد کرده‌اید، به پوشه client بروید:
    cd contributing/samples/integrations/gcp_auth/client
    
  2. یک محیط مجازی Python ایجاد و فعال کنید، سپس وابستگی‌های کارخواه را از requirements.txt نصب کنید:
    uv venv --python 3.13 .venv
    source .venv/bin/activate
    uv pip install --python .venv/bin/python -r requirements.txt
    
  3. متغیرهای محیطی را که کارخواه را به پروژه Google Cloud، منطقه (us-central1)، و شناسه Agent Engine مستقرشده (YOUR_ENGINE_ID) هدایت می‌کنند تنظیم کنید، سپس سرور FastAPI محلی را در درگاه 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 (Vertex AI) (یا Remote Agent Engine) تنظیم کنید.
  3. شناسه پروژه و مکان (us-central1) Google Cloud خود را وارد کنید، سپس روی بار کردن عوامل ازراه‌دور کلیک کنید. با این کار، عوامل مستقرشده در پروژه‌تان بار می‌شود.
  4. عامل app مستقرشده‌تان را از منو کرکره‌ای انتخاب موتور انتخاب کنید و روی ذخیره و اعمال تنظیمات کلیک کنید.
  5. در چارگوش گپ، پُرسمان هدف‌گیری‌شده‌ای را تایپ کنید (مثلاً واکشی مشکلات یا مخزن‌های اخیر):
    Get the last 2 GitHub issues reported against my name
    
    (یا "List my 3 most recently updated repositories" را امتحان کنید) و کلید Enter را فشار دهید.
  6. واسط کاربر گپ را مشاهده کنید: چون نماینده هنوز اعتبارنامه‌ای برای جلسه کاربر شما ندارد، چالش اصالت‌سنجی دریافت می‌کند و کارت «اصالت‌سنجی لازم است» را در رشته مکالمه نمایش می‌دهد.
  1. پنجره بالاپر مرورگر جداگانه‌ای باز می‌شود و شما را ازطریق «مدیر احراز هویت» Google Cloud به صفحه مجوز GitHub OAuth هدایت می‌کند.
  2. اجازه‌های درخواستی را مرور کنید و روی مجاز کردن کلیک کنید.
  3. GitHub به Google Cloud هدایت می‌کند، که بالاپر را به localhost نشانی وب فراخوان /validateUserId شما هدایت می‌کند.
  4. سرویس فراخوانی برگشتی، دست‌دهی اطلاعات اعتباری را پردازش و نهایی می‌کند.

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

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

مرحله ۴: بررسی گزارش‌های 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. بررسی گزارش‌های زمان اجرای Agent: همچنین می‌توانید گزارش‌های اجرا را مستقیماً در «کنسول پلاتفرم Agent» مشاهده کنید:
    • به کنسول زمان اجرای Agent بروید.
    • روی نماینده مستقرشده‌تان در فهرست کلیک کنید.
    • به برگه Playground بروید؛ با این کار گزارش‌های زنده عامل در قاب پایین نمایش داده می‌شود و حلقه استدلال عامل، جزئیات اجرای ابزار، و چرخه حیات بازیابی کد به‌صورت هم‌زمان نشان داده می‌شود.

‫۱۰. پاک‌سازی کردن

برای جلوگیری از کسر هزینه‌های جاری در 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، مدیریت گزارش‌های دورسنجی، و فراخوانی میاناهای برنامه‌سازی کاربردی نهایی‌سازی اطلاعات کاربری.
  • هویت واگذارشده کاربر: نحوه درخواست مجوز توسط عامل برای اقدام ازطرف کاربر در پلاتفرم‌های خارجی (مانند GitHub) با راه‌اندازی جریان رضایت OAuth سه‌جانبه (3LO).
  • ادغام امن ابزار: نحوه متصل کردن «عامل‌های ADK» به سرورهای «پروتکل بافتار مدل» (MCP) بااستفاده از Google Cloud Auth Manager برای واکشی پویای توکن‌های کاربر به‌جای استفاده از رمزهای کدگذاری‌شده.
  • پیکربندی خط‌مشی IAM: نحوه راه‌اندازی اتصال‌های اجازه‌های دقیق برای صدور مجوز برای هویت Agent Runtime و حساب خودتان در ارائه‌دهنده احراز هویت.

مطالعه بیشتر