Googleが提供するオープンソースのADK（Agent Development Kit）を利用してAIエージェントを開発する際、「ユーザーからの入力とは別に、特定の画像やドキュメントをあらかじめエージェントにインプットしておきたい」と思うことはありませんか？

毎回入力プロンプトとしてファイルを添付する実装も可能ですが、運用上あまりスマートではありません。

この記事では、Google ADKを使ってAIエージェントに静的ファイル（画像やドキュメント）をプロンプトとして読み込ませる方法を解説します。ローカルファイルの読み込みからCloud Storageの活用まで紹介しますので、ぜひ参考にしてください。

static_instruction とは？

具体的なコードを見る前に、今回活用する static_instruction というパラメータについて簡単に解説します。

Google ADKにおける static_instruction とは、google-adkのバージョン1.15.0で追加されたAIエージェントに固定のコンテキスト（前提知識や参考資料）を持たせるための設定項目です。

通常、ユーザーからの質問や指示は毎回変わりますが、static_instruction に設定したテキストや画像、ドキュメントは、エージェントが常に保持する「ベースとなる知識」として機能します。これにより、ユーザーが毎回プロンプトで背景を説明したり、ファイルを添付したりする手間を省き、エージェントに安定した前提条件を共有させることができます。

検証環境

本記事の検証は、以下のバージョン環境で行っています。バージョンが異なる場合、挙動が変わる可能性がありますのでご注意ください。

google-adk 1.27.1

ローカルのファイルを読み込ませる方法

まずは、ローカル環境に保存されている画像ファイルを読み込ませるコードです。

from google.adk.agents.llm_agent import Agent
from google.genai import types

with open("your-agent-folder/images/image.png", "rb") as f:
    data = f.read()

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    description="質問回答エージェント",
    instruction="ユーザーの質問に答えて。",
    static_instruction=types.Content(parts=[
        types.Part.from_bytes(
            data=data,
            mime_type="image/png",
        )
    ])
)

上記のように static_instruction に対して Part.from_bytes を設定することで、エージェントは画像ファイル全体をあらかじめ読み込んだ状態で回答を行ってくれます。

↓実行例(猫の画像を読み込ませています。)

Cloud Storage（クラウド）のファイルを読み込ませる方法

画像やドキュメントファイルをGoogle Cloud Storage (GCS) 上で管理し、そこから読み込ませたい場合は、file_uri を指定することでシームレスに設定が可能です。

from google.adk.agents.llm_agent import Agent
from google.genai import types

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    description="質問回答エージェント",
    instruction="ユーザーの質問に答えて。",
    static_instruction=types.Content(parts=[
        types.Part(
            file_data=types.FileData(
                file_uri="gs://<your-bucket-name>/sample.png",
                mime_type="image/png",
                display_name="サンプル画像1",
            )
        ),
    ])
)

複数のファイルを読み込ませる・テキストを追加する方法

static_instruction には配列形式で複数の Part を渡すことができるため、複数の画像ファイルや、追加のテキスト情報を組み合わせて設定することも可能です。

# 複数ファイルやテキストの読み込み例
static_instruction=types.Content(parts=[
    # テキストの追加
    types.Part(text="ここに追加のコンテキストテキストが入ります。"),

    # 1つ目のファイル
    types.Part(
        file_data=types.FileData(
            file_uri="gs://<your-bucket-name>/images/image_1.png",
            mime_type="image/png",
            display_name="サンプル画像1",
        )
    ),
    # 2つ目のファイル
    types.Part(
        file_data=types.FileData(
            file_uri="gs://<your-bucket-name>/images/image_2.png",
            mime_type="image/png",
            display_name="サンプル画像2",
        )
    )
])

静的ファイルとしてプロンプトに配置するメリット・デメリット

AIエージェントに静的ファイルを直接設定する構成には、いくつかの特徴があります。開発するシステムの要件に合わせて使い分けましょう。

メリット ： コンテキスト汚染を防げる

今回の例では root_agent 単体での動作ですが、本格的なシステムでは複数のAIエージェントを組み合わせることが一般的です。

入力時のプロンプトとして毎回ファイルを添付してしまうと、他のエージェントにも不要な情報が渡ってしまう（コンテキスト汚染）可能性があります。しかし、あらかじめ特定のエージェントの静的ファイルとして配置しておけば、情報がそのエージェント内に限定されるため、ハルシネーション（AIの幻覚）を防ぐ対策として非常に有効です。

デメリット ： 処理時間が長くなる可能性がある

RAG（検索拡張生成）のように必要な部分だけを抽出して読み込む手法とは異なり、この方法ではファイル全体をそのまま読み込みます。そのため、読み込ませるドキュメントの容量や画像の数が大きくなると、それに比例してAIの処理時間（レイテンシ）も長くなる点には注意が必要です。

まとめ

今回はGoogle ADKを利用して、AIエージェントに画像やドキュメントを静的ファイルとして読み込ませる方法について解説しました。

用途に応じてローカルファイルとCloud Storageを使い分け、複数エージェントを組み合わせる際のコンテキスト管理やハルシネーション対策にぜひ役立ててください！

最後まで読んでいただきありがとうございました。この記事が、あなたのAIエージェント開発の参考になれば幸いです。