AI エージェントとの統合を構築する

このページでは、AI コーディング エージェントにプロンプトを入力して統合を構築する方法について説明します。統合で何を行うかを記述すると、エージェントが統合を作成し、Application Integration REST API を使用してアップロードして公開し、実行して、トラブルシューティングを支援します。例として、シンプルな保険金請求の審査統合を構築します。

エージェントは、google/skills リポジトリ内の 3 つの公開エージェント スキルから Application Integration の知識を取得します。

各スキルの参照ファイルについては、Application Integration エージェントのスキルをご覧ください。

始める前に

  1. 本番環境プロジェクトではなく、安全にテストできる Google Cloud プロジェクトを使用します。プロジェクトで課金が有効になっている必要があります。
  2. サポート対象の地域のプロジェクトで Application Integration を設定します。Application Integration の設定には、そのページに記載されている独自のロールが必要です。
  3. gcloud CLI をインストールし、gcloud auth login でログインします。エージェントは、gcloud 認証情報を使用して、またはクライアント ライブラリを使用する場合はアプリケーションのデフォルト認証情報を使用して、ユーザーとして REST API を呼び出します。エージェントがクライアント ライブラリを使用している場合は、gcloud auth application-default login の実行を求められることがあります。
  4. エージェント スキルをサポートする AI コーディング エージェントを使用します。

必要なロール

Application Integration を設定したら、統合を構築して実行するために次のロールが必要です。

統合のアップロード、公開、実行、実行の表示に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

サービス アカウント ユーザーが必要なユーザーと、その付与方法については、実行サービス アカウントにサービス アカウント ユーザーを付与するをご覧ください。

エージェント スキルをインストールする

ターミナルで次のコマンドを実行して、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

プロンプトが表示されたら、構成するエージェントとインストール スコープを選択します。エージェントがリストにない場合は、デフォルトの Universal オプションが .agents/skills にインストールされます。インストーラは、find-skills などの他のスキルも提供する場合があります。このページでは必要ありません。一部のエージェントは、プロジェクト フォルダを信頼した後にのみ、そのフォルダからスキルを読み込みます。 が利用できない場合は、Node.js をインストールします。これには が含まれています。npx後でスキルを更新するには、npx skills update を実行します。

統合について説明する

空の作業ディレクトリでエージェントを起動し、統合について説明します。トリガー、入力と出力、ルール、デプロイ先を具体的に指定します。次に例を示します。

Using the Application Integration skills, build an integration named
claims-adjudication in project PROJECT_ID, region LOCATION.

- 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.

PROJECT_ID はプロジェクト ID に置き換え、LOCATION は Application Integration を設定したリージョンに置き換えます。

プランを確認してコマンドを承認する

エージェントは、統合バージョン ファイル（claims-adjudication.json など）を書き込みます。これには、トリガー（triggerConfigs）、タスク（taskConfigs）、変数（integrationParameters）が含まれています。続行する前に、この内容を確認し、予期しないことがあればエージェントに説明を求めてください。たとえば、エージェントが Cloud Logging（cloudLoggingDetails.enableCloudLogging）を有効にしているかどうかを確認します。これにより、費用が増加する可能性があります。オフにするには、enableCloudLogging を false に設定し、cloudLoggingSeverity を削除します。

スキルは、統合や実行の一覧表示など、読み取り専用のチェックを自由に実行するようにエージェントに指示しますが、変更を加える前に、正確なコマンドまたはリクエストを表示して承認を待ちます。これには、API の有効化、IAM ポリシーの変更、統合のアップロード、公開、実行が含まれます。エージェントが正確なコマンドやリクエストを表示せずに承認を求めた場合は、それらを表示するようエージェントに依頼します。エージェント独自の権限設定により、読み取り専用のコマンドを含む各コマンドの承認を求められることもあります。承認する前に、各コマンドのプロジェクト、リージョン、統合名を確認してください。

統合をアップロード、公開、実行する

承認すると、エージェントは次の Application Integration API 呼び出しを行います。

  1. versions.upload JSON ファイルを統合の新しいバージョンとしてアップロードします。
  2. versions.publish は、そのバージョンを公開します。公開されたバージョンは ACTIVE で、以前に公開されたバージョンは公開停止されます。
  3. integrations.execute は、API トリガーを介して公開された統合を同期的に実行します。

公開された統合を自分で実行することもできます。

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/claims-adjudication:execute"

レスポンスには、executionId と、outputParameters の統合の出力変数が含まれます。

実行を確認してトラブルシューティングを行う

integrations.execute からの成功レスポンスは、すべてのタスクが想定どおりに実行されたことを意味するとは限りません。タスクの再試行戦略では、タスクが失敗した後も実行を継続できます。無視を使用すると、統合は失敗したタスクを成功として扱い、なしを使用すると、統合は代替パスを介して成功として終了できます。また、リクエストで doNotPropagateError が true に設定されている場合、エラーはエラー ステータスではなくレスポンスで返されます。エージェントに実行を確認するよう依頼します。次に例を示します。

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

エージェントは、実行 ID でフィルタされた executions.list メソッドを使用して実行レコードを読み取ります。

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/claims-adjudication/executions"

レコードには、SUCCEEDED、FAILED、SUSPENDED などの実行状態と、各タスクの状態が表示されます。 Google Cloud コンソールで実行ログを開くこともできます。Cloud Logging は、デフォルトで統合に対して無効になっています。使用するには、Cloud Logging で統合ログを表示するをご覧ください。

修正を適用するということは、新しいバージョンをアップロードして公開することを意味するため、スキルはまずエージェントに再度承認を求めるように指示します。公開後、以前のバージョンが最大 10 分間実行され続ける可能性があるため、修正をテストする前にしばらく待ってください。公開すると、以前のバージョンの一時停止中の実行（承認待ちの実行など）もキャンセルされます。

ベスト プラクティス

  • 本番環境外で開始する。非本番環境プロジェクトでビルドとテストを行い、レビュー済みの JSON ファイルをプロモートします。統合のアップロードとダウンロードをご覧ください。
  • 専用の run-as サービス アカウントを使用する。統合ごとに、専用の最小スコープのサービス アカウントを使用します。実行サービス アカウントを設定するをご覧ください。
  • シークレットを構成変数に含めない。構成変数は、書式なしテキストで保存され、エクスポートされます。代わりに、認証プロファイルまたは Secret Manager アクセス タスクを使用してください。
  • 生成された JSON を確認します。ソース管理に保持し、アップロードする前に変更内容を確認します。認証プロファイルはファイルに含まれていないため、各プロジェクトで構成します。

クリーンアップ

サンプル統合を削除するには、エージェントに次の質問をします。

Unpublish claims-adjudication, then delete every version of it.

承認すると、エージェントは公開バージョンで versions.unpublish を呼び出し、各バージョンで versions.delete を呼び出します。バージョンが残っていない場合、統合は統合のリストに表示されなくなります。統合自体を削除するには、Application Integration 管理者などのロールが必要です。編集者ロールでは削除できません。

次のステップ