Как создать ИИ-агента, который действует от имени пользователя, с помощью идентификации агента и менеджера авторизации

1. Введение

Агент с собственными учетными данными и широкими разрешениями видит данные всех пользователей. В этой практической работе вы создадите агента, который вызывает сторонний API с учетными данными вошедшего пользователя, чтобы видеть только то, что видит этот пользователь.

Вы создадите его с помощью Google Agent Development Kit (ADK) и Gemini Enterprise.

В частности, вы узнаете, как разработать архитектуру с двойной идентификацией, в которой:

  1. Агент действует от своего имени (идентификатор агента). Используя идентификатор агента на основе SPIFFE, агент вызывает Auth Manager, сохраняет телеметрию и вызывает Google Cloud API.
  2. Агент действует от имени пользователя (делегированная идентификация пользователя). Чтобы получить доступ к внешним ресурсам, например GitHub, агент запускает процесс получения согласия 3-legged OAuth (3LO) для безопасного запроса инструментов с использованием учетных данных пользователя.

Архитектура двойной идентификации

Для этого вы научитесь:

  1. Создайте агент ADK, который подключается к серверу Model Context Protocol (MCP) GitHub.
  2. Переведите инструмент агента со статического персонального токена доступа GitHub на трехсторонний протокол OAuth (3LO) с помощью Google Cloud Auth Manager.
  3. Безопасно разверните агент в 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.

2. Настройка проекта

1. Как выполнить аутентификацию в 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

2. Включите необходимые сервисы Google Cloud

Чтобы выполнить эту практическую работу, включите необходимые API в облачном проекте Google Cloud. Выполните в терминале следующую команду:

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

Выполнение этой команды может занять минуту. После завершения вы вернетесь в командную строку, подтверждающую, что API активны.

3. Установите 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, содержащий базовый код агента, зависимости и тестовые файлы.

4. Добавьте необходимые дополнительные параметры 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

3. Создайте и протестируйте агента

1. Создайте агента

В проекте замените код в файле 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). Создает экземпляр Agent ADK с помощью модели gemini-3.8-flash, настраивает логику повторных попыток HTTP и оснащает агент набором инструментов GitHub.
  • App Wrapper (app). Помещает корневого агента в контейнер ADK App, что позволяет развернуть его в Agent Runtime.

2. Как добавить инструмент MCP для GitHub

Агент подключается к GitHub с помощью Model Context Protocol (MCP). Создайте новый файл в 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 Toolset (McpToolset) динамически обнаруживает и регистрирует функции GitHub как вызываемые инструменты агента.
  • Параметры подключения (StreamableHTTPConnectionParams). Направляют набор инструментов к общедоступному шлюзу MCP GitHub.
  • Заголовки авторизации. Внедряет GITHUB_TOKEN в качестве токена на предъявителя и принудительно включает режим только для чтения (X-MCP-Readonly: true) непосредственно на транспортном уровне.

3. Локальное тестирование с помощью GitHub PAT (персональный токен доступа)

Чтобы запустить агент локально со статическими учетными данными:

  1. Создайте персональный токен доступа с детализированными разрешениями на странице Personal Access Tokens (Персональные токены доступа) в GitHub:
    • Нажмите Generate new token (Создать токен) и укажите название токена.
    • В разделе Repository access (Доступ к репозиториям) выберите All repositories (Все репозитории) или укажите нужные репозитории.
    • В разделе Permissions (Разрешения) > Repositories (Репозитории) нажмите +Add permissions (+Добавить разрешения) и выберите Contents (Контент), Issues (Проблемы) и Pull requests (Pull-запросы), чтобы установить для них значение Read-only (Только чтение) (для параметра Metadata (Метаданные) автоматически устанавливается значение "Только чтение").
    • Нажмите Создать токен и скопируйте его значение. Если вы используете персональный токен доступа (классический), выберите область действия 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 для выполнения действий от вашего имени, попробуйте спросить его о ваших частных репозиториях или вкладах.

4. Настроить Auth Manager

Хотя жесткое кодирование статических учетных данных (например, PAT) удобно для создания прототипов, оно подвергает рабочие приложения риску утечки учетных данных, простоям при ручном обновлении токенов и отсутствию облачных средств контроля доступа.

Чтобы решить эту проблему, Google Cloud предоставляет Agent Identity Auth Manager. Менеджер аутентификации Agent Identity – это хранилище, предназначенное для защиты учетных данных. Он позволяет агентам выполнять аутентификацию с помощью ключа API или идентификатора клиента OAuth и секретного кода, а также от имени пользователя через делегирование OAuth с использованием токенов доступа конечных пользователей.

В Auth Manager вы настраиваете поставщиков аутентификации, которые определяют тип аутентификации и учетные данные для определенных сторонних приложений. Поставщики аутентификации являются региональными, и регион должен соответствовать региону, в котором вы развертываете агент. Полный рабочий процесс Auth Manager выглядит следующим образом:

Рабочий процесс менеджера аутентификации

  1. Динамический перехват согласия. Когда агент пытается выполнить инструмент от имени пользователя, ADK проверяет Auth Manager на наличие действительных учетных данных. Если токена нет, Auth Manager возвращает URL авторизации, чтобы запустить процесс получения согласия 3LO.
  2. Безопасное хранилище. Как только конечный пользователь авторизует приложение, Auth Manager автоматически перехватывает обратный вызов OAuth и сохраняет полученные токены доступа и токены обновления в безопасном хранилище учетных данных, управляемом Google.
  3. Автоматизированный жизненный цикл токенов. Auth Manager полностью управляет сроком действия и ротацией токенов в фоновом режиме, устраняя необходимость в логике обновления токенов вручную или простое.
  4. Выполнение инструмента без секретов. Для последующих действий агент (проходящий аутентификацию через идентификатор агента SPIFFE) динамически запрашивает делегированный токен доступа пользователя у менеджера аутентификации во время выполнения, сохраняя код клиента и агента полностью свободным от секретов.

Шаг А. Настройте GitHub в качестве поставщика аутентификации

Выполните следующую команду gcloud, чтобы создать поставщика аутентификации GitHub в облачном проекте Google Cloud. Идентификатор клиента и секретный код вы укажете позже: GitHub не выдаст их, пока не узнает URL обратного вызова этого поставщика.

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"

Опишите поставщика, чтобы получить сгенерированный URL переадресации 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 Developer Settings (Настройки разработчика GitHub), выберите OAuth Apps (Приложения OAuth) на боковой панели слева и нажмите New OAuth App (Новое приложение OAuth) (или Register a new application (Зарегистрировать новое приложение), если вы ещё не создали приложение).
  2. Заполните поля формы приложения OAuth:
    • Название приложения. Введите название приложения, например secure-agent-demo.
    • URL главной страницы. Введите URL своего интерфейсного приложения (http://localhost:8501 для локального прототипирования; вы можете изменить его на URL развернутого приложения в рабочей среде).
    • Application description (Описание приложения). Необязательно (можно оставить пустым).
    • Authorization callback URL (URL обратного вызова авторизации) (URI перенаправления): вставьте redirectUrl, полученный на шаге А.
    • Enable Device Flow (Включить поток устройств) – оставьте флажок снятым.
  3. Нажмите Register application (Зарегистрировать приложение).
  4. На открывшейся странице приложения скопируйте идентификатор клиента, затем нажмите Generate a new client secret (Создать секретный код клиента) и скопируйте созданный секретный код клиента. Сохраните оба значения. На следующем шаге вы будете использовать их как 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 Auth Manager полностью настроен с учетными данными приложения GitHub OAuth. Google Cloud будет выступать в качестве защищенного хранилища, которое управляет согласием и жизненными циклами токенов.

5. Переключить токен PAT на Auth Manager

Теперь, когда Auth Manager полностью настроен, следующим шагом будет обновление кода инструмента агента. Замените содержимое файла 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 сначала запрашивает у Auth Manager токен этого пользователя, и если его ещё нет, он предлагает пользователю войти в систему вместо сбоя. Заданный в коде параметр GITHUB_TOKEN полностью удален.

6. Развертывание агента в Agent Runtime

Теперь, когда мы обновили инструмент MCP GitHub для использования 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. Для этого перейдите в консоль Agent Runtime, выберите развернутого агента, откройте вкладку Identity (Идентификация) и скопируйте всю строку principal://....

Теперь предоставьте своему аккаунту ту же роль у поставщика. Клиент пользовательского интерфейса, который вы запустите на следующем шаге, вызывает API завершения учетных данных с вашими Application Default Credentials, поэтому без этого процесс согласия завершается с ошибкой 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. Как работает процесс получения согласия 3LO

Теперь, когда агент развернут в Agent Runtime с защищенным Agent Identity, следующим шагом будет предоставление пользователям настраиваемого интерфейса для общения с ним. Кроме того, для завершения цикла аутентификации Google Cloud Auth Manager требуется обработчик обратных вызовов клиентского приложения.

Google Cloud Auth Manager безопасно управляет учетными данными пользователей в хранилище, но не может самостоятельно завершить обмен токенами OAuth. В процессе рукопожатия 3LO клиентское приложение выступает в качестве связующего звена:

  1. Когда пользователь авторизует приложение GitHub, GitHub перенаправляет его обратно на URL перенаправления поставщика идентификационной информации агента redirectUrl.
  2. Затем Auth Manager перенаправляет всплывающее окно браузера пользователя обратно на клиентский URL обратного вызова (continue_uri).
  3. Клиентское приложение должно перехватить это перенаправление, прочитать одноразовый код из файлов cookie браузера и вызвать конечную точку credentials:finalize Google Cloud, чтобы завершить рукопожатие.
  4. Когда клиент завершает обмен, Google Cloud надежно сохраняет токен в хранилище поставщика аутентификации, позволяя агенту вызывать инструмент GitHub.

Без этого пользовательского клиента, на котором размещена конечная точка обратного вызова, подтверждение связи остается незавершенным, и хранилище не может сохранить учетные данные.

Интерактивный процесс OAuth 3LO состоит из нескольких уровней. Ниже описан полный жизненный цикл выполнения запроса инструмента. Ниже и на следующем шаге мы подробно расскажем, как это сделать.

👉 Нажмите на изображение, чтобы увеличить его.

Схема трехстороннего протокола OAuth

Основные обязанности клиента при передаче аккаунта

  • Передача запроса на согласие (шаги 5–6). Агент отправляет событие adk_request_credential, содержащее URL согласия и одноразовый код. Клиент открывает всплывающее окно и сохраняет код в виде файла cookie.
  • Разместите обратный вызов переадресации (шаги 10–11): /validateUserId, куда Auth Manager отправляет всплывающее окно после получения согласия.
  • Завершение создания токена (шаги 12–14). Объедините статус подтверждения, полученный при переадресации, с кешированным одноразовым кодом и вызовите credentials:finalize, чтобы сохранить токен в хранилище.

Создание собственного клиента

Вам не нужно писать этот клиент для лабораторной работы – на следующем шаге запускается предварительно созданный клиент. При реализации этого в собственном приложении следует использовать следующие две ссылки:

8. Запустите клиент пользовательского интерфейса локально

Как показано на диаграмме 3LO Consent Flow, Auth Manager перенаправляет окно браузера обратно на клиентскую конечную точку обратного вызова. Пример клиента в хранилище adk-python размещает эту конечную точку по адресу /validateUserId. Скачайте и запустите его локально, выполнив следующие действия.

Скачайте файлы клиента

Каталог contributing/samples/integrations/gcp_auth/client в adk-python содержит три основных объекта:

  • main.py – серверная часть FastAPI, которая подключается к развернутому Agent Engine и размещает конечную точку обратного вызова /validateUserId для завершения работы с токенами OAuth.
  • static/ – файлы HTML и JavaScript для интерфейса чата в браузере.
  • requirements.txt – пакеты Python, необходимые для запуска клиентского сервера.

Поскольку adk-python – это большой репозиторий, используйте функцию sparse checkout в 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.

9. Протестируйте процесс OAuth

Теперь, когда все сервисы развернуты, привязки IAM настроены и переменные среды заданы, вы готовы протестировать безопасный сквозной процесс авторизации, делегированной пользователем.

Шаг А. Запустите выполнение инструмента

  1. Откройте вкладку браузера и перейдите по URL клиента: http://localhost:8501.
  2. На панели слева в разделе Configuration Settings (Настройки конфигурации) для параметра Agent Type (Тип агента) выберите значение Remote Agent (Vertex AI) (или Remote Agent Engine).
  3. Укажите идентификатор проекта Google Cloud и местоположение (us-central1), а затем нажмите Загрузить удаленные агенты. Загрузятся агенты, развернутые в вашем проекте.
  4. В раскрывающемся списке Select Engine (Выбрать систему) выберите развернутый агент app и нажмите Save & Apply Settings (Сохранить и применить настройки).
  5. В окне чата введите целевой запрос, например "Покажи мои недавние проблемы" или "Покажи мои недавние репозитории".
    Get the last 2 GitHub issues reported against my name
    
    (или "List my 3 most recently updated repositories") и нажмите Ввод.
  6. Посмотрите на интерфейс чата. Поскольку у агента ещё нет учетных данных для вашего сеанса пользователя, он получает запрос на аутентификацию и показывает в цепочке чата карточку "Требуется аутентификация".
  1. Откроется отдельное всплывающее окно браузера, в котором вы будете перенаправлены через Google Cloud Auth Manager на страницу авторизации GitHub OAuth.
  2. Проверьте запрашиваемые разрешения и нажмите Авторизовать.
  3. GitHub перенаправит вас обратно в Google Cloud, который перенаправит всплывающее окно на ваш localhostURL обратного вызова/validateUserId.
  4. Сервис обратного вызова обрабатывает и завершает рукопожатие учетных данных.

Шаг В. Возобновите работу

  1. Когда всплывающее окно закрывается, родительская вкладка чата автоматически обнаруживает это.
  2. Фронтенд отправляет агенту полезную нагрузку для возобновления.
  3. Агент безопасно получает новый токен из Google Cloud Auth Manager, вызывает инструменты MCP GitHub от вашего имени и передает данные GitHub прямо в окно чата. Без этого агент не смог бы получить доступ к данным.

Шаг 4. Проверьте журналы Cloud

Чтобы убедиться, что обмен токенами и завершение процесса были выполнены безопасно:

  1. Перейдите в Logs Explorer в консоли 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 Runtime Console.
    • Выберите развернутого агента из списка.
    • Перейдите на вкладку 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), запуская процесс получения согласия 3-legged OAuth (3LO).
  • Безопасная интеграция инструментов. Как подключить агентов ADK к серверам Model Context Protocol (MCP) с помощью Google Cloud Auth Manager, чтобы динамически получать токены пользователей вместо использования жестко закодированных секретов.
  • Настройка правил IAM. Как настроить точные привязки разрешений, чтобы авторизовать как идентификатор среды выполнения агента, так и ваш собственный аккаунт у поставщика аутентификации.

Дополнительные ресурсы