この記事は「Google ADK × コンテクストエンジニアリング」シリーズの一部です。
Andrej Karpathy（OpenAI・Tesla 元AI責任者）が提唱した「コンテクストエンジニアリング」という考え方があります。LLMの性能を引き出す鍵は、モデルそのものではなく、モデルに渡すコンテクストをいかに設計するか――という発想です。
Google ADK（Agent Development Kit）でエージェントを組んでいると、この考え方の重要性を痛感する場面が多々あります。instruction の書き方ひとつ、ツールの返り値ひとつで、エージェントの振る舞いは大きく変わります。にもかかわらず、「ADKの内部で何がどうコンテクストとして組み立てられているのか」を体系的に解説した資料は、まだほとんど見当たりません。
本シリーズでは、ADK のソースコードを読み解きながら、コンテクストを構成する要素を一つひとつ分解し、実務で使えるテンプレートやテクニックに落とし込んでいきます。
📚 シリーズ目次（クリックで展開）
| # | タイトル | 概要 |
|---|---|---|
| 1 | ADKで制御できるコンテクストの全体像 | name, description, instruction, tool, state... ADKで触れるコンテクスト要素の全体マップ |
| 2 | Agentクラス大解剖 — LLMに実際に何が渡っているのか | 内部のプロンプト組み立て順序を解明し、実用テンプレートを提案 |
| 3 | ツール定義の解剖 — 入出力・エラー・descriptionの最適化（近日公開） | Geminiが失敗しやすい引数定義、tool descriptionの自作テクニック |
| 4 | google_search ツールの落とし穴と実践コールバック集（近日公開） | 仕様の罠、引用リンク自動挿入、現在時刻の差し込みなど |
| 5 | 実践Tips集 — タスク管理ツール・デプロイ・運用の小技（近日公開） | write_todo、デプロイスクリプト、現場で使える小技集 |
👉 第1回：ADKで制御できるコンテクストの全体像 ← 今ここ
この記事で得られること
- コンテクストエンジニアリングとは何か、なぜ重要なのかがわかる
- ADK で制御できるコンテクスト要素の 全体マップ が頭に入る
- 各要素がLLMの振る舞いにどう関わるか、概要レベルで把握できる
対象読者: ADK を触り始めた方〜中級者
ADK バージョン: Python v1.16.0+
コンテクストエンジニアリングとは
「プロンプトエンジニアリング」はすでに広く知られた概念です。モデルへの指示文を工夫して、より良い出力を引き出す技術ですね。
一方、エージェントが長期的で複雑なタスクを扱うようになると、プロンプト単体の最適化では不十分になります。Anthropic のエンジニアリングブログでは、コンテクストエンジニアリングという概念を次のように位置づけています。
LLMが推論時に参照する すべてのトークン を設計・管理するアプローチ
対象はシステムプロンプトだけではありません。ツール定義、ツールの実行結果、会話履歴、外部データ――これらすべてが「コンテクスト」としてLLMに渡され、モデルの振る舞いを決定します。
なぜ重要なのか — コンテクスト劣化
「たくさん情報を渡せば精度が上がる」と思いがちですが、実際はそうとは限りません。Anthropic はこれを コンテクスト劣化（Context Rot） と呼んでいます。
Transformer ではすべてのトークンが他のすべてのトークンに注意を向けるため、トークン数 n に対して注意関係は n² で増加します。コンテクストが肥大化するとモデルの注意が分散し、重要な情報へのフォーカスが難しくなる。つまり 「とりあえず全部渡す」はアンチパターン です。
必要な情報を、必要なタイミングで、必要な量だけ渡す。これがコンテクストエンジニアリングの基本思想であり、ADK でエージェントを設計するときにも直接効いてくる考え方です。
ADK で制御できるコンテクスト要素の全体マップ
ADK で制御可能なコンテクスト要素を俯瞰すると、大きく4つの領域に分かれます。
- ① Agent 定義 — name / description / instruction / global_instruction
- ② ツール定義 — 関数名 / description / パラメータスキーマ / ツール実行結果
- ③ 会話履歴・コンテクスト管理 — Session Events / include_contents / AgentTool / Events Compaction
- ④ State — session.state / output_key / instruction への動的テンプレート注入
以下、各領域の要素を概要レベルで紹介します。個別の深掘り（ADK内部でどう組み立てられるか、どう書くべきか）は第2回以降で行いますので、まずは「何がどこに効くのか」の地図を手に入れてください。
① Agent 定義
LlmAgent を定義するときに指定するパラメータのうち、コンテクストに直接影響するものです。
| パラメータ | 概要 |
|---|---|
| name | エージェントの識別子。マルチエージェント構成ではルーティングの参照先として使われる |
| description | 他エージェント（親）がタスク委譲先を判断するための情報。自分自身の役割認識にも使われる |
| instruction | システムプロンプト本体。State の値を {key} で埋め込むテンプレート機能、関数で動的に生成する InstructionProvider が利用可能 |
| global_instruction | ルートエージェントに設定すると、階層内の全エージェントに共通で適用される指示 |
これらがADK内部でどのような順序で組み立てられ、最終的にどんなプロンプトになるかは 第2回 で解剖します。
② ツール定義
tools パラメータに渡すツールの情報です。ツール定義そのものがコンテクストの一部としてLLMに送られます。
| 要素 | 概要 |
|---|---|
| 関数名 | LLMがツールを識別する名前。命名がツール選択の精度に影響する |
| description（docstring） | ツールの目的、いつ使うべきかの説明。LLMのツール選択判断に直接使われる |
| パラメータスキーマ | 引数の名前・型・説明。型ヒントと docstring から自動生成される |
| ツール実行結果 | tool response として次の推論ステップの入力になる。dict 型推奨。エラー時の設計が特に重要 |
Gemini が苦手な引数パターン、description の設計テクニック、エラーレスポンスの設計パターンは 第3回 で集中的に扱います。
③ 会話履歴・コンテクスト管理
マルチターンの対話で蓄積される会話履歴と、その管理手段です。
include_contents
LlmAgent のパラメータで、会話履歴をLLMに渡すかどうかを制御します。デフォルトは 'default'（履歴あり）で、'none' にすると過去の会話履歴を一切渡さずに動作します。文脈に依存しない単発タスク向けのエージェントで有効です。
Sub-Agent vs AgentTool
マルチエージェント構成における、コンテクストの扱いが根本的に異なる2つのパターンです。
| sub_agents（Agent Transfer） | AgentTool | |
|---|---|---|
| コンテクスト | 親と共有 | 分離（独立Session） |
| 親への影響 | 子の全やりとりが履歴に残る | 最終結果のみ |
| ユースケース | 対話の引き継ぎ | 裏側でサブタスクを実行 |
「ユーザーとの対話を引き継ぐ」なら sub_agents、「裏側で処理して結果だけ欲しい」なら AgentTool が基本方針です。AgentTool はコンテクスト分離の手段として非常に強力ですが、独立 Session になることに伴う制約もあります。
Events Compaction
ADK v1.16.0 で導入された機能で、古いイベントをLLMで自動要約してコンテクストサイズを削減します。スライディングウィンドウ方式で、compaction_interval（圧縮間隔）と overlap_size（重複数）を設定します。要約モデルのカスタマイズも可能です。
④ State（セッション状態）
session.state はエージェント間でデータを受け渡すためのキーバリューストアです。コンテクストエンジニアリングの観点で注目すべき点は2つあります。
-
instruction テンプレート注入: instruction 内の
{key}がsession.state['key']の値で自動置換される - output_key: エージェントの最終応答を State に自動保存し、後続エージェントから参照可能にする
State 経由のデータ受け渡しは、会話履歴に全文を残すよりも明示的でトークン効率が良い手段です。「何を State に入れ、何を履歴に残すか」の判断もコンテクスト設計の重要な一部になります。
まとめ
本記事で紹介した全体マップをもう一度まとめます。
| 領域 | 要素 | 深掘り |
|---|---|---|
| Agent 定義 | name / description / instruction / global_instruction | 第2回 |
| ツール定義 | 関数名 / description / パラメータスキーマ / tool response | 第3回 |
| 会話履歴管理 | include_contents / AgentTool / Events Compaction | 第2回・第5回 |
| State | session.state / output_key / テンプレート注入 | 第2回 |
コンテクストエンジニアリングの核心は、 「LLMに渡されるトークンの価値を最大化する」 ことです。ADK はそのための制御ポイントを豊富に提供しています。本記事がその全体像を掴むための地図として役立てば幸いです。
次回の第2回では、LlmAgent の内部に踏み込みます。ここで紹介した name / description / instruction / global_instruction が、ADK のソースコード上でどのような順序で組み立てられ、最終的にLLMに何が渡されているのかを解剖します。
📌 次回: 第2回 Agentクラス大解剖 — LLMに実際に何が渡っているのか