Как создать интеграцию с ИИ-агентом и навыками агента Application Integration

1. Введение

В этой лабораторной работе вы создадите интеграцию Application Integration, описав ее ИИ-агенту. Вы устанавливаете три общедоступных навыка агента Application Integration из репозитория google/skills, а затем просите Gemini CLI написать, загрузить, опубликовать и запустить небольшую тестовую интеграцию.

Пример sample-claims-adjudication принимает страховое требование и возвращает APPROVE, REVIEW или DENY.

Что вам предстоит сделать

  • Настройте Application Integration в проекте Google Cloud.
  • Установите навыки агента Application Integration.
  • Попросите Gemini CLI создать, загрузить, опубликовать и запустить интеграцию.
  • Проверьте выполнение самостоятельно и попросите агента устранить неполадки.
  • Удалите пример интеграции.

Что вы узнаете

  • Что дают агенту навыки application-integration-basics, -authoring и -troubleshooting.
  • Как проверить JSON-код версии интеграции и команды, которые выполняет агент, прежде чем одобрить их.
  • Как читать запись о выполнении.

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

  1. Если у вас нет аккаунта Google, создайте его.
    • Используйте личный аккаунт вместо рабочего или учебного. В рабочих и учебных аккаунтах могут быть ограничения, которые не позволят вам включить API, необходимые для этой лабораторной работы.
  2. Войдите в консоль Google Cloud.
  3. Включите оплату в Cloud Console.
  4. Создайте новый проект или выберите существующий.
    • Если вы видите ошибку, связанную с квотой на проекты, используйте существующий проект или удалите его, чтобы создать новый.

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

3. Открыть редактор Cloud Shell

  1. Нажмите на эту ссылку, чтобы перейти в редактор Cloud Shell.
  2. Если в какой-то момент вам будет предложено авторизоваться, нажмите Авторизоваться, чтобы продолжить. Нажмите, чтобы авторизовать Cloud Shell
  3. Если терминал не появился внизу экрана, откройте его:
    • Нажмите Вид.
    • Выберите Терминал.Открыть новый терминал в редакторе Cloud Shell
  4. В терминале задайте проект с помощью следующей команды:
    • Формат:
      gcloud config set project [PROJECT_ID]
      
    • Пример:
      gcloud config set project lab-project-id-example
      
    • Если вы не помните идентификатор проекта:
      • Чтобы посмотреть список всех идентификаторов проектов, выполните следующую команду:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Как задать идентификатор проекта в терминале редактора Cloud Shell
  5. Вы увидите следующее сообщение:
    Updated property [core/project].
    
    Если вы видите сообщение WARNING и вопрос Do you want to continue (Y/n)?, то, скорее всего, вы неправильно указали идентификатор проекта. Нажмите n, затем Enter и попробуйте снова выполнить команду gcloud config set project.

4. Настройте Application Integration

Application Integration – это региональный сервис, поэтому его нужно настраивать в одном регионе. В этой лабораторной работе используется us-central1.

  1. Запишите идентификатор проекта. Позже вы вставите его в запрос.
    gcloud config get-value project
    
  2. Включите Application Integration API:
    gcloud services enable integrations.googleapis.com
    
  3. Перейдите на страницу Application Integration в консоли Google Cloud и выберите проект.
  4. На странице Обзор выберите регион us-central1 и нажмите Быстрая настройка. После завершения настройки в консоли появится список Интеграции. Если вы используете проект повторно, убедитесь, что у вас есть роли, перечисленные в разделе Настройка Application Integration, прежде чем нажимать Быстрая настройка.

Подробнее о том, как настроить Application Integration…

5. Установите навыки агента

Навыки дают агенту знания об Application Integration:

  • application-integration-basics: основные понятия, включение API, инициализация региона, роли IAM и ограничения.
  • application-integration-authoring: запись версий интеграции в формате JSON, их загрузка, публикация и запуск.
  • application-integration-troubleshooting: диагностика сбоев, зависаний и отсутствия ответа.
  1. Создайте каталог для этой лабораторной работы и перейдите в него:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Установите три навыка:
    npx skills add google/skills --skill application-integration-basics
    npx skills add google/skills --skill application-integration-authoring
    npx skills add google/skills --skill application-integration-troubleshooting
    
    Для каждого навыка установщик задает несколько вопросов. Gemini CLI входит в вариант по умолчанию Universal (.agents/skills), поэтому нажмите Enter, чтобы оставить его, выберите Project в качестве области установки и подтвердите установку.

Навыки теперь доступны в ~/appint-agent-lab/.agents/skills.

6. Как запустить Gemini CLI

  1. Запустите Gemini CLI из каталога практического занятия:
    gemini
    
    Когда Gemini CLI спросит, доверяете ли вы этой папке, выберите Trust folder (Доверять папке). Gemini CLI загружает навыки из папки проекта только после того, как вы подтвердите, что доверяете ей, а затем перезапускается. Если этого не произошло, откройте новое окно терминала, перейдите в каталог ~/appint-agent-lab и снова выполните команду gemini. Чтобы принять некоторые настройки по умолчанию, может потребоваться нажать Enter.
  2. Показать список навыков, которые может использовать Gemini CLI:
    /skills
    
    В списке должны появиться три навыка application-integration-*.

7. Как создать, опубликовать и запустить интеграцию

  1. Вставьте этот запрос в Gemini CLI. Замените PROJECT_ID идентификатором проекта, который вы записали в разделе Настройка Application Integration.
    Using the Application Integration skills, build an integration named
    sample-claims-adjudication in project PROJECT_ID, region us-central1.
    
    - Start it with an API trigger named adjudicate_claim.
    - Inputs: claimId (string), claimAmount (double), policyActive (boolean).
    - Outputs: decision (string) and reason (string).
    - Rules: if policyActive is false, return DENY. If claimAmount is 1000 or less,
      return APPROVE. Otherwise, return REVIEW. Set reason to a short explanation.
    - Save the integration version JSON in this directory so I can review it.
    - Show me every command before you run it, then upload, publish, and run it
      once with a sample claim.
    
  2. Когда агент впервые использует навык, Gemini CLI попросит вас активировать его. Разрешить.
  3. Агент записывает файл версии интеграции, например sample-claims-adjudication.json. В нем содержатся триггер (triggerConfigs), задачи (taskConfigs) и переменные (integrationParameters). Прочитайте его и попросите агента объяснить все, что вам непонятно. Например, проверьте, включил ли агент Cloud Logging (cloudLoggingDetails.enableCloudLogging), за который может взиматься плата. Чтобы отключить его, задайте для enableCloudLogging значение false и удалите cloudLoggingSeverity.
  4. Одобрите команды. Gemini CLI запрашивает разрешение перед выполнением каждой команды, включая команды только для чтения. Навыки также указывают агенту показывать вам точную команду или запрос, прежде чем что-либо менять, например загружать, публиковать или запускать интеграцию. Если агент запрашивает одобрение, не показывая команду, попросите его показать ее. Прежде чем одобрить команду, проверьте проект, регион и название интеграции. Отклоняйте команды, которые считывают или изменяют не ваши интеграции.

После вашего одобрения агент загружает JSON-файл как новую версию (versions.upload), публикует его (versions.publish) и запускает через триггер API (integrations.execute). Затем он показывает вам решение, причину и идентификатор выполнения.

8. Проверьте выполнение

Запустите опубликованную интеграцию и прочитайте запись о ее выполнении.

  1. Откройте новую вкладку терминала Cloud Shell, перейдите в каталог практической работы и сохраните идентификатор проекта и регион в переменных:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Запустите интеграцию с заявкой, в которой указано более 1000:
    curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
          "triggerId": "api_trigger/adjudicate_claim",
          "inputParameters": {
            "claimId": {"stringValue": "CLM-1001"},
            "claimAmount": {"doubleValue": 2500},
            "policyActive": {"booleanValue": true}
          }
        }' \
        "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication:execute"
    
    Ответ содержит executionId и outputParameters, в котором для decision задано значение REVIEW.
  3. Прочитайте запись о выполнении. Замените EXECUTION_ID на executionId из ответа:
    curl -G \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        --data-urlencode 'filter=execution_id="EXECUTION_ID"' \
        "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication/executions"
    
    В ответе executionDetails.state – это SUCCEEDED, а executionDetails.executionSnapshots показывает статус каждой задачи.

Вы также можете посмотреть запуск в журналах выполнения в консоли Google Cloud.

9. Устранение неполадок

Успешный ответ не всегда означает, что каждая задача выполнена так, как вы ожидали. Попросите агента проверить выполнение. В Gemini CLI введите следующий запрос, заменив EXECUTION_ID:

Check execution EXECUTION_ID of sample-claims-adjudication. Did every task
succeed? If anything failed, tell me why and propose a fix.

Агент считывает запись о выполнении с помощью executions.list, отфильтрованную по идентификатору выполнения, и обобщает состояние выполнения и каждой задачи.

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

  • /skills не перечисляет навыки Application Integration. Запустите Gemini CLI из папки ~/appint-agent-lab и добавьте ее в доверенные.
  • Вызов завершается ошибкой PERMISSION_DENIED. Убедитесь, что вы используете нужный проект и у вас есть роль редактора Application Integration (roles/integrations.integrationEditor).
  • При запуске интеграции возникает ошибка No integrations found for the requested trigger_id. Убедитесь, что проект и регион в запросе соответствуют месту публикации интеграции, что triggerId – это api_trigger/adjudicate_claim и что версия интеграции опубликована. Такая же ошибка возникает, если вы загрузили версию, но не опубликовали ее.

10. Организовать

  1. В Gemini CLI попросите агента удалить пример интеграции:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    После того как вы подтвердите действие, агент отменит публикацию опубликованной версии (versions.unpublish) и удалит все версии (versions.delete). Когда версий не останется, интеграция исчезнет из списка.Если вы создали проект только для этой лаборатории, то можете удалить его, а не интеграцию. Выполните эту команду на вкладке терминала, которую вы открыли в разделе Проверка выполнения:
    gcloud projects delete $(gcloud config get-value project)
    
  2. Введите /quit и нажмите Enter, чтобы выйти из Gemini CLI.
  3. Удалите каталог практической работы:
    cd ~ && rm -rf ~/appint-agent-lab
    

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

Вы создали, опубликовали, запустили и проверили интеграцию, отправив запрос ИИ-агенту с навыками агента Application Integration.

Дальнейшие действия