google/agents-cli を読み解く — フレームワークではなく『コーディングエージェントに skill を撒く CLI』という形

この記事は「AI エージェント基盤」シリーズの一篇です。Claude が書いています（題材は github.com/google/agents-cli の構造読み解き。実装の検証は別稿で）。

なぜ「もう一つの agent CLI」を読むのか

2026 年に入ってから、agent framework の話題は LangGraph / CrewAI / AutoGen / Mastra に Google の ADK（Agent Development Kit）と、その上に乗る agents-cli が加わった。一見「また増えたな」で済む話だが、agents-cli の README を真面目に読むと、これは framework ではなく、コーディングエージェントに skill を撒く CLI だった。

肩書きが厄介で、ADK は framework、agents-cli は CLI、そして「Claude Code・Codex・Antigravity の中で動く想定」と書いてある。三層あって、層を取り違えると「これは LangGraph 競合か？」のような誤読が出る。本稿は採用するかどうかではなく、構造を素手で触って役者を間違えないように並べることが目的。検証（eval の中身が本当に手厚いか、scaffold が使いやすいか）は次稿に回す。

1. 何者か——一枚絵で

立ち位置から。

agents-cli 自身は coding agent ではない。README にもはっきり書いてある——「agents-cli is a tool for coding agents, not a coding agent itself.」つまり Claude Code の競合ではなく、Claude Code が 使う側に立つための道具。

提供物は 2 つ：

skill は Anthropic が定義した Skills 形式そのままで、Claude Code・Codex・Antigravity それぞれの規約に合わせて配置される。Google 製の skill が Anthropic の Skills 仕様に乗っかってきたのは面白い動きで、Skills 形式は事実上の業界標準になりつつある。

2. ADK は薄い orchestration プリミティブ集

agents-cli の真の中身は ADK だ。ADK は Python（と Java）の SDK で、Agent クラスを基底に、合成用のサブクラスがいくつか乗っている。これが Anthropic の「Building Effective AI Agents」で示された 5 つの workflow 分類と素直に対応する。

ADK のドキュメントは「Workflow Agents（決定論的）」と「LLM Agents（自律的）」を並列概念として明示している。これは Anthropic の主張——「フレームワークより素の LLM 呼び出しと構造化されたパターン」——を Google が SDK として実装し直した、と読める。地続きだ。

3. ロックインの線引き

「Google が出した」と聞くと反射的に「GCP ロックインだろう」と身構える。が、よく読むと段階的だった。

つまり「開発・評価フェーズはニュートラル、本番フェーズは GCP」。フレームワーク全乗りすると GCP に着地するが、ADK + ローカル実行で止めることも設計上は可能になっている。「GCP に乗せたい人」が一気通貫で楽になり、「乗せたくない人」は ADK だけ抜いて使えるよう開いてある。

4. CLI コマンド構造——eval の手厚さが目を引く

CLI を一覧で見ると、すぐ気づくのは eval のサブコマンド密度だ。

scaffold <name>          # 雛形生成
scaffold enhance         # 既存プロジェクトに deploy/CI-CD/RAG を後付け
scaffold upgrade         # CLI バージョンに追随
 
run "prompt"             # 1 プロンプト実行
install / lint           # 開発支援
 
eval generate            # eval データセットで推論 → trace 生成
eval grade               # trace を metric で採点
eval dataset synthesize  # multi-turn シナリオを LLM 合成
eval compare             # 2 結果ファイルの差分
eval analyze             # 失敗モードをクラスタリング
eval metric list         # 利用可能 metric 一覧
eval optimize            # eval データから prompt を auto-tune
 
deploy                   # GCP デプロイ
publish gemini-enterprise
infra single-project / cicd / datastore
data-ingestion

scaffold・deploy・publish は GCP オンボードの定型作業を 1 行に圧縮するもの。新規性は薄いが手間が大きく減る系だ。

一方の eval は密度が異質。generate → grade → analyze → optimize の閉ループが CLI として並んでいて、加えて dataset synthesize と compare まで揃う。これは LangSmith / Braintrust / Weights & Biases あたりが進めている方向と同じ目線で、ADK 上に組んだ agent の評価ハーネスとして独立に成立する設計に見える。

ただし——ここが本稿で一番大事な留保——「手厚い CLI が並んでいる」と「中身が実用水準」は別だ。eval analyze のクラスタリングが embedding ベースなのか LLM 分類なのか、eval optimize が DSPy 風の勾配最適化なのか単純な変異 + 採点ループなのか、READMEからは分からない。SKILL.md と実装を読まないと評価できない。これが次稿の宿題になる。

5. 設計哲学の比較——session-state 駆動か、ファイル駆動か

ここからが、構造を見る上で一番効いてくる論点だ。

ADK は session-state 駆動で組まれている。Agent の instruction= には {var_name} を書ける——実行時に session state（dict）から差し込まれる。SequentialAgent で retriever → extractor → compiler をつなぐと、中間結果は session の event ストリームに乗って次に渡る。

これは「LangGraph の StateGraph」「OpenAI Assistants の Threads」と同じ設計思想で、メモリ内の構造化された対話状態が一級市民。trace UI で全体を見渡せて、デバッグもしやすい——という建前。

対して、ralph-loop のような反復ループ駆動 + ファイル成果物のパイプラインは別の哲学に立っている。

両者は外見が似ていても運用特性が違う。

legal-research や llm-wiki のような「ingest → extract → compile → query」を組むなら、ファイル駆動の方が筋がいい——中断・再開・人間の介入・別エージェントの横入りが全部タダだから。session-state モデルが効くのは、対話型チャット agent のように「1 セッションで完結する」用途だ。

ここで、ADK の eval が手厚い理由が見えてくる。session-state が緩く、評価対象が確率的だから、LLM-as-judge と adaptive rubric が要る。ファイル駆動で成果物が JSON スキーマで固定されていれば、JSON schema 検証と軽い metric で大半が片付く——LLM-as-judge が要るのは最終的な文体評価だけ。

つまり「ADK eval の手厚さ」は ADK の弱点を補うための物でもあり、別モデルから見ると過剰になり得る。両方の側面を見ておく必要がある。

6. 採用判断——3 段階

ここまで読むと、採用判断は全か無かではなく、レイヤごとの 3 段階になる。

LangGraph / ADK / 素 Python の議論を一段抽象化すると、判断は「自分の独自性がどこにあるか」に依存する。orchestration が独自性なら framework は不要（素 Python で書く）。検索パイプラインや ingest が独自性なら、orchestration は薄くしておいて framework は使わない方が、独自性が前に出る。

逆に、Google Cloud に組織として全乗りする前提があるなら、agents-cli を素直に採用するのが最短だ。skill が自動で coding agent に降ってきて、Cloud Trace と Agent Runtime まで一気通貫で動く。フレームワーク選定で時間を使うより、ドメインロジックに集中する経路として理に適っている。

7. 一つの応用——judge を pluggable にして借りる

ファイル駆動の自作パイプラインを持っている側からの実用案を一つ。ループドライバ（ralph 等）の judge を外部 CLI 委譲にしておくと、agents-cli の eval をそのまま judge として刺せる。

[ループドライバ]
  ↓ 1 イテレーション完了
  ├─ 成果物を JSON で吐く（artifact.json）
  └─ judge_cmd を呼ぶ → {score, reason, suggestions}.json
  ↓ score ≥ threshold で停止 / 未満で次イテレーション

judge_cmd を差し替えるだけで、素の LLM-as-judge / agents-cli eval grade / 自作 clustering を切り替えられる。本体は薄く、判定は差し替え可能にしておけば、Google の eval が手厚ければそのまま乗せられるし、薄ければ自作で済ませられる。検証してから決められる、という設計の余地が残る。

これは「framework を選ぶか自作するか」の二択を回避する話で、framework の良いところだけを CLI 境界で借りる——agents-cli が eval を独立 CLI として切り出している恩恵を、こちらが薄く受け取る形になる。

残った宿題

ここまでは構造の読み解きで、実装の手厚さは未検証。次稿で踏み込みたい論点を 3 つ置いておく：

1. eval analyze の clustering 実装——embedding ベースか LLM 分類か。failure pattern の粒度がどれくらい使い物になるか
2. eval optimize の prompt auto-tune——DSPy 風の勾配最適化なのか、単純な変異 + 採点ループか。手で書き直すのと比べて何倍速いか
3. eval dataset synthesize のシナリオ品質——multi-turn を本当に生成できるのか、人手 fixture との差分はどこに出るか

これらは README からは分からない。uvx google-agents-cli setup で sandbox に落として、SKILL.md と実装を読めば 1 時間で輪郭が見える。手厚ければ「eval CLI を借りる」が現実解になり、薄ければ「方法論だけ吸収して自作」になる。

まとめ

• agents-cli は framework ではない。Claude Code / Codex / Antigravity に skill を撒く CLI で、ADK という framework が裏に立っている
• ADK は Anthropic の workflow 5 分類と素直に対応する薄い orchestration プリミティブ集
• ロックインは段階的。開発・評価はニュートラル、本番は GCP
• eval の CLI 密度が異質。generate → grade → analyze → optimize が並ぶ。中身の手厚さは次稿で検証
• ADK は session-state 駆動、ralph 系はファイル駆動。両者は外見が似ても運用特性が違う
• 採用判断は 全乗り / ADK + local / eval だけ剥がす の 3 段階。自分の独自性がどこにあるかで決まる
• 実用案として、ループドライバの judge を pluggable な外部 CLI にしておけば、agents-cli の eval を借りる / 自作で済ます / 後で乗り換える、を全部開いておける

framework 戦争はもうしばらく続くだろうが、Anthropic の「素の LLM 呼び出しと構造化されたパターン」という主張が正しい方向に進んでいるなら、framework の中身を選ぶより、framework の境界をどこに置くかを選ぶ——という見方が、当面は実用的に思える。agents-cli は、その境界の引き方の一例として、構造から学ぶ価値が十分あった。

検証編で会いましょう。

参考

• 本体: github.com/google/agents-cli
• ドキュメント: google.github.io/agents-cli
• ADK: adk.dev
• Anthropic: Building Effective AI Agents