google-agents-cli-workflow

エージェント開発のワークフローとガイドライン

agents-cli は、Google Cloud でエージェントを構築、評価、デプロイするための CLI とスキルツールキットです。任意のコーディングエージェント（Antigravity CLI、Claude Code、Codex など）や、選択したエージェントフレームワーク（デフォルトは Agent Development Kit (ADK)）と連携します。uvx google-agents-cli setup でインストールできます。

エージェントのコードを書く前に、スキャフォールド済みのプロジェクトがあることを確認してください（フェーズ 2 を参照）。 スキャフォールディングを省略すると、評価用のボイラープレート、CI/CD 設定、プロジェクトの規約が失われます。

必要条件：google-agents-cli = 1.11.0 バージョンが古い場合は、次を実行してください：uv tool install "google-agents-cli=1.11.0"

バージョンを確認：agents-cli info 必要に応じて、まず uv をインストールしてください。

セッションの継続性とスキルの相互参照

各フェーズを始める前に、関連するスキルを読み直してください。作業を始めて問題が発生してから読み直すのではありません。コンテキストの圧縮によって、以前のスキルの内容が失われていることがあります。スキルを利用できない場合は、uvx google-agents-cli setup を実行してインストールしてください。

フェーズ	スキル	読み込むタイミング
0 — 理解する	—	スキルは不要です。.agents-cli-spec.md があれば読み、なければユーザーに目標を確認します
1 — レシピを調べる	/google-agents-cli-adk-code	設計中に、スキャフォールディングの前に読み込みます。 Python の場合：references/samples.md のトピックインデックスで、必要な機能を実装するレシピを確認できます。Go の場合：上流の examples/ が同等のものです。早い段階で読み込んでください。
2 — スキャフォールド	/google-agents-cli-scaffold	プロジェクトの作成または拡張の前
3 — 構築する	/google-agents-cli-adk-code	エージェントのコードを書く前 — API パターン、ツール、コールバック、状態
4 — 評価する	/google-agents-cli-eval	評価を実行する前 — データセットのスキーマ、メトリクス、評価と修正のループ
5 — デプロイする	/google-agents-cli-deploy	デプロイする前 — デプロイ先の選択、403／タイムアウトのトラブルシューティング
6 — 公開する	/google-agents-cli-publish	デプロイ後、Gemini に登録する場合（任意）
7 — 監視する	/google-agents-cli-observability	デプロイ後 — トレース、ログ、監視の設定

---

セットアップ

agents-cli がインストールされていない場合：

uv tool install google-agents-cli

uv コマンドが見つからない場合

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

製品名の対応付け

ユーザーによって製品名の呼び方が異なります（Vertex AI や Agent Platform → Gemini platform、Agent Engine や Agent Runtime → Gemini platform の Agent Runtime など）。references/terminology.md を使って、ユーザーの用語を CLI の値に対応付けてください。

---

フェーズ 0：理解する

何かを書く、またはスキャフォールディングを始める前に、チェックリストではなく、設計についての対話を通じて、何を構築するのかを理解してください。references/brainstorming.md を読み込み、その指示に従ってください。一度に質問を一つだけ行い、複雑なエージェントではアーキテクチャのアプローチを2～3案提示し、スキャフォールディングを始める前に設計を検証してください。

現在のディレクトリに .agents-cli-spec.md がある場合は、それを読み込んでください。これは最も優先される情報源です。ない場合は、次の手順に従ってください。

ユーザーが仕様を承認するまで、計画、スキャフォールディング、コーディングに進まないでください。自分で推測したり、調査したり、空欄を埋めたりしないでください。すべてはユーザーの意図に基づきます。

複雑さに応じて手順の規模を調整してください。 単純なエージェント（ツールが一つで、ペルソナが固定されている場合）であれば、質問は2～3個、仕様は2～3文、承認は1回で十分です。複雑なエージェント（マルチエージェント、RAG、外部 API／認証、安全性が極めて重要なもの）の場合は、references/brainstorming.md の手順をすべて実施してください。

確認するトピック（一度に一つずつ、ユーザーの状況に合わせて質問してください。プレイブックを参照してください）。

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

状況に応じて質問してください。

• エージェントにスキャフォールドに含まれていない機能（データの検索、サンドボックス化されたコード実行、セッションをまたぐメモリ、OAuth の同意、安全性のガードレール、イベント駆動型トリガーなど）が必要な場合、その機能はスキャフォールドのフラグではなく、複製して調査するレシピから得られます。/google-agents-cli-adk-code のトピックインデックスである references/samples.md から必要な機能を探し、フェーズ 1 で該当するレシピを調査してください。
• エージェントがライブエージェントまたは音声エージェント（Live API、音声での会話、割り込み、電話）である場合は、仕様を書く前に /google-agents-cli-adk-code（references/adk-python-live.md）を読み込んでください。ライブエージェントでは、A2A、Gemini アプリ、デフォルトモデルは使用できません。
• エージェントをほかのエージェントから利用可能にする場合、A2A プロトコルは agents-cli でスキャフォールディングされるすべての Python エージェントに組み込まれています。別途選択する必要はなく、通常どおりスキャフォールディングしてください。
• 完全なデプロイを選んだ場合は、CI/CD ランナーを確認してください。GitHub Actions（デフォルト）と Google Cloud Build のどちらを使いますか？
• エージェントにセッションをまたいでユーザーの好みや事実を記憶させる場合は、会話をまたぐ長期メモリが必要です。/google-agents-cli-adk-code を読み込んでください。ここにはレシピ（references/samples.md）と ADK メモリ API の詳細の両方があります。
• Cloud Run または GKE を選んだ場合は、セッションストレージを確認してください。インメモリ（デフォルト）、Cloud SQL（永続化）、Gemini プラットフォームのセッション（マネージド）から選びます。
• CI/CD を使ったデプロイを選んだ場合は、Git リポジトリについて確認してください。既存のリポジトリを使いますか、それとも新しく作成しますか？ 新しく作成する場合は、パブリックとプライベートのどちらにしますか？

設計の合意が得られたら、references/spec-template.md のテンプレートを使って .agents-cli-spec.md に仕様を書き、内容を自分でレビューしてから、ユーザーの承認を得てください。これらの選択肢が CLI フラグにどう対応するかは、/google-agents-cli-scaffold を参照してください。

内容を明確に把握したら、フェーズ 1 に進んでください。

フェーズ 1：リファレンスレシピを調べる

トリガー。 リクエストに次のいずれかが含まれる場合：自分のドキュメントの検索 · ユーザーに代わってのシェルまたは Python コードの実行 · サンドボックス化された、またはユーザーごとに分離された環境 · エージェントが実行時に取り込むスキルの読み込み · 数日間にわたる、再開される、または無人で実行される作業 · 会話をまたいだ記憶 · リスクのある操作が実行される前の承認 · 有害なコンテンツのブロック、またはエージェントの発言のモデレーション · ユーザー自身の API キーや認証情報を使った操作 · ユーザー自身のデータにアクセスするための OAuth 同意 · 分離されたコンテキストを持つサブエージェントへの委任 · 他のエージェントとの A2A 通信 · イベントやスケジュールへの対応 · オンラインでのトピック調査と出典付きの報告 · 画像や動画の生成 · 本番環境のトレースを使った、デプロイ済みエージェントの品質の監視 — であれば、すでにその機能を実装したレシピがあります。実装に着手する前に調べてください。

このリストは、/google-agents-cli-adk-code → references/samples.md のトピックインデックスと同じ機能を網羅しています。一方を拡張した場合は、もう一方も拡張してください。

今すぐ /google-agents-cli-adk-code を読み込んでください。まだ何もスキャフォールディングされておらず、コードも書いていない場合でも読み込んでください。「コードスキルを使う段階ではない」というのは、エージェントがこの手順を省略するための合理化です。このスキルの コードを書くための前提条件 は、あなたには当てはまりません。

設計で必要とされる機能を一つずつ調べてください。ADK Python： references/samples.md のトピックインデックスでは、ニーズ（検索、サンドボックス化された実行、メモリ、承認ゲート、ガードレール、ユーザーごとの認証情報、スケジューリング）に、それらを解説し、クローン方法も示すレシピが対応付けられています。ADK Go： リファレンスカタログはありません。API については references/adk-go.md を、上流の examples/ も確認してください。

複数のレシピが該当する場合もあります。該当するものをすべてクローンして調べ、まず各レシピの AGENTS.md を確認してください。

該当するレシピがない場合は、フェーズ 2 に進んでください。ただし、その前に、本当にそうでしょうか。ユーザーのリクエストを読み直し、使用言語のトピックインデックスを再確認してください。該当するレシピを省略すると、すでに存在するパターンをたいていはより悪い形で作り直すことになります。

IMPORTANT — 終了条件： レシピを調べた後、それを活用して設計の実現に役立てられることがないか、自問してください。次に進む前に、再利用するものを書き留めてください。これに回答するまでは、先に進まないでください。

このカタログはどのフェーズでも役立ちます — デプロイ、公開、インフラストラクチャに関する疑問が生じたら、再度参照してください。レシピにある Terraform や登録のパターンが、後でまさに必要になるかもしれません。

フェーズ 2：スキャフォールディング（必要な場合）

まず、すでにプロジェクトがあるか確認します。プロジェクトのルートから agents-cli info を実行してください。agents-cli によってすでに作成または拡張されている場合は、このフェーズをスキップしてください。

そうでない場合は、コードを書く前にスキャフォールディングします。

• プロジェクトがまだない場合 → agents-cli scaffold create <name> --agent <template> --deployment-target <target>
• インポートする既存のコードがある場合 → agents-cli scaffold enhance .（agents-cli の構造を追加します）

ワークフロー全体については /google-agents-cli-scaffold を使ってください。アーキテクチャの選択（デプロイ先、エージェントの種類、セッションストレージ）と、プロジェクトの作成または拡張について説明しています。

フェーズ 3：構築と実装

エージェントのロジックを実装します。

1. エージェントのディレクトリにコードを書き込む、または変更します（ディレクトリ名は GEMINI.md / CLAUDE.md を確認してください）。
2. 簡易スモークテスト：変更後に agents-cli run "your prompt" を使ってエージェントが動作することを確認します。ターミナルを離れずに動作を確認する最速の方法です。
3. ユーザーからのフィードバックに基づいて実装を反復改善します。

ユーザーが対話型テストを希望した場合は、agents-cli playground を提案してください。エージェントと手動で会話できるウェブベースのプレイグラウンドが開きます。

ADK API のパターンやコード例については、/google-agents-cli-adk-code を使用してください。

ここではスモークテストのみを実施してください。動作確認用のユニットテストは書かないでください。 LLM の出力は非決定的です。動作確認は pytest や go test ではなく、評価（フェーズ 4）で行います。簡易確認には agents-cli run "prompt" を使用してください。

レシピのインフラストラクチャを用意する（レシピを応用した場合）

レシピに基盤となるインフラストラクチャ（データストア、インデックス、サンドボックス、キューなど）が必要な場合は、レシピに独自のプロビジョニング手順が含まれています。レシピの Makefile（例：make setup-infra、make data-ingestion）と AGENTS.md / README.md に従い、レシピの infra/terraform/ と .env をプロジェクトに合わせて調整してください。 agents-cli にこのためのコマンドはありません。

フェーズ 4：評価

このフェーズが最も重要です。 評価では、エージェントの動作をエンドツーエンドで検証します。

必須： 評価を実行する前に、/google-agents-cli-eval を有効にしてください。 評価にはデータセットのスキーマ、設定形式、重要な注意点が含まれています。絶対に省略しないでください。

このフェーズを省略しないでください。 エージェントを構築した後は、必ず評価に進んでください。

ユニットテストと agents-cli eval の違いを把握してください。

• ユニットテスト（Python の場合は uv run pytest、Go の場合は go test ./...）— コードの正しさをテストします。インポートが機能するか、関数が期待する型を返すか、API コントラクトが守られているかを確認します。エージェントの動作が適切かどうかはテストしません。
• agents-cli eval — エージェントの動作をテストします。応答の品質、ツールの使用、ペルソナの一貫性、安全性への準拠を検証します。エージェントが実際に機能することを確認するために使用します。
• agents-cli run "prompt" — 開発中に行う単発の簡易スモークテストです。複数のプロンプトをテストする場合は、--start-server オプションを使ってローカルサーバーを起動したままにすると、繰り返し呼び出す際のオーバーヘッドを軽減でき、--session-id を使ってローカルセッションを再開できます。これは迅速な反復改善に使用し、ユニットテストには使用しないでください。

LLM の応答内容を確認するユニットテストは絶対に書かないでください（例：海賊に関するキーワードが含まれることをアサートする、エージェントがアレルギーについて言及するかを確認する）。LLM の出力は非決定的です。代わりに、LLM を評価者として使う基準を設けて評価してください。

1. 小さく始める：評価ケースをすべてそろえるのではなく、サンプルを 1～2 件用意します。
2. 評価を実行します：agents-cli eval run（generate と grade を連続して実行します）。デバッグやカスタムのトレース保存先を指定する場合は、2 段階の形式で agents-cli eval generate を実行し、その後 agents-cli eval grade を実行します。
3. 結果についてユーザーと話し合います。
4. まずコアケースの問題を修正し、反復改善します。
5. コアケースに合格してから、エッジケースや新しいシナリオを追加します。
6. ユーザーと合意した基準をすべてのケースが満たすまで繰り返します（eval run はスコアにかかわらず終了コード 0 を返すため、スコアを確認してください）。

ここでは 5～10 回以上の反復を想定してください。

フェーズ 5：デプロイ

評価スコアが十分であることにユーザーが同意したら、次の手順に進みます。

1. プロジェクトにデプロイ先が設定されているか確認します。現在の設定を確認するには agents-cli info を実行します。
2. プロジェクトがプロトタイプ（デプロイ先が未設定）の場合は、まずデプロイをサポートする設定を追加します。

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

   デプロイ先の選択基準（Agent Runtime、Cloud Run、GKE）については、/google-agents-cli-deploy を参照してください。
3. 準備ができたらデプロイします：agents-cli deploy

重要：人間から明示的な承認を得ずにデプロイしてはいけません。

フェーズ 6：公開（任意）

すべてのエージェントに公開が必要なわけではありません。現在、Gemini への登録をサポートしています。登録モード、フラグ、トラブルシューティングについては、/google-agents-cli-publish を参照してください。

フェーズ 7：監視

デプロイ後は、オブザーバビリティツールを使用して、本番環境でのエージェントの動作を監視します。Cloud Trace、プロンプトとレスポンスのログ記録、BigQuery Analytics、サードパーティとの連携については、/google-agents-cli-observability をご覧ください。

---

コーディングエージェントの運用ガイドライン

避けるべきよくある近道

エージェントは、もっともらしい言い訳をして手順を省略しがちです。こうした言い訳を見抜き、思いとどまらせてください。

近道	うまくいかない理由
「ユーザーの要望は十分明確なので、確認する必要はありません」	要件を推測しています。フェーズ 0 は、ひな形を作成する前に意図を確認するためのものです。たった一つ質問するだけでも、全面的なやり直しを防げることがあります。
「agents-cli run でエージェントが正しく応答したので、評価は必要ありません」	1 つのプロンプトはテストスイートではありません。評価では、1 回の実行では決してわからないリグレッション、エッジケース、ツールの実行経路に関する問題を検出できます。
「もっと新しい、より優れたモデルを使います」	ひな形で選択されたモデルには、意図があります。依頼されていないのに変更することは、コード保全（原則 1）に反し、多くの場合、問題を引き起こします。場所が違う、バージョンが廃止されている、404 になるなどの問題です。トレーニングデータが古くなっている可能性があるため、モデル名に関する知識ではなく、スキルとモデル一覧表示コマンドを頼りにしてください。
「サンドボックス、メモリ、承認ゲートの構築方法はすでにわかっています」	これから、既存のレシピをさらに悪い形で作り直そうとしています。こうした機能はすでに /google-agents-cli-adk-code → references/samples.md で実装され、十分に検証済みです。独自の設計を始める前に、トピック索引を確認し、該当するレシピの AGENTS.md を開いてください。
「ひな形を省略して、手作業でセットアップできます」	手作業でセットアップすると、評価用の定型コード、CI/CD 設定、プロジェクト設定マニフェストの規約を見落とします。簡単な実験でも agents-cli create を使用してください。

原則 1：コードの保全と隔離

コードの変更は、細心の注意を払って行う必要があります。ユーザーの依頼が直接対象とするコード部分のみを変更し、周囲のコードや無関係なコードは厳密に保持してください。

実行前の必須確認：

コードを置き換える前に、次の点を確認してください。

1. 対象の特定： ユーザーの明示的な指示のみに基づいて、変更する正確な行または式を明確にします。
2. 保持の確認： 特定した対象以外のすべてのコード、設定値（例：model、version、api_key）、コメント、書式が同一であることを確認します。

例：

• ユーザーの依頼：「エージェントの指示を、レシピを提案するものに変更してください。」
• 誤り（違反）：

  root_agent = Agent(
      name="recipe_suggester",
      model="gemini-1.5-flash",  # UNINTENDED - model was not requested to change
      instruction="You are a recipe suggester."
  )
  

• 正解（遵守）：

  root_agent = Agent(
      name="recipe_suggester",  # OK, related to new purpose
      model="gemini-3.8-flash",  # PRESERVED
      instruction="You are a recipe suggester."  # OK, the direct target
  )
  

原則 2：実行のベストプラクティス

• モデルの選択 — 重要：

  • 明示的に指示されない限り、モデルを変更しないでください。
  • 新しいエージェントを作成する場合（既存のエージェントを変更する場合を除く）は、最新の Gemini モデルを使用してください。エージェントが実際に使用するロケーション（デフォルトでは global の GOOGLE_CLOUD_LOCATION）で利用可能なモデルを一覧表示してください。すべてのモデルがすべてのロケーションで提供されているわけではありません。

    uv run --with google-genai python -c "
    from google import genai
    # GOOGLE_CLOUD_LOCATION（'global'、または 'us-east1' などのリージョン）を使用します
    client = genai.Client(vertexai=True, location='global')
    for m in client.models.list(): print(m.name)
    "
    

  • 明示的に指示されない限り、古いモデルは使用しないでください。モデルのドキュメントについては、https://adk.dev/agents/models/google-gemini/index.md を取得してください。安定版モデルとモデルエンドポイントのロケーションも参照してください。

• Python コマンドの実行：

  • Python コマンドの実行には必ず uv を使用してください（例：uv run python script.py）
  • スクリプトを実行する前に uv sync を実行してください

• 無限ループの停止：

  • 同じエラーが3回以上連続して表示されたら、直ちに停止してください
  • 危険信号：ロック ID が増加する、名前が v5→v6→v7 と変わる、「もう一度だけ試します」と繰り返す
  • 状態の競合（Error 409）：作成を再試行するのではなく、terraform import を使用してください
  • 行き詰まった場合：基盤となるコマンドを直接実行してください（例：terraform CLI）

• トラブルシューティング：

  • まず /google-agents-cli-adk-code を確認してください。よくあるパターンの大半が記載されています
  • 詳細を調べるには、ADK ドキュメントのインデックスにある URL で WebFetch を使用してください（curl https://adk.dev/llms.txt）
  • エラーが繰り返し発生する場合は、対象を絞ったウェブ検索でより早く解決策が見つかることがよくあります
  • CLI コマンドの失敗：agents-cli <command> --help を実行してください。出力の末尾に、そのコマンドを実装している正確なソースファイルを示す Source: 行があります。そのファイルを読んでロジックを理解し、失敗の原因を診断してください。複数のファイルを調べる必要がある場合は、agents-cli info を使用して CLI のインストール先全体を確認してください。

系統的なデバッグ

問題が発生した場合は、この手順に従ってください。手順を飛ばしたり、手当たり次第に修正を試したりしないでください。

1. 再現する — 失敗したコマンドをそのまま実行します。エラー出力全体を保存してください。再現できなければ、修正できません。
2. 原因を絞り込む — 原因がエージェントのコード、ツール、設定、環境のどれかを特定します。agents-cli run "prompt" を使用して、デプロイの問題とエージェントの動作を切り分けます。-v（--verbose）を追加すると、JSON イベントのペイロード全体が出力され、ツール呼び出し、中間ステップ、表面化しない失敗の確認に役立ちます。
3. 一つずつ修正する — 一度に変更する変数は一つにしてください。指示、ツール、設定を同時に変更すると、何が修正につながったのか（または別の問題を引き起こしたのか）が分からなくなります。
4. 検証する — 問題を再現したコマンドをそのまま再実行します。修正が機能したと決めつけないでください。
5. 再発を防ぐ — 原因が分かりにくいバグだった場合は、再発を検出するための eval ケースを追加します。

作業停止ルール： 変更によって動作していたものが壊れた場合は、機能開発を中断して、まずリグレッションを修正してください。後で戻るつもりで作業を進めないでください。リグレッションは連鎖的に増えていきます。

• 環境変数：
  • .env ファイルと環境変数の割り当て（例：GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION）は、通常エージェントの動作に必要です。ユーザーから明示的に依頼されない限り、削除したり変更したりしないでください
  • プロジェクトのルートに .env ファイルがある場合は、必須の設定として扱ってください
  • シークレットや API キーには、.env に直接記載するのではなく GCP Secret Manager を優先してください。シークレット管理のガイダンスについては /google-agents-cli-deploy を参照してください

---

一時的なスキャフォールドを参照として使用する

Terraform、CI/CD、Dockerfile などの特定のインフラストラクチャファイルが必要で、現在のプロジェクトを変更したくない場合は、/google-agents-cli-scaffold を使用して /tmp/ に一時的なプロジェクトを作成し、必要なファイルをコピーしてください。

---

参照ファイル

ファイル	内容
references/internals.md	agents-cli が言語ごとにラップする基盤となるツールとコマンド（Python：adk、uv、ruff。Go：adk-go、go、golangci-lint）
references/spec-template.md	.agents-cli-spec.md のテンプレートと任意のセクション
references/brainstorming.md	フェーズ 0 の設計対話プレイブック（一度に 1 つの質問と回答、アプローチ、ゲート）
references/terminology.md	製品名から CLI 値への対応表
references/commands.md	フェーズごとの agents-cli コマンド一覧
references/extension.md	アドホック拡張機能の作成、または既存の拡張機能の採用（コマンドのオーバーライドまたは追加）

開発コマンド

正式なフラグ一覧を確認するには、agents-cli --help または agents-cli <command> --help を実行してください。フェーズごとのコマンド一覧は references/commands.md に、フェーズごとの使用方法は上記の各フェーズのセクションに記載されています。

組み込みコマンドをオーバーライド（例：deploy をコンプライアンスチェックでラップ）したり、新しいコマンドを追加したりするには、agents-cli の拡張システムを使用します。このリポジトリ用のアドホック拡張機能を作成するか、既存のものを採用するには、references/extension.md を読み込んでください。

---

スキルのバージョン

トラブルシューティングのヒント： スキルが古い、または不完全に見える場合は、再インストールしてください。

agents-cli setup --skip-auth

古いスキルが問題の原因だと思われる場合にのみ実行してください。