Tworzenie integracji z agentem AI i umiejętnościami agenta Application Integration

1. Wprowadzenie

W tym module utworzysz integrację Application Integration, opisując ją agentowi AI. Zainstalujesz 3 publiczne umiejętności agenta Application Integration z repozytorium google/skills, a następnie użyjesz interfejsu wiersza poleceń Gemini, aby napisać, przesłać, opublikować i uruchomić niewielką przykładową integrację.

Przykładowy model sample-claims-adjudication przyjmuje roszczenie ubezpieczeniowe i zwraca APPROVE, REVIEW lub DENY.

Jakie zadania wykonasz

  • skonfigurować Application Integration w projekcie Google Cloud,
  • Zainstaluj umiejętności agenta Application Integration.
  • Użyj interfejsu wiersza poleceń Gemini, aby utworzyć, przesłać, opublikować i uruchomić integrację.
  • Samodzielnie sprawdź wykonanie i poproś agenta o rozwiązanie problemu.
  • Usuń dane z przykładowej integracji.

Czego się nauczysz

  • Jakie umiejętności dają agentowi application-integration-basics, -authoring i -troubleshooting.
  • Jak sprawdzić plik JSON wersji integracji i polecenia, które agent uruchamia, zanim je zatwierdzisz.
  • Jak odczytać rekord wykonania.

2. Konfigurowanie projektu

  1. Jeśli nie masz jeszcze konta Google, musisz je utworzyć.
    • Użyj konta osobistego zamiast służbowego lub szkolnego. Konta służbowe i szkolne mogą mieć ograniczenia, które uniemożliwiają włączenie interfejsów API potrzebnych w tym module.
  2. Zaloguj się w konsoli Google Cloud.
  3. Włącz płatności w konsoli Cloud.
  4. Utwórz nowy projekt lub wybierz istniejący projekt.
    • Jeśli pojawi się błąd dotyczący limitu projektów, użyj istniejącego projektu lub usuń istniejący projekt, aby utworzyć nowy.

Użyj nowego projektu lub istniejącego projektu, w którym możesz bezpiecznie eksperymentować, a nie projektu produkcyjnego. Agent przesyła, publikuje i uruchamia integracje w tym folderze, używając Twoich danych logowania.

3. Otwórz edytor Cloud Shell

  1. Kliknij ten link, aby przejść bezpośrednio do edytora Cloud Shell.
  2. Jeśli w którymś momencie pojawi się prośba o autoryzację, kliknij Autoryzuj, aby przejść dalej. Kliknij, aby uwierzytelnić się w Cloud Shell
  3. Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
    • Kliknij Wyświetl.
    • Kliknij TerminalOtwieranie nowego terminala w edytorze Cloud Shell.
  4. W terminalu ustaw projekt za pomocą tego polecenia:
    • Format:
      gcloud config set project [PROJECT_ID]
      
    • Przykład:
      gcloud config set project lab-project-id-example
      
    • Jeśli nie pamiętasz identyfikatora projektu:
      • Aby wyświetlić listę wszystkich identyfikatorów projektów, użyj polecenia:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Ustawianie identyfikatora projektu w terminalu edytora Cloud Shell
  5. Powinien wyświetlić się ten komunikat:
    Updated property [core/project].
    
    Jeśli widzisz WARNING i prośbę Do you want to continue (Y/n)?, prawdopodobnie identyfikator projektu został wpisany nieprawidłowo. Naciśnij n, a następnie Enter i spróbuj ponownie uruchomić polecenie gcloud config set project.

4. Konfigurowanie Application Integration

Usługa Application Integration działa regionalnie, więc konfigurujesz ją w jednym regionie. W tym module używamy us-central1.

  1. Zanotuj identyfikator projektu, ponieważ później trzeba będzie go wkleić w odpowiedzi na prompt:
    gcloud config get-value project
    
  2. Włącz interfejs Application Integration API:
    gcloud services enable integrations.googleapis.com
    
  3. W konsoli Google Cloud otwórz stronę Application Integration i wybierz swój projekt.
  4. Na stronie Przegląd wybierz region us-central1 i kliknij Szybka konfiguracja. Po zakończeniu konfiguracji w konsoli pojawi się lista Integracje. Jeśli używasz ponownie projektu, przed kliknięciem Szybka konfiguracja sprawdź, czy masz role wymienione w sekcji Konfigurowanie Application Integration.

Więcej informacji znajdziesz w artykule Konfigurowanie Application Integration.

5. Instalowanie umiejętności agenta

Umiejętności dają agentowi wiedzę o Application Integration:

  • application-integration-basics: pojęcia, włączanie interfejsów API, udostępnianie regionu, role uprawnień i limity.
  • application-integration-authoring: zapisywanie wersji integracji jako JSON oraz ich przesyłanie, publikowanie i uruchamianie.
  • application-integration-troubleshooting: diagnozowanie nieudanych, zablokowanych lub cichych uruchomień.
  1. Utwórz katalog na potrzeby tego modułu i przejdź do niego:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Zainstaluj 3 umiejętności:
    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
    
    W przypadku każdej umiejętności instalator zadaje kilka pytań. Interfejs wiersza poleceń Gemini jest uwzględniony w domyślnej opcji Universal (.agents/skills), więc naciśnij Enter, aby go zachować, wybierz Project jako zakres instalacji i potwierdź instalację.

Umiejętności są teraz w języku ~/appint-agent-lab/.agents/skills.

6. Uruchom interfejs wiersza poleceń Gemini

  1. Uruchom interfejs wiersza poleceń Gemini z katalogu modułu:
    gemini
    
    Gdy interfejs wiersza poleceń Gemini zapyta, czy ufasz temu folderowi, wybierz Ufaj folderowi. Interfejs wiersza poleceń Gemini wczytuje umiejętności z folderu projektu dopiero po oznaczeniu go jako zaufanego, a następnie uruchamia się ponownie. Jeśli nie uruchomi się ponownie, otwórz nowy terminal, przejdź do ~/appint-agent-lab i ponownie uruchom gemini. Może być konieczne naciśnięcie Enter, aby zaakceptować niektóre ustawienia domyślne.
  2. Wyświetl listę umiejętności, których może używać interfejs wiersza poleceń Gemini:
    /skills
    
    Na liście powinny być widoczne 3 umiejętności application-integration-*.

7. Tworzenie, publikowanie i uruchamianie integracji

  1. Wklej tego prompta do interfejsu wiersza poleceń Gemini. Zastąp PROJECT_ID identyfikatorem projektu zanotowanym w sekcji Konfigurowanie 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. Gdy agent po raz pierwszy użyje umiejętności, interfejs wiersza poleceń Gemini poprosi Cię o jej aktywowanie. Zezwól na to.
  3. Agent zapisuje plik wersji integracji, np. sample-claims-adjudication.json. Zawiera on wyzwalacz (triggerConfigs), zadania (taskConfigs) i zmienne (integrationParameters). Przeczytaj go i poproś agenta o wyjaśnienie wszystkiego, czego nie rozumiesz. Sprawdź na przykład, czy agent włączył usługę Cloud Logging (cloudLoggingDetails.enableCloudLogging), co może zwiększyć koszty. Aby ją wyłączyć, ustaw enableCloudLogging na false i usuń cloudLoggingSeverity.
  4. Zatwierdź polecenia. Interfejs wiersza poleceń Gemini pyta przed uruchomieniem każdego polecenia, w tym poleceń tylko do odczytu. Umiejętności informują też agenta, że ma pokazać Ci dokładne polecenie lub prośbę, zanim coś zmieni, np. prześle, opublikuje lub uruchomi integrację. Jeśli agent prosi o zatwierdzenie bez wyświetlania polecenia, poproś go o jego wyświetlenie. Przed zatwierdzeniem sprawdź projekt, region i nazwę integracji, a następnie odrzuć polecenia, które odczytują lub zmieniają integracje, które nie należą do Ciebie.

Po zatwierdzeniu agent przesyła plik JSON jako nową wersję (versions.upload), publikuje go (versions.publish) i uruchamia za pomocą aktywatora interfejsu API (integrations.execute). Następnie wyświetla decyzję, uzasadnienie i identyfikator wykonania.

8. Sprawdzanie wykonania

samodzielnie uruchomić opublikowaną integrację i odczytać jej rekord wykonania.

  1. Otwórz nową kartę terminala Cloud Shell, przejdź do katalogu modułu i zapisz identyfikator projektu oraz region w zmiennych:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Uruchom integrację z roszczeniem powyżej 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"
    
    Odpowiedź zawiera executionId i outputParameters z decision ustawionym na REVIEW.
  3. Odczytaj rekord wykonania. Zastąp EXECUTION_ID wartością executionId z odpowiedzi:
    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"
    
    W odpowiedzi executionDetails.state to SUCCEEDED, a executionDetails.executionSnapshots pokazuje stan każdego zadania.

Uruchomienie możesz też zobaczyć w logach wykonywania w konsoli Google Cloud.

9. Rozwiązywanie problemów

Odpowiedź informująca o powodzeniu nie zawsze oznacza, że każde zadanie zostało wykonane zgodnie z oczekiwaniami. Poproś agenta o sprawdzenie wykonania. W interfejsie wiersza poleceń Gemini wpisz tego prompta, zastępując EXECUTION_ID:

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

Agent odczytuje rekord wykonania za pomocą executions.list, filtrowany według identyfikatora wykonania, i podsumowuje stan uruchomienia oraz każdego zadania.

Jeśli podczas wykonywania tego modułu coś pójdzie nie tak, sprawdź te typowe przyczyny:

  • /skills nie zawiera umiejętności związanych z Application Integration. Uruchom interfejs wiersza poleceń Gemini z ~/appint-agent-lab i oznacz folder jako zaufany.
  • Połączenie nie powiodło się i wyświetla się błąd PERMISSION_DENIED. Sprawdź, czy używasz właściwego projektu i czy masz w nim rolę Edytujący integrację aplikacji (roles/integrations.integrationEditor).
  • Uruchomienie integracji kończy się błędem No integrations found for the requested trigger_id. Sprawdź, czy projekt i region w żądaniu są zgodne z miejscem opublikowania integracji, czy triggerId to api_trigger/adjudicate_claim i czy wersja integracji jest opublikowana. Ten sam błąd występuje, jeśli prześlesz wersję, ale jej nie opublikujesz.

10. Czyszczenie danych

  1. W interfejsie wiersza poleceń Gemini poproś agenta o usunięcie przykładowej integracji:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    Gdy zatwierdzisz, agent cofnie publikację opublikowanej wersji (versions.unpublish) i usunie każdą wersję (versions.delete). Gdy nie pozostaną żadne wersje, integracja nie będzie już widoczna na liście integracji.Jeśli projekt został utworzony tylko na potrzeby tego modułu, możesz go usunąć zamiast usuwać integrację. Uruchom to polecenie na karcie terminala otwartej w sekcji Weryfikowanie wykonania:
    gcloud projects delete $(gcloud config get-value project)
    
  2. Wpisz /quit i naciśnij Enter, aby zamknąć interfejs wiersza poleceń Gemini.
  3. Usuń katalog modułu:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. Gratulacje

Udało Ci się utworzyć, opublikować, uruchomić i sprawdzić integrację, prosząc agenta AI o wykorzystanie umiejętności agenta Application Integration.

Co dalej?