AI エージェントとは、入力を受け取るたびに LLM（頭脳）が「次に何をすべきか」を判断し、必要に応じて外部ツールを実行し、その結果を再度 LLM に渡しながら処理を段階的に進める仕組みである。
では、このエージェント的アプローチが、具体的にソースコード開発においてどのように活用されうるのだろうか。
そこで、Google が OSS として公開している Gemini CLI を例に、その内部構造とエージェントの挙動を見てみたい。LLM エージェントが実際にどのようにツールを呼び出し、どのようなループでコード編集を行っているのかを可視化できる点が大きな魅力である。OSS で実装が見えるというのは、まさに時代の変化を象徴していると言える。
Gemini CLI のエージェント構造を読み解く
1. セットアップ
Gemini CLI のリポジトリをクローンする：
まず、Claude Code に「Gemini CLI のエージェント動作とは何か」を尋ねると、次のような回答が得られる。
1. ユーザー入力を受け取る
2. LLM（Gemini）がタスクを分析
3. 必要に応じてツールを呼び出す
- run_shell_command（シェルコマンド実行）
- read_file（ファイル読み取り）
- write_file（ファイル書き込み）
- edit_file（ファイル編集）
4. ツール結果をLLMに返す
5. LLMが次のアクションを決定（さらにツール呼び出し or 回答生成）
6. 完了まで 3〜5 を繰り返す
これは極めてシンプルなループでありながら、本質をよく捉えている。LLM は「一度で完結する回答」を返すのではなく、必要な手順を分割し、外部ツールを組み合わせながら問題を解く。Gemini CLI は、この一連の流れをそのまま実装している。
2. Telemetry によるエージェント内部の可視化
Gemini CLI には、開発者向けの Telemetry が標準で付属している。
ローカル開発ガイド に従って設定すると、ローカルマシン上で実行したエージェントが「どのようなステップを踏んだのか」をトレースできる。
私は以前、この種のトレースを自作していたが、標準でバンドルされているのは非常にありがたい。AI エージェントの挙動を理解するには、実際に内部で何が起きているのかを見るのが最も早い。
たとえば、n8n のリポジトリ上で Gemini CLI を起動し、次のように指示を与えてみる：
「ノードをボードに置いたとき、強くハイライトするようにしたい。」
すると Telemetry には、次のように各ステップの履歴が記録される。
左側に並んでいるのが、エージェントが処理を進めた時系列である。
典型的には次のように並ぶ：
- submitQuery
- generateContent(Stream)
- schedule
- [tool]（glob / read_file / run_shell_command など）
- submitQuery
- generateContent(Stream)
……
まさに「LLM が判断 → ツールを実行 → 結果を受け取って次の判断へ」というループが繰り返されていることが視覚化されている。
3. エージェント動作の深掘り：1ステップの“入出力”を見る
Telemetry のログを詳細に追うと、1 回のステップでどのような I/O が行われているかがわかる。
以下は、あるステップで Gemini が返した出力の例である。
次に、同じステップの Telemetry ログを見てみる。
このインプットには（長すぎてスクショは省略）、
- システムプロンプト
- read_file の結果（ファイル内容）
- ユーザー要求
- 現在の作業ステップ
- 直前のツール出力
などがすべて含まれている。
つまり、必要な文脈をすべて整え、それを 1 回分の推論として LLM に渡しているにすぎない。
そして、LLM のアウトプットには次のアクションが記述される。
- 修正対象ファイルのパス
- 修正方法（replace）
- 置換後のコード
この出力を外部ループが受け取り、実際のファイル操作を行い、その結果をまた次の推論のインプットに加える。
これこそが Gemini CLI のエージェント動作の核心であり、
「前ステップのアウトプットを、次ステップのインプットへ」
「そのインプットを元に LLM が推論し、また次のアクションを返す」
というシンプルなループである。
4. コーディングエージェントの最小原理
以上の観察から、AI エージェントの構造は次のように理解できる。
- LLM は単発推論を行っているだけ
- 外部ループが、正しい推論ができるよう文脈を整えている
- ツール呼び出しは、LLM が参照すべき最新状態を提供するための仕組み
- 一連の連続性は「状態を受け渡す外部制御」の結果
- エージェントの“賢さ”は LLM の性能ではなく、外側の I/O 設計に大きく依存する
つまり、エージェントが高度な思考をしているように見えても、その実態は 「LLM がより良いアウトプットを返せるように、周辺がインプットを最適化し続けているだけ」 である。
この最小原理こそが、コーディングエージェントを理解するための出発点である。
複雑なエージェント設計を学ぶ前に、このような OSS を読み解くことには大きな意味がある。
まとめ：最小原理を理解すれば、より良いエージェントを設計できる
Gemini CLI を観察すると、AI エージェントの実態は驚くほど単純である。
- LLM は毎回“単発の推論”を行うだけ
- その精度を高めるため、外部ループがツールを使い文脈を逐次再構築する
- 前ステップの結果を次ステップに渡す I/O パイプラインが全体の連続性を生んでいる
この構造を理解すると、「ではどうすればより良いエージェントを作れるか」という議論が自然に始められる。
例えば、
- どの情報を LLM に渡すべきか
- ファイルスキャンや差分計算の粒度
- 計画フェーズと実行フェーズの分離
- 状態管理の方式
- LLM 呼び出しの回数とプロンプトの設計
といったポイントが、すべて「最小原理の延長線」で説明できる。
Gemini CLI は、その理解のための最良の教材である。
おそらくClaudeCodeはエージェントワークフローがもっと複雑でコーディングに最適化されているんだろうと思う。