agent-platform-troubleshooting

Навык Agent Platform Troubleshooting предназначен для диагностики Google Cloud Gemini Enterprise Agent Platform. Его область — связка Agent Gateway, Agent Registry, Agent Identity, политик авторизации, Model Armor, Identity-Aware Proxy и service extensions. Карточка полезна, когда запрос агента к внешнему API завершается 403, особенно сообщением Egress request is not authorized, когда запрос Agent Runtime или ReasoningEngine возвращает 500, в логах видны ошибки авторизации или падение контейнера, а Gateway получает PERMISSION_DENIED при обращении к Model Armor. Тот же навык применим к недавно зарегистрированным агентам, MCP-серверам и endpoint, которые формально созданы, но не работают, а также к вопросам о маршрутизации Gateway, IAP, principal set и структуре Agent Registry. Работа начинается с обязательной проверки границ задачи. Общие ошибки GCE, GCS и IAM, не связанные со стеком Agent Platform, сюда не относятся. Навык отдельно запрещает писать или запускать пользовательские скрипты для обнаружения ресурсов: вместо этого предлагаются стандартные команды gcloud или REST-вызовы. Для задач регистрации Google API описан консолидированный сервис googleapis, а не множество отдельных записей. Для Cloud Run или Cloud Functions, вызываемых через MCP, проверяется схема с impersonation сервисного аккаунта и правом roles/iam.serviceAccountTokenCreator; прямой Agent Identity к Cloud Run OIDC не принимается как готовая схема. При блокировках telemetry проверяются telemetry.mtls.googleapis.com, monitoring.googleapis.com, trace.mtls.googleapis.com и cloudtrace.googleapis.com. Для IAP нужно отличать отказ IAP, проверять аудит, roles/iap.egressor и AuthorizationPolicy; роль roles/iap.tunnelResourceAccessor и обход аутентификации не являются рекомендациями этого навыка. Для PSC описана быстрая проверка в us-central1, а ручная регистрация endpoint в мульти-регионах us и eu запрещена. VPC Service Controls рассматриваются как отдельный perimeter block, который нельзя устранять отключением контроля. До диагностики фиксируется контекст: PROJECT_ID и PROJECT_NUMBER, LOCATION, идентификатор Agent Runtime или ReasoningEngine, имя Agent Gateway, identity агента, точный текст ошибки и момент её появления, а также destination, к которому обращался агент. Затем формулируется не более трёх проверяемых гипотез. Для каждой нужно связать симптом с недавним изменением конфигурации и объяснить, почему проблема началась именно сейчас. Диагностический поток разделяет вопросы проектирования и настройки от активных сбоев; активный сбой проверяется по логам агента, Gateway и IAP, состоянию Registry, привязке AuthorizationPolicy и ролям identity. Важное ограничение — навык выпускает диагностический отчёт, а не применяет исправления. В отчёте должны быть контекст, собранные доказательства, гипотеза причины, связь гипотезы с фактами, рекомендуемая проверка после исправления, неизвестные и приложения с точными именами ресурсов и проверенными ссылками. Сначала читаются reference-файлы самого навыка: field manual, known issues и материалы по Gateway, policies, Registry и identity выбираются по симптому. Принцип работы — читать доказательства, указывать точные resource names, не выполнять Terraform-изменения и деструктивные действия, не сканировать регионы без необходимости и не маскировать неизвестные данные предположениями.