adk-scaffold

ADK プロジェクトのスキャフォールディングガイド

agent-starter-pack CLI（uvx 経由）を使用して、新しい ADK エージェントプロジェクトを作成するか、デプロイ、CI/CD、インフラストラクチャのスキャフォールディングで既存のプロジェクトを拡張します。

---

ステップ 1：要件を確認する

まずユースケースを確認し、回答に基づいて追加の質問をします。

必ず確認する項目：

1. エージェントはどのような問題を解決しますか？ — 中核となる目的と機能
2. 必要な外部 API やデータソースはありますか？ — ツール、連携、認証要件
3. 安全性に関する制約はありますか？ — エージェントがしてはならないこと、ガードレール
4. デプロイの希望はありますか？ — まずはプロトタイプ（推奨）にしますか、それとも完全にデプロイしますか？デプロイする場合は、Agent Engine、Cloud Run、GKE のどれですか？

状況に応じて確認する項目：

• データの検索または検索拡張生成に関する言及がある場合（RAG、セマンティック検索、ベクトル検索、埋め込み、類似性検索、データ取り込み）→ データストアは必要ですか？ --agent agentic_rag --datastore <choice> を使用します。
  • vertex_ai_vector_search — 埋め込み、類似性検索、ベクトル検索向け
  • vertex_ai_search — ドキュメント検索、検索エンジン向け
• エージェントをほかのエージェントから利用可能にする場合 → A2A プロトコルを使用しますか？ --agent adk_a2a を使用して、エージェントを A2A 互換サービスとして公開します。
• 完全なデプロイを選択した場合 → CI/CD ランナーはどれですか？ GitHub Actions（デフォルト）または Google Cloud Build。
• Cloud Run または GKE を選択した場合 → セッションストレージはどれですか？ インメモリ（デフォルト）、Cloud SQL（永続化）、Agent Engine（マネージド）。
• CI/CD を使用したデプロイを選択した場合 → Git リポジトリはありますか？ すでにあるか、新しく作成する必要があるかを確認します。新しく作成する場合は、公開または非公開のどちらにするかを確認します。

---

ステップ 2：DESIGN_SPEC.md を作成する

次のセクションを含む詳細な仕様を作成します。スキャフォールディングを実行する前に、仕様全体を提示してユーザーの承認を得ます。

# DESIGN_SPEC.md

## Overview
2-3 paragraphs describing the agent's purpose and how it works.

## Example Use Cases
3-5 concrete examples with expected inputs and outputs.

## Tools Required
Each tool with its purpose, API details, and authentication needs.

## Constraints & Safety Rules
Specific rules — not just generic statements.

## Success Criteria
Measurable outcomes for evaluation.

## Edge Cases to Handle
At least 3-5 scenarios the agent must handle gracefully.

仕様は、別の開発者が追加の情報なしでエージェントを実装できるほど詳細に記述してください。

---

ステップ 3：プロジェクトを作成または拡張する

新しいプロジェクトを作成する

uvx agent-starter-pack create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype \
  -y

制約：

• プロジェクト名は26 文字以内で、小文字のアルファベット、数字、ハイフンのみを使用してください。
• create を実行する前に、プロジェクトディレクトリを mkdir で作成しないでください。CLI が自動的に作成します。先に mkdir を実行すると、create が失敗したり、予期しない動作をしたりします。
• 実行中の IDE に基づいてガイダンスファイル名を自動検出し、適切な --agent-guidance-filename を渡してください。
• 既存プロジェクトを拡張する場合は、エージェントのコードがどこにあるかを確認してください。app/ 以外にある場合は、--agent-directory <dir>（例：--agent-directory agent）を渡してください。指定を誤ると、enhance でファイルが見つからなかったり、別の場所に配置されたりします。

作成フラグ

フラグ	短縮形	デフォルト	説明
--agent	-a	adk	エージェントテンプレート（下記のテンプレート表を参照）
--deployment-target	-d	agent_engine	デプロイ先（agent_engine、cloud_run、gke、none）
--region		us-central1	GCP リージョン
--prototype	-p	off	CI/CD と Terraform をスキップします（最初の段階では推奨）
--cicd-runner		skip	github_actions または google_cloud_build
--datastore	-ds	—	データ取り込み用のデータストア（vertex_ai_search、vertex_ai_vector_search）
--session-type		in_memory	セッションストレージ（in_memory、cloud_sql、agent_engine）
--auto-approve	-y	off	確認プロンプトをスキップします
--skip-checks	-s	off	GCP／Vertex AI の検証チェックをスキップします
--agent-directory	-dir	app	エージェントコードのディレクトリ名
--agent-guidance-filename		GEMINI.md	ガイダンスファイル名（CLAUDE.md、AGENTS.md）
--debug		off	トラブルシューティング用のデバッグログを有効にします

デフォルトでは、スキャフォールディングされたプロジェクトは Google Cloud の認証情報（Vertex AI）を使用します。API キーの設定とモデル構成については、Gemini モデルの構成およびサポート対象モデルを参照してください。

既存のプロジェクトを拡張する

uvx agent-starter-pack enhance . \
  --deployment-target <target> \
  -y

プロジェクトディレクトリ内で実行してください（または . の代わりにパスを渡してください）。enhance は新しいファイル（.github/、deployment/、tests/load_test/ など）を作成するため、コミットする必要があることを忘れないでください。

Enhance のフラグ

create のすべてのフラグに加えて、以下を使用できます。

フラグ	短縮形	デフォルト	説明
--name	-n	ディレクトリ名	テンプレート作成時のプロジェクト名
--base-template	-bt	—	ベーステンプレートを上書きします（例：RAG を追加する場合は agentic_rag）
--dry-run		オフ	適用せずに変更をプレビューします
--force		オフ	すべてのファイルを強制的に上書きします（スマートマージをスキップ）

よくあるワークフロー

これらのコマンドを実行する前に、必ずユーザーに確認してください。 選択肢（CI/CD ランナー、デプロイ先など）を提示し、実行前に確認を得てください。

# Add deployment to an existing prototype
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
uvx agent-starter-pack enhance . --cicd-runner github_actions -y

# Add RAG with data ingestion
uvx agent-starter-pack enhance . --base-template agentic_rag --datastore vertex_ai_search -y

# Preview what would change (dry run)
uvx agent-starter-pack enhance . --deployment-target cloud_run --dry-run -y

---

テンプレートのオプション

テンプレート	デプロイ先	説明
adk	Agent Engine、Cloud Run、GKE	標準的な ADK エージェント（デフォルト）
adk_a2a	Agent Engine、Cloud Run、GKE	エージェント間の連携（A2A プロトコル）
agentic_rag	Agent Engine、Cloud Run、GKE	データ取り込みパイプラインを備えた RAG

---

デプロイのオプション

ターゲット	説明
agent_engine	Google が管理します（Vertex AI Agent Engine）。セッションは自動的に処理されます。
cloud_run	コンテナベースのデプロイです。より細かく制御できますが、Dockerfile が必要です。
gke	GKE Autopilot 上のコンテナベースのデプロイです。Kubernetes を完全に制御できます。
none	デプロイ用のスキャフォールディングはありません。コードのみです。

「まずプロトタイプを作成する」パターン（推奨）

まず --prototype を指定して CI/CD と Terraform をスキップします。最初にエージェントを動作させることに集中し、その後 enhance でデプロイを追加します。

# Step 1: Create a prototype
uvx agent-starter-pack create my-agent --agent adk --prototype -y

# Step 2: Iterate on the agent code...

# Step 3: Add deployment when ready
uvx agent-starter-pack enhance . --deployment-target agent_engine -y

Agent Engine と session_type

デプロイ先に agent_engine を指定すると、Agent Engine がセッションを内部で管理します。コードで session_type を設定している場合は、Agent Engine によって上書きされるため、設定をクリアしてください。

---

ステップ 4：DESIGN_SPEC.md を保存し、開発ワークフローを読み込む

スキャフォールディングの完了後、ステップ 2 で承認された仕様をプロジェクトのルートに DESIGN_SPEC.md として保存してください。

その後、すぐに /adk-dev-guide を読み込んでください。ここには、エージェントの実装時に従う必要がある開発ワークフロー、コーディングガイドライン、運用ルールが記載されています。

---

参照用にスキャフォールディングする

Terraform、CI/CD ワークフロー、Dockerfile などの特定のファイルが必要でも、現在のプロジェクトを直接スキャフォールディングしたくない場合は、/tmp/ に一時的な参照プロジェクトを作成してください。

uvx agent-starter-pack create /tmp/ref-project \
  --agent adk \
  --deployment-target cloud_run \
  --cicd-runner github_actions \
  -y

生成されたファイルを確認し、必要なものを調整して実際のプロジェクトにコピーしてください。完了したら、参照プロジェクトを削除してください。

次のような場合に便利です。

• enhance では対応できない標準外のプロジェクト構成
• 特定のインフラストラクチャファイルだけを選んで取り込む場合
• コミットする前に ASP が生成する内容を把握する場合

---

重要なルール

• 明示的に依頼されない限り、既存のコード内のモデルを絶対に変更しないでください
• create の前に絶対に mkdir を実行しないでください — CLI がディレクトリを作成します。事前に作成すると、create モードではなく enhance モードになります
• 確認せずに Git リポジトリを作成したり、リモートにプッシュしたりしないでください — リポジトリ名、公開か非公開か、そもそも作成するかどうかを確認してください
• CI/CD ランナーを選択する前に必ず確認してください — GitHub Actions と Cloud Build を選択肢として提示し、黙ってデフォルトを選ばないでください
• Agent Engine は session_type をクリアします — agent_engine にデプロイする場合は、コードから session_type の設定を削除してください
• 手早く反復する場合は --prototype から始めてください — デプロイは後から enhance で追加できます
• プロジェクト名は 26 文字以下で、小文字の英字、数字、ハイフンのみ使用できます
• A2A コードをゼロから絶対に作成しないでください — A2A の Python API（インポートパス、AgentCard スキーマ、to_a2a() のシグネチャ）は複雑で、バージョンによって変わります。A2A プロジェクトのスキャフォールディングには、必ず --agent adk_a2a を使用してください。

---

例

scaffold を参考にする場合： ユーザー：「標準的でないプロジェクト用の Dockerfile が必要です」 操作：

1. 一時プロジェクトを作成します：uvx agent-starter-pack create /tmp/ref --agent adk --deployment-target cloud_run -y
2. 関連ファイル（Dockerfile など）を /tmp/ref からコピーします
3. 一時プロジェクトを削除します 結果：実際のプロジェクトに適合させたインフラストラクチャファイル

---

A2A プロジェクト： ユーザー：「A2A を公開し、Cloud Run にデプロイする Python エージェントを作ってください」 操作：

1. 標準的な手順（要件の収集、DESIGN_SPEC、scaffold）に従います
2. uvx agent-starter-pack create my-a2a-agent --agent adk_a2a --deployment-target cloud_run --prototype -y 結果：有効な A2A インポートと Dockerfile が用意されます。A2A コードを手動で記述する必要はありません。

---

トラブルシューティング

uvx コマンドが見つからない

公式インストールガイドに従って uv をインストールしてください。

uv を使用できない場合は、代わりに pip を使用してください：

# macOS/Linux
python -m venv .venv && source .venv/bin/activate
# Windows
python -m venv .venv && .venv\Scripts\activate

pip install agent-starter-pack
agent-starter-pack create <project-name> ...

利用可能なすべてのオプションを確認するには、uvx agent-starter-pack create --help を実行してください。