google-agents-cli-scaffold

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

必要条件： agents-cli（uv tool install google-agents-cli）— 必要に応じて、先に uv をインストールしてください。

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

---

前提条件：要件を明確にする（新規プロジェクトでは必須）

新しいプロジェクトをスキャフォールディングする前に、/google-agents-cli-workflow を読み込み、Phase 0 を完了してください — scaffold create コマンドを実行する前に、ユーザーの要件を明確にします。エージェントに何をさせたいか、どのツール／API が必要か、プロトタイプと完全なデプロイのどちらを希望するかを確認してください。

---

Step 1：アーキテクチャを選択する

ユーザーの選択を CLI フラグに対応付ける：

選択肢	CLI フラグ
検索／RAG、サンドボックス化された実行、セッションをまたぐメモリ、OAuth の同意、ガードレール、スケジュール実行	フラグなし — これらはクローンして学ぶレシピから利用できます。ADK Python： /google-agents-cli-adk-code → references/samples.md のトピックインデックスを参照してください。他のフレームワークでは、フレームワークのテンプレートに含まれるサンプルインデックスを参照してください
A2A プロトコル	スキャフォールディングされたアプリに組み込み済みです — 通常どおりスキャフォールディングしてください（ADK Python： --agent adk（デフォルト）、ADK Go： --agent adk_go）
プロトタイプ（デプロイなし）	--prototype
デプロイ先	--deployment-target <agent_runtime|cloud_run|gke>
CI/CD ランナー	--cicd-runner <github_actions|google_cloud_build>
セッションストレージ	--session-type <in_memory|cloud_sql|agent_platform_sessions>

製品名の対応付け

現在の名称（ユーザーが使う可能性のある以前の名称）→ CLI の値（vertexai SDK パッケージ名は変更なし）：

• Gemini プラットフォームの Agent Runtime（Agent Engine／Vertex AI Agent Engine／Agent Runtime）→ --deployment-target agent_runtime
• Gemini プラットフォームの Sessions（Agent Engine sessions／Agent Platform Sessions）→ --session-type agent_platform_sessions
• Gemini プラットフォームの Search／Vector Search（Vertex AI Search／Vertex AI Vector Search）／RAG → フラグではなく、クローンして学ぶレシピ

削除されたフラグ。 --datastore、agentic_rag テンプレート、agents-cli infra datastore／ agents-cli data-ingestion は現在存在しません。これらを使おうとしている場合は、代わりにレシピが必要です。

---

Step 2：プロジェクトを作成または拡張する

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

agents-cli scaffold create <project-name> \
  --agent <template> \
  --deployment-target <target> \
  --region <region> \
  --prototype

制約：

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

参照ファイル

ファイル	内容
references/flags.md	create コマンドと enhance コマンドのすべてのフラグのリファレンス

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

agents-cli scaffold enhance . --deployment-target <target>
agents-cli scaffold enhance . --cicd-runner <runner>

プロジェクトディレクトリ内から実行してください（または . の代わりにパスを指定してください）。

プロジェクトをアップグレードする

既存のプロジェクトを新しいバージョンの agents-cli にアップグレードし、カスタマイズを維持しながら更新をインテリジェントに適用します。

agents-cli scaffold upgrade                # Upgrade current directory
agents-cli scaffold upgrade <project-path> # Upgrade specific project
agents-cli scaffold upgrade --dry-run      # Preview changes without applying
agents-cli scaffold upgrade --auto-approve  # Auto-apply non-conflicting changes
agents-cli scaffold upgrade --force        # Overwrite scaffolding files when smart-merge fails
agents-cli scaffold upgrade --force --dry-run  # List what --force would overwrite

--force は、スマートマージに失敗した場合の代替手段です。agents-cli のバージョンが PyPI に存在しない場合も、そのバージョンのテンプレートが必要なためスマートマージは停止します。その場合も --force を使用してください。スキャフォールディングファイルは新しいテンプレートで上書きされますが、エージェントのコード、設定ファイル、README.md、エージェントのガイダンスファイル、評価用データセットと設定は保持されます。新しいテンプレートで削除された依存関係やファイル（削除された CI ワークフローなど）は削除されないため、不要なものは手動で削除してください。その後、インポートを確認し、テストを実行してください。どのファイルが変更されるかを確認するには、まず --dry-run を使用してください。

実行モード

CLI のデフォルトは 厳格なプログラム実行モード です。必須パラメーターはすべて CLI フラグで指定する必要があり、指定しない場合は UsageError が発生します。承認フラグは不要です。必須パラメーターをすべて明示的に渡してください。

よく使われるワークフロー

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

# Add deployment to an existing prototype (strict programmatic)
agents-cli scaffold enhance . --deployment-target agent_runtime

# Add CI/CD pipeline (ask: GitHub Actions or Cloud Build?)
agents-cli scaffold enhance . --cicd-runner github_actions

---

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

| テンプレート | 言語 | デプロイ | 説明 | |----------|------------|-------------| | adk | Python | Agent Runtime、Cloud Run、GKE | 標準の ADK エージェント（デフォルト）。A2A プロトコルを組み込み済み | | adk_go | Go | Agent Runtime、Cloud Run、GKE | 標準の ADK Go エージェント。A2A プロトコルを組み込み済み |

組み込みテンプレートは adk と adk_go のみです。 adk がデフォルトのため、Go プロジェクトでは明示的に --agent adk_go を指定する必要があります。 その他のフレームワークはテンプレートリポジトリとして提供されており、そこから直接スキャフォールディングできます。 --agent google/agents-cli/extensions/langchain/[email protected] のように指定し、何もインストールされていない状態で利用できます。ファーストパーティの LangChain テンプレートは agents-cli リポジトリ内の extensions/langchain/template/ です。独自のテンプレートの公開方法については、 /google-agents-cli-workflow → references/extension.md を参照してください。テンプレート以外の機能（検索拡張生成、サンドボックス化された実行、メモリ、OAuth、ガードレール）は、 テンプレートではなく、クローンして学習するためのレシピです。ADK Python： /google-agents-cli-adk-code → references/samples.md のトピックインデックスを参照してください。

ライブエージェントと音声エージェント： テンプレートはありません。adk をスキャフォールディングした後、 /google-agents-cli-adk-code の変換チェックリスト（references/adk-python-live.md の「Converting a scaffolded project to Live」）に従ってください。モデルの差し替えは、5 つの変更点のうちの 1 つです。

---

デプロイのオプション

対象	説明
agent_runtime	Google が管理します（Agent Runtime）。コンテナーベースで、Agent Runtime がプロジェクトの Dockerfile をビルドします。セッションは自動的に処理されます。
cloud_run	コンテナーベースのデプロイです。より細かく制御でき、Dockerfile のビルドとデプロイはユーザーが行います。
gke	GKE Autopilot 上でのコンテナーベースのデプロイです。Kubernetes を完全に制御できます。
none	デプロイ用のスキャフォールディングはありません。コードのみです（Dockerfile は含まれます）。

「まずはプロトタイプ」パターン（推奨）

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

# Step 1: Create a prototype
agents-cli scaffold create my-agent --agent adk --prototype

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

# Step 3: Add deployment when ready
agents-cli scaffold enhance . --deployment-target agent_runtime

Agent Runtime と session_type

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

---

ステップ 3：開発ワークフローを読み込む

スキャフォールディングの後、すぐに /google-agents-cli-workflow を読み込んでください。ここには、エージェントの実装時に従うべき開発ワークフロー、コーディングガイドライン、運用ルールが記載されています。

編集するファイルは言語によって異なります。/google-agents-cli-adk-code の references/adk-python.md と references/adk-go.md に、それぞれの注釈付きツリーがあります。

• ADK Python（--agent adk） — app/agent.py と app/tools.py をカスタマイズします。
• ADK Go（--agent adk_go） — app/agent.go をカスタマイズします。

.env は自由に編集できます。それ以外はテンプレートによって生成された状態を維持してください。テンプレートがサービング、セッション、組み込みの A2A サーフェスを設定しています。

レシピを適用する場合： レシピの app/、infra/terraform/、およびインジェストやプロビジョニングに必要なものをスキャフォールディング済みのプロジェクトにコピーし、レシピ独自の Makefile（例：make setup-infra）からプロビジョニングを実行します。レシピの AGENTS.md から始めてください。

エージェントの動作を確認する場合： 手早いスモークテストには agents-cli run "test prompt" を使用し、その後、体系的な検証には agents-cli eval run を使用します。LLM の応答内容を検証する pytest テストは作成しないでください。その検証は eval で行います。

---

参照用のスキャフォールディング

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

agents-cli scaffold create ref-project --output-dir /tmp \
  --agent adk \
  --deployment-target cloud_run

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

次のような場合に役立ちます。

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

---

重要なルール

• 要件の確認を絶対に省略しないでください — /google-agents-cli-workflow のフェーズ 0 を読み込み、scaffold create を実行する前にユーザーの意図を確認します。
• 明示的に依頼されない限り、既存コードのモデルを絶対に変更しないでください。
• create の前に mkdir を絶対に実行しないでください — CLI がディレクトリを作成します。事前に作成すると、create モードではなく enhance モードになります。
• 許可なく Git リポジトリを作成したり、リモートにプッシュしたりしないでください — リポジトリ名、公開か非公開か、そもそも作成を希望するかを確認します。
• CI/CD ランナーを選ぶ前に必ず確認してください — GitHub Actions と Cloud Build を選択肢として提示し、何も言わずに一方を選ばないでください。
• Agent Runtime は session_type をクリアします — agent_runtime にデプロイする場合、コードから session_type の設定を削除します。
• 素早く反復するには --prototype から始めてください — デプロイは後から enhance で追加します。
• プロジェクト名は 26 文字以下で、小文字、英字、数字、ハイフンのみ使用できます。
• A2A コードをゼロから絶対に作成しないでください — A2A はスキャフォールディング済みアプリ（adk と adk_go のテンプレート、およびフレームワークテンプレート）に組み込まれています。各言語の A2A サーフェス（インポートパス、AgentCard スキーマなど）は複雑で、バージョン間で変更されます。通常どおりスキャフォールディングし、A2A サーフェスを手書きしないでください。唯一許可されている A2A の手動編集は、A2A 経由でサービングできない Live エージェントについて、生成された配線を「削除する」ことです。詳しくは /google-agents-cli-adk-code の references/adk-python-live.md を参照してください。

例

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

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

---

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

1. 標準的なフローに従います（要件を把握し、アーキテクチャを選択して、scaffold を作成します）
2. agents-cli scaffold create my-a2a-agent --agent adk --deployment-target cloud_run --prototype 結果：有効な A2A インポートと Dockerfile が用意されます。A2A コードを手動で記述する必要はありません。

---

Go プロジェクト： ユーザー：「Cloud Run にデプロイする Go エージェントを作成してください」 手順：

1. 標準的なフローに従います（要件を把握し、アーキテクチャを選択して、scaffold を作成します）
2. agents-cli scaffold create my-go-agent --agent adk_go --deployment-target cloud_run --prototype 結果：app/agent.go、main.go のランチャー、ルートに A2A カードがある Go プロジェクトが作成されます。

---

トラブルシューティング

agents-cli コマンドが見つからない

/google-agents-cli-workflow の セットアップ セクションをご覧ください。

---

関連スキル

• /google-agents-cli-workflow — 開発ワークフロー、コーディングガイドライン、ビルド・評価・デプロイのライフサイクル
• /google-agents-cli-adk-code — エージェントコードの作成に役立つ ADK API クイックリファレンス。グラフの Workflow API を含みます
• /google-agents-cli-deploy — デプロイ先、CI/CD パイプライン、本番環境のワークフロー
• /google-agents-cli-eval — 評価の方法、データセットのスキーマ、評価・修正のサイクル