AI エージェントと Application Integration エージェント スキルとの統合を構築する

1. はじめに

このラボでは、AI エージェントに説明することで、Application Integration の統合を構築します。google/skills リポジトリから 3 つの公開 Application Integration エージェント スキルをインストールし、Gemini CLI に小さなサンプル統合の作成、アップロード、公開、実行を指示します。

サンプル sample-claims-adjudication は、保険金請求を受け取り、APPROVE、REVIEW、または DENY を返します。

演習内容

  • Google Cloud プロジェクトで Application Integration を設定する。
  • Application Integration エージェント スキルをインストールします。
  • Gemini CLI にプロンプトを送信して、統合をビルド、アップロード、公開、実行する。
  • 実行を自分で確認し、エージェントにトラブルシューティングを依頼します。
  • サンプル統合をクリーンアップします。

学習内容

  • application-integration-basics、-authoring、-troubleshooting のスキルがエージェントに提供するもの。
  • 統合バージョンの JSON と、エージェントが実行するコマンドを承認前に確認する方法。
  • 実行レコードの読み方。

2. プロジェクトの設定

  1. Google アカウントをお持ちでない場合は、Google アカウントを作成する必要があります。
    • 仕事用または学校用のアカウントではなく、個人アカウントを使用してください。仕事用アカウントや学校用アカウントには、このラボに必要な API を有効にできない制限が設定されている場合があります。
  2. Google Cloud コンソールにログインします。
  3. Cloud コンソールで課金を有効にします。
    • このラボを完了するために必要な Cloud リソースの費用は 1 米ドル未満です。
    • このラボの最後の手順に沿ってリソースを削除すると、追加の請求を回避できます。
    • 新規ユーザーは、300 米ドル分の無料トライアルをご利用いただけます。
  4. 新しいプロジェクトを作成するか、既存のプロジェクトを再利用します。
    • プロジェクトの割り当てに関するエラーが表示された場合は、既存のプロジェクトを再利用するか、既存のプロジェクトを削除して新しいプロジェクトを作成します。

本番環境プロジェクトではなく、新しいプロジェクトか、安全にテストできる既存のプロジェクトを使用します。エージェントは、ユーザーの認証情報を使用して、統合をアップロード、公開、実行します。

3. Cloud Shell エディタを開く

  1. このリンクをクリックすると、Cloud Shell エディタに直接移動します。
  2. 本日、承認を求められた場合は、[承認] をクリックして続行します。クリックして Cloud Shell を承認します
  3. 画面の下部にターミナルが表示されない場合は、ターミナルを開きます。
    • [表示] をクリックします。
    • [Terminal] をクリックします。Cloud Shell エディタで新しいターミナルを開く
  4. ターミナルで、次のコマンドを使用してプロジェクトを設定します。
    • 形式:
      gcloud config set project [PROJECT_ID]
      
    • 例:
      gcloud config set project lab-project-id-example
      
    • プロジェクト ID がわからない場合は、次の操作を行います。
      • 次のコマンドを使用すると、すべてのプロジェクト ID を一覧表示できます。
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Cloud Shell エディタのターミナルでプロジェクト ID を設定する
  5. 次のようなメッセージが表示されます。
    Updated property [core/project].
    
    WARNING が表示され、Do you want to continue (Y/n)? と尋ねられた場合は、プロジェクト ID が正しく入力されていない可能性があります。n を押し、Enter を押して、gcloud config set project コマンドをもう一度実行してみます。

4. Application Integration を設定する

Application Integration はリージョン サービスであるため、1 つのリージョンに設定します。このラボでは us-central1 を使用します。

  1. プロジェクト ID をメモします。後でプロンプトに貼り付けます。
    gcloud config get-value project
    
  2. Application Integration API を有効にします。
    gcloud services enable integrations.googleapis.com
    
  3. Google Cloud コンソールで [Application Integration] ページに移動し、プロジェクトを選択します。
  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. 次の 3 つのスキルをインストールします。
    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
    
    リストに 3 つの application-integration-* スキルが表示されます。

7. 統合をビルド、公開、実行する

  1. このプロンプトを Gemini CLI に貼り付けます。PROJECT_ID は、Application Integration を設定するでメモしたプロジェクト ID に置き換えます。
    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)を介して実行します。その後、決定、理由、実行 ID が表示されます。

8. 実行を確認する

公開された統合を自分で実行し、その実行レコードを読み取ります。

  1. 新しい Cloud Shell ターミナル タブを開き、ラボのディレクトリに移動して、プロジェクト ID とリージョンを変数に保存します。
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. 1,000 を超える請求で統合を実行します。
    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 と、decision が REVIEW に設定された outputParameters が含まれます。
  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 を使用して実行レコードを読み取り、実行 ID でフィルタして、実行と各タスクの状態を要約します。

このラボで問題が発生した場合は、次の一般的な原因を確認してください。

  • /skills には、Application Integration のスキルは表示されません。~/appint-agent-lab から Gemini CLI を起動し、フォルダを信頼します。
  • 呼び出しが 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 エージェント スキルを使用して AI エージェントにプロンプトを送信することで、統合を構築、公開、実行、確認しました。

次のステップ