🚀 ADK徹底解説｜StateとArtifactを使った動的プロンプトの作り方

今回は、GoogleのAgent Development Kit（ADK） を使う際に超便利な、
「インストラクション（プロンプト）内でのプレースホルダー置換」 機能について紹介します。

公式ドキュメントではあまり強調されていないですが、
実はかなり使える機能だったので、詳しく掘り下げていきます！

🎯 そもそもの課題｜コンテキストに応じたプロンプトを作りたい

AIエージェントを作るとき、こんなことをしたくなりませんか？

• ユーザーが前に入力したデータを参照したい
• 過去のツールの出力結果をプロンプトに入れたい
• 保存しておいたドキュメントを要約させたい

このためにADKには、
✅ session.state（セッション中の状態保存）
✅ ArtifactService（ファイルなどの管理）
といった仕組みがあります。

でも、毎回大量のデータを直接プロンプトにベタ書きするのは大変だし、
LLMのコンテキストウィンドウ（入力できる最大トークン数）にも引っかかりやすい……。

もっとスマートな方法が欲しいですよね。

---

🧩 解決策｜インストラクション内のプレースホルダー置換

ADKのソースコードを読み込んだところ、
実は instruction 文字列の中に {} で囲んだプレースホルダーを書くと、
自動で置換してくれる仕組みがあることが判明しました！

✨ 使えるプレースホルダー一覧

1. Session Stateを参照

   • {key} または {state.key} → session.state['key']
   • {app:key} → アプリスコープのstate
   • {user:key} → ユーザースコープのstate
   • {key?} → 省略可能なプレースホルダー（無いときは空文字になる）

2. Artifactを参照

   • {artifact.filename} → 指定したアーティファクトファイルの中身に置換

置換時には値が自動で文字列化されるので、型を気にしなくてOKです。

---

🛠️ 実際の使い方｜サンプルコード紹介

ここからは実際に、どうやって使うかを見ていきましょう！

📜 例①：Stateの値を参照する（Generator-Criticパターン）

from google.adk.agents import Agent

# Generatorエージェント：下書きを作成してstateに保存
generator = Agent(
    name="generator_agent",
    model="gemini-2.0-flash",
    instruction="Write a short paragraph about subject X.",
    output_key="draft_text"
)

# Reviewerエージェント：stateから下書きを読み込んでレビュー
reviewer = Agent(
    name="reviewer_agent",
    model="gemini-2.0-flash",
    instruction="Please review the following draft: {draft_text}. Check for factual accuracy and provide feedback."
)

こんな感じで、自然な形でデータをバトンタッチできます！

(この例がドキュメントには違う形式で記載されているので混乱する...)

---

📁 例②：Artifactのファイルを参照する

from google.adk.agents import Agent

# meeting_notes.txtというファイルをもとに要約
summarizer = Agent(
    name="summarizer_agent",
    model="gemini-2.0-flash",
    instruction="Summarize the document provided in the artifact named 'meeting_notes.txt': {artifact.meeting_notes.txt}"
)

Artifactを使えば、ドキュメントを丸ごとプロンプトに載せることも可能です！

---

🛠️【応用】コード側でインストラクションを組み立てる方法も

ちなみに、プレースホルダーを使わず、
Pythonコード内で動的にinstructionを組み立てる方法もあります。

# コールバック関数でインストラクションを動的にセット
def update_instruction_before_call(callback_context: CallbackContext, llm_request: LlmRequest):
    draft = callback_context.state.get('draft_text', '')
    llm_request.config.system_instruction = f"Please review the following draft: {draft}. Check for factual accuracy."
    return None

reviewer = Agent(
    name="reviewer_agent",
    model="gemini-2.0-flash",
    instruction=None,
    before_model_callback=update_instruction_before_call
)

こちらは柔軟性重視ですが、
シンプルな置換だけならプレースホルダーの方が圧倒的にきれいですね！

---

📝 まとめ

まとめると…

• {key} {artifact.filename} のような プレースホルダー を使えば
• session.stateやArtifactServiceのデータを
• 簡単＆安全にインストラクションに埋め込める！

ただし、
現時点では公式ドキュメントで明確に紹介されていない内部仕様っぽいので、
今後のバージョンアップで仕様変更されるリスクはゼロではありません⚠️

とはいえ、
ソースコードやユニットテストにもしっかり実装されているので、
「現行バージョンでは安心して使える機能」と考えて問題ないでしょう！

---

🌟 ADKを使ったエージェント開発をもっとスムーズにしたい方は、
ぜひこのプレースホルダー置換、活用してみてください！