Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

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

1. Введение

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

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

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

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

Архитектура с двумя идентификаторами

Вы научитесь:

Создайте агента ADK, который подключается к серверу Model Context Protocol (MCP) GitHub.
Обновите инструмент агента, заменив статический персональный токен доступа GitHub на трехсторонний протокол OAuth (3LO) с помощью менеджера аутентификации Google Cloud.
Безопасно разверните агента в Agent Runtime и инициализируйте идентификацию агента.
Настройте роли IAM, чтобы предоставить агенту доступ к хранилищу токенов от имени пользователя.
Изучите сквозной процесс 3LO для Менеджера авторизации в 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 из локальной командной строки, чтобы убедиться, что у вашей среды есть необходимые разрешения для развертывания в среде выполнения агента, инициализации идентификатора агента и настройки менеджера аутентификации во время этой лабораторной работы:

Выполните следующие команды, чтобы войти в аккаунт Google Cloud и настроить учетные данные по умолчанию для приложений (ADC):

gcloud auth login
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).

Создание начальной структуры проекта. Сначала вы создадите локальный прототип, а затем улучшите его для развертывания в среде выполнения агента:

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

Будет создана директория secure-agent-demo, содержащая основной код агента, зависимости и тестовые файлы.

4. Добавьте необходимые дополнительные параметры ADK

Сгенерированный файл 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

3. Как создать и протестировать агента

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

В этом файле определены три ключевых компонента агента:

Системная инструкция (INSTRUCTION). Определяет личность, ограничивает область применения помощника до GitHub Triage и обеспечивает соблюдение строгих правил безопасности (например, доступ только для чтения и подсказки пользователям о необходимости аутентификации при возникновении ошибок).
Конфигурация агента (root_agent): создает экземпляр ADK Agent с помощью модели gemini-3.8-flash, настраивает логику повторных попыток HTTP и оснащает агента набором инструментов GitHub.
Контейнер приложения (app). Позволяет поместить корневого агента в контейнер ADK App, чтобы его можно было развернуть в среде выполнения агента.

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 в качестве токена носителя и применяет режим только для чтения (X-MCP-Readonly: true) непосредственно на транспортном уровне.

3. Как протестировать локально с помощью персонального токена доступа GitHub

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

Создайте личный токен доступа GitHub. Предоставьте ему доступ для чтения к своим репозиториям, иначе агент сможет видеть только общедоступные данные, и приведенный ниже запрос не вернет никаких результатов.
Установите его в своей среде:
```
export GITHUB_TOKEN="your_github_pat_here"
```
Перейдите в папку secure-agent-demo. Запущено:
```
cd secure-agent-demo
agents-cli playground
```
Откройте интерфейс песочницы и выберите в раскрывающемся меню папку app. В окне чата введите "Fetch my contributions across my private repositories over the last 6 months" и убедитесь, что агент вызывает инструмент GitHub и возвращает данные из ваших частных репозиториев.

4. Как настроить Менеджер аутентификации

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

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

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

Рабочий процесс Auth Manager

Динамическое перехватывание согласия. Когда агент пытается выполнить действие с помощью инструмента от имени пользователя, ADK проверяет, есть ли в Менеджере аутентификации действительные учетные данные. Если такого файла cookie нет, Менеджер авторизации возвращает URL авторизации, чтобы инициировать процесс запроса согласия OAuth с тремя этапами.
Безопасное хранилище Сейфа. После того как конечный пользователь авторизует приложение, Менеджер авторизации автоматически перехватывает обратный вызов OAuth и сохраняет полученные токены доступа и обновления в безопасном хранилище учетных данных, управляемом Google.
Автоматическое управление жизненным циклом токена. Менеджер авторизации полностью управляет истечением срока действия и ротацией токенов в фоновом режиме, избавляя от необходимости вручную обновлять токены или допускать простои.
Выполнение инструмента без секретного кода. Для последующих действий агент (прошедший аутентификацию с помощью идентификатора агента SPIFFE) динамически запрашивает у Менеджера авторизации делегированный токен доступа пользователя во время выполнения, благодаря чему код клиента и агента не содержит секретных кодов.

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

Выполните следующую команду gcloud, чтобы создать поставщика аутентификации GitHub в облачном проекте Google Cloud. Идентификатор и секретный код клиента вы укажете позже. 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

Перейдите на страницу настроек разработчика GitHub и нажмите Register a new OAuth app (Зарегистрировать новое приложение OAuth).
В поле URL главной страницы введите URL клиентской части приложения, например http://localhost:8501 для локального прототипирования. Позже вы сможете изменить его на URL, используемый в рабочей среде.
В поле URI переадресации укажите значение redirectUrl, полученное на предыдущем шаге.
Нажмите Register application (Зарегистрировать приложение), а затем Generate a new client secret (Создать новый секретный код клиента) и сохраните идентификатор и секретный код клиента.

Шаг В. Добавьте учетные данные 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 будет выступать в качестве безопасного хранилища, обрабатывающего согласие и жизненные циклы токенов.

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

6. Как развернуть агента в Agent Runtime

Теперь, когда мы обновили инструмент MCP GitHub, чтобы использовать вместо него менеджер аутентификации, следующий шаг – развернуть агент в среде выполнения агента. При развертывании с включенной идентификацией агента для него будет создан уникальный идентификатор 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, которое принадлежит этому развертыванию и используется агентом для аутентификации в Менеджере авторизации и других сервисах 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"

На создание и загрузку контейнера уходит несколько минут. После этого интерфейс командной строки выведет название развернутого ресурса. Запишите значение reasoningEngines/ENGINE_ID, так как оно понадобится вам для авторизации агента и указания на него в клиентском интерфейсе.

Куда переходит пользователь после предоставления согласия. После того как пользователь предоставит согласие, его браузер будет перенаправлен на адрес в OAUTH_CONTINUE_URI, который обслуживается вашим клиентским приложением. В этой лаборатории клиент работает на вашем компьютере, поэтому агент использует значение по умолчанию, уже заданное в app/tools.py (http://localhost:8501/validateUserId), и вам ничего не нужно менять. Если вы позже разместите клиентское приложение в другом месте, обновите значение по умолчанию перед развертыванием.

Как авторизовать идентификатор агента

Теперь, когда агент работает в облаке, ему нужно разрешение на доступ к учетным данным, хранящимся в Менеджере аутентификации. По умолчанию у идентификатора SPIFFE агента нет доступа к внешним облачным ресурсам.

Выполните следующую команду 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"

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

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

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

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

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

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

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

Основные обязанности клиента в рамках соглашения

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

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

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

Обновите приложение на стороне клиента, следуя инструкциям в документации по Менеджеру авторизации. В ней рассказывается, как обрабатывать запрос согласия и вызывать credentials:finalize.
Запускаемый образец клиента в репозитории adk-python. Полную реализацию трех описанных выше обязанностей можно найти в main.py.

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

Как мы показали на диаграмме последовательности 3LO Consent Flow, Менеджер авторизации должен перенаправить всплывающее окно браузера обратно в клиентскую конечную точку обратного вызова. В примере клиента эта конечная точка размещена по адресу /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

Как запустить клиент

Перейдите в папку client, которую вы только что скопировали:
```
cd adk-python/contributing/samples/integrations/gcp_auth/client
```
Создайте виртуальную среду и установите зависимости клиента. В папке есть 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
```

Укажите клиенту на развернутого агента и запустите его на порту 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

Убедитесь, что сервер успешно запущен и прослушивает порт http://localhost:8501.

9. Как протестировать процесс OAuth

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

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

Откройте вкладку браузера и перейдите по URL клиента: http://localhost:8501.
На панели слева выберите тип агента Remote Agent Engine.
Укажите проект Google Cloud и местоположение. Нажмите на значок Load Remote Agents. После этого должны загрузиться все агенты, развернутые в вашем проекте.
Выберите нужного агента в раскрывающемся списке и сохраните настройки.

В окне чата введите:

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

и нажмите Ввод.

Посмотрите на интерфейс чата. Поскольку у агента ещё нет учетных данных для сеанса пользователя, он получает запрос на аутентификацию и показывает карточку "Требуется аутентификация" в цепочке сообщений.

Откроется отдельное всплывающее окно браузера, которое перенаправит вас через менеджер аутентификации Google Cloud на страницу авторизации OAuth GitHub.
Проверьте запрашиваемые разрешения и нажмите Авторизовать.
GitHub перенаправит вас обратно в Google Cloud, который перенаправит всплывающее окно на ваш localhost URL обратного вызова /validateUserId.
Сервис обратного вызова обрабатывает и завершает рукопожатие учетных данных.

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

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

Шаг D. Проверьте журналы облака

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

Перейдите в Logs Explorer в консоли Google Cloud.
Найдите в журналах сервера подтверждение извлечения и успешной проверки одноразового кода:
```
INFO:secure-agent-client:Caching consent nonce for session_id: session-xxxxxxx
INFO:secure-agent-client:Successfully finalized auth provider credentials.
```
Проверка журналов выполнения агента. Вы также можете просматривать журналы выполнения непосредственно в консоли платформы агента:
- Перейдите в консоль 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

Как удалить локальные файлы

Чтобы полностью очистить локальную среду, выполните следующие действия:

Остановите локальный сервер uvicorn, нажав Ctrl+C в терминале, где он запущен.
Удалите каталоги проектов, созданные во время выполнения этой лабораторной работы:

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

11. Поздравляем!

Вы успешно создали и защитили агента, который действует от имени вошедшего в аккаунт пользователя.

Что вы узнали

Системный идентификатор агента. Как агент работает под собственным идентификатором аккаунта для безопасного взаимодействия с инфраструктурой GCP, управления журналами телеметрии и вызова API для завершения работы с учетными данными.
Делегированный идентификатор пользователя. Как агент запрашивает разрешение действовать от имени пользователя на внешних платформах (например, GitHub), запуская трехэтапный процесс согласия OAuth (3LO).
Безопасная интеграция инструментов. Как подключить агентов ADK к серверам протокола Model Context Protocol (MCP) с помощью Google Cloud Auth Manager, чтобы динамически получать токены пользователей вместо использования жестко заданных секретов.
Настройка правил IAM. Как настроить точные привязки разрешений, чтобы авторизовать как идентификатор среды выполнения агента, так и собственный аккаунт у поставщика аутентификации.

Дополнительные материалы

Менеджер аутентификации идентификатора агента, чтобы узнать больше о конфигурации потока аутентификации и областях действия.
Общие сведения об Agent Runtime
Документация по ADK
Model Context Protocol