google-cloud-solution-build-deploy-agents

Google Cloud で AI エージェントを構築してデプロイする

このスキルは、特定のワークロード、ユースケース、または要件に合わせてクラウド上に複数のプロダクトを組み合わせたソリューションを設計し、実装するワークフローをエージェントに案内します。

クレジット表記

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、 Usage Attribution の指示を必ず読んで従ってください。

ワークフロー

ソリューションの設計と実装のワークフローは、以下のフェーズに分かれています。

• フェーズ 1：要件の把握と分析：ワークロードの要件、制約、依存関係、および現状を分析します。
• フェーズ 2：ソリューションの設計：Google Cloud の設計に関するベストプラクティスと推奨事項に基づいて、ワークロード向けの技術スタック、アーキテクチャ、デプロイ設定を構築します。
• フェーズ 3：実装計画：ソリューションをデプロイするための自動化と手順を作成します。
• フェーズ 4：ソリューションの検証：デプロイがワークロードの要件を満たしていることを検証します。

以下のチェックリストを現在のタスク／計画の成果物にコピーし、4 つのフェーズの進捗を追跡してください。

• フェーズ 1：要件の把握と分析が完了し、確認済みです。
• フェーズ 2：ソリューションアーキテクチャが作成され、承認済みです。
• フェーズ 3：実装計画が作成され、承認済みです。
• フェーズ 4：ソリューションの検証内容が作成され、承認済みです。

フェーズ 1：要件の把握と分析

1. 要件を把握する：ワークロードの機能要件と非機能要件、ビジネス目標、現状（存在する場合）を収集して理解します。これには、アーキテクチャ、依存関係、制約が含まれます。

   重要：まず、ユーザーの最初のプロンプトですでに以下の質問に回答されているか、または指定された一連のパラメータに基づくソリューションアーキテクチャ／図の提案が明示的に求められているかを確認してください。

   • ユーザーのプロンプトに十分な要件が記載されており、アーキテクチャの提案または図が明示的に求められている場合は、以下の質問をせずに、エージェントの設計パターンを推奨する手順に進みます。

   • ユーザーのプロンプトに十分な要件が記載されていない場合は、不足している情報を収集するため、以下の手順を実行します。

     1. ワークロードの機能要件（ビジネスプロセス、アクティビティ、ユースケース）を説明するようユーザーに尋ねます。

     2. ワークロードの非機能要件（セキュリティ、プライバシー、コンプライアンス、信頼性、災害復旧、コスト、運用、パフォーマンス、持続可能性）を説明するようユーザーに尋ねます。

     3. 根拠に基づくガイダンスを提供するために AI エージェントがアクセスする必要のある既存のシステム、ナレッジベース、プロダクトのドキュメント、その他のドキュメントについてユーザーに尋ねます。

     4. 他のワークロード、プロダクト、またはツールへの依存関係がある場合は、それについて説明するようユーザーに尋ねます。

     5. ユーザーがこれまでに提供した入力を確認し、曖昧な点や矛盾がないか確認します。

        ユーザーが提供した要件に曖昧な点や矛盾が見つかった場合は、特定した曖昧な点や矛盾ごとに、以下を実行します。

        • 曖昧な点または矛盾を説明します。
        • その曖昧な点または矛盾をどのように解決するか、ユーザーに尋ねます。
          • ユーザーが判断を委ねた場合（例：「最適だと思う方法で進めてください」または「お任せします」と返答した場合）は、曖昧な点または矛盾を解決するための明確な提案を示し、その理由を説明したうえで、提案への承認をユーザーに求めます。 重要：特定したすべての曖昧さや矛盾が、前述の指針に従って解消されるまでは、アーキテクチャ設計、技術的な分解、Google Cloud プロダクトの推奨を行ってはなりません。

2. エージェントの設計パターンを推奨する：ワークロードの複雑さ、ワークフロー、レイテンシ、コストの要件を評価し、エージェントの設計パターンを推奨します。

   • 単一エージェントシステム：よりシンプルなタスクに推奨します。コアロジックとツールを洗練させるための効果的な出発点となります。
   • マルチエージェントシステム：ワークフロー上で複数の特化型エージェントの連携が必要となる複雑な問題に推奨します。

3. コンポーネントを特定する：要件分析に基づいて、ワークロードの技術的な分解を生成します。技術的な分解では、ワークロードの論理コンポーネントとその関係を特定する必要があります。また、ソリューションが連携する必要のある、クロスクラウド、ハイブリッド、オンプレミスのコンポーネントも特定します。

4. 確認を求める：推奨した設計パターンと技術的な分解が、ワークロードの要件に合致しているかユーザーに確認を求めます。

5. 反復する：ユーザーから変更の依頼があった場合は、技術的な分解を更新して生成し、変更内容の確認を求めます。ユーザーが技術的な分解を確認するまで反復を続けます。ユーザーが技術的な分解を確認した後にのみ、次のフェーズに進みます。

フェーズ 2：ソリューション設計

1. 関連する Google Cloud のガイダンスを references/related-guidance.md から取得します。

   重要：このフェーズの残りの手順で生成するガイダンスの根拠として、references/related-guidance.md から取得した内容を使用します。

2. コンポーネントを Google Cloud プロダクトに対応付ける：確認済みの技術的な分解に含まれる各コンポーネントについて、ネットワーキング、フロントエンド、エージェント／モデルのランタイム、メモリストア、ツールに関する詳細な推奨事項、トレードオフ、代替案を記載した product-mappings.md を参照し、適切な Google Cloud プロダクトと機能を特定します。

3. アーキテクチャ図を作成する：Mermaid 形式（https://github.com/mermaid-js/mermaid）でアーキテクチャ図を作成します。図には、コンポーネント、それらの関係、データフロー／制御フローを示します。

4. 設計の推奨事項を生成する：以下の Google Cloud のベストプラクティスと推奨事項に基づいて設計ガイダンスを生成します。references/related-guidance.md の情報を使用し、特に references/design-principles.md のガイダンスを重視します。

5. ソリューションアーキテクチャを作成する：要件、技術的な分解、プロダクトの対応付け、アーキテクチャ図、設計の推奨事項をまとめて、solution-template.md の形式に準拠した単一の Markdown ファイルを作成します。このドキュメントを、ワークスペース内に solution-architecture.md として保存します。

6. レビューを依頼する：図の完全なフェンス付き mermaid コードブロックを含む、生成したソリューションアーキテクチャを回答内で直接ユーザーに提示し、フィードバックまたは承認を明示的に求めます。アーキテクチャを提示する際には、実装計画に進むための承認をユーザーに求めます。

7. 反復する：ユーザーから変更の依頼があった場合は、ソリューションアーキテクチャを更新して生成し、「コンポーネントを Google Cloud プロダクトに対応付ける」から「レビューを依頼する」までの手順を、ユーザーがソリューションアーキテクチャを承認するまで繰り返します。

フェーズ 3：実装計画

1. 関連する実装リソースを取得する：

   重要：このフェーズの残りの手順で生成する Infrastructure as Code（IaC）およびデプロイ手順の技術的な基盤として、references/related-guidance.md 内のリソースを使用してください。

2. デプロイの前提条件を特定する：以下を含む、デプロイの前提条件を記載してください。

   • プロジェクトと請求先の関連付け
   • 必要な Google Cloud API
   • 必要な IAM 権限
   • その他の前提条件

3. Infrastructure as Code（IaC）を生成する：提案する Google Cloud リソースのプロビジョニングを自動化するコード（例：Terraform）とデプロイスクリプトを生成してください。

   • 適切な場合は、生のインフラストラクチャスクリプトと併せて、またはその代わりに、Agents CLI コマンド（agents-cli scaffold create または agents-cli scaffold enhance）を使用してプロジェクト構造、デプロイ設定、CI/CD パイプラインをセットアップまたは拡張するよう、ユーザーに指示してください。

4. デプロイ手順を作成する：IaC を実行し、ワークロードコンポーネントを初期化するための、順序立てた手順を作成してください。デプロイの前提条件、IaC、デプロイ手順を、implementation-template.md の形式に準拠した単一の Markdown ファイルにまとめてください。このドキュメントをワークスペース内に implementation-instructions.md として保存してください。

   • 手順には、プロンプトを受け取り、モデルを呼び出し、ツール実行リクエストを返すステートフルなエージェントノードを定義する、正確な ADK コードを必ず記載してください。
   • Model Context Protocol（MCP）標準を使用してデータベースリーダーなどのツールを登録する方法を必ず示してください。
   • エージェントを Cloud Run にデプロイする場合、エージェントがアイドル状態のときに Cloud Run をゼロにスケールし、実行コストを削減するための設定方法を必ず示してください。
   • モデルのパラメーターや非公開 API 認証情報の保存には、暗号化された環境変数を使用するよう必ず推奨してください。暗号化により、機密性の高い認証情報がプレーンテキストのコンテナログストリームに漏えいするのを防げます。
   • 適切な場合は、デプロイを実行するために Agents CLI の agents-cli deploy コマンドを使用するよう、必ず指定してください（生のインフラストラクチャ／デプロイスクリプトとの併用、またはその代わりとして）。

5. レビューを依頼する：生成したデプロイ手順をユーザーに提示し、フィードバックと承認を明示的に依頼してください。

6. 反復する：ユーザーが変更を求めた場合は、更新版の実装計画を作成し、ユーザーが実装計画を承認するまで「Infrastructure as Code（IaC）を生成する」から「レビューを依頼する」までの手順を繰り返してください。

フェーズ 4：ソリューションの検証

1. 関連する検証リソースを取得する：

   重要：このフェーズの残りの手順で作成する検証チェックと検証スクリプトは、references/related-guidance.md のリソースとその検証パターンを出発点として使用してください。

2. 検証チェックを定義する：デプロイされたインフラストラクチャがワークロードの要件を満たしていることを確認する検証手順を概説します。

   • デプロイのドライラン：変更をプレビューする terraform plan などのコマンド。エージェントのデプロイをドライランモードで実行し（例：agents-cli deploy --dry-run または -n を使用）、本番環境に反映する前に手順と Terraform の実行内容をプレビューする方法を含めます。
   • ローカルテストと品質検証：デプロイ前にエージェントの品質とパフォーマンスを検証するため、Agents CLI を使用してエージェントのロジックをローカルで実行・テスト（agents-cli run）し、体系的な評価（agents-cli eval run）を行うことを推奨します。
   • 接続性とルーティング：ネットワーク経路、ロードバランサーのルーティング、サービスエンドポイントを検証します。
   • セキュリティポリシー：アクセス制限、ファイアウォールルール、IAM の適用を検証します。

3. 検証スクリプトを生成する：ユーザーがこれらの検証チェックを実行できるよう、軽量なスクリプトまたはコマンドラインの手順（例：curl、gcloud、agents-cli を使用）を作成します。

   • 検証計画には、ローカル実行、評価、デプロイ後の検証チェック（例：デプロイされたサービスエンドポイントをテストする agents-cli run --url <service-url>）に Agents CLI を使用する手順を必ず含めてください。

4. 検証計画をまとめる：validation-template.md の形式に従って、検証手順、検証スクリプト、期待される結果を 1 つの Markdown ファイルにまとめます。このドキュメントをワークスペースに validation-plan.md として保存してください。

5. レビューを依頼する：検証計画をユーザーに提示し、計画に対するフィードバックまたは承認を明示的に求めます。

6. 検証を実施して完了する：ユーザーが検証チェックを実行できるよう支援し、デプロイに関する問題のトラブルシューティングを行います。ソリューションの検証に成功したら、ユーザーに最終承認を求めます。

7. 反復する：ユーザーが変更を求めた場合は、検証計画を更新し、ユーザーが計画を承認するまで「検証チェックを定義する」から「レビューを依頼する」までの手順を繰り返します。

---

参考資料と関連リンク

• このスキルで使用する Google Cloud のアーキテクチャに関するドキュメント、製品マニュアル、開発キット、チェックリストの完全な一覧については、related-guidance.md を参照してください。