変数

変数は、会話のターンをまたいでデータを保存および取得するために使用されます。これにより、エージェントは情報を記憶し、コンテキストを維持できます。 エージェントのプロンプト手順を記述するときに、これらの変数への参照を含めることができます。

変数の種類

エージェント ビルダーでは、手順で 2 種類の変数（静的変数と動的変数）がサポートされています。

適切なタイプを選択するかどうかは、ユーザーのセッション中に変数の値を変更する必要があるかどうかと、レイテンシをどの程度最適化する必要があるかによって異なります。

静的変数

静的変数は、モデル呼び出しが行われる前にエージェント プロンプトに直接コンパイルされます。 直接的な 1 対 1 のテキスト置換として機能し、更新頻度は低くなります。

静的変数は、手順の遵守品質を最大限に高め、多くのシナリオで条件付きの手順に適しています。 静的変数は、構成データ、厳格なビジネスルール、1 回の会話の存続期間中に変更されない大きなコンテキスト ペイロードに使用します。

手順で静的変数を名前で参照するには、 二重中かっこを使用します: {{variable_name}}。

たとえば、大規模な静的商品カタログを持つ小売エージェントを作成する場合は、次のような手順を使用できます。

You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.

動的変数

動的変数は、会話中にツール、コールバック、API リクエストによっていつでも更新できます。 プロンプトのテキストに直接代入されることはありません。 代わりに、更新されると、新しい値が state update イベントとして会話履歴に追加されます。 例: <state_update>var_name: value</state_update>。

動的変数は、セッション中にユーザーから抽出された情報、外部 API（ツール）から取得された出力、会話の進行に伴って変化する状態に使用します。

動的変数には次のデメリットがあります。

  • 動的変数は会話履歴に追加されるため、長いセッションがコンテキスト ウィンドウの制限を超えると、履歴のトリミング時に変数値が失われる可能性があります。
  • 動的変数は、静的変数と比較して手順の遵守度が若干低くなる可能性があります。 これは、変数値が手順から離れて定義されているためです。 また、モデルの思考が手順から離れた場所で値を見つける必要があるため、レイテンシが増加する可能性があります。

手順で動的変数を名前で参照するには、単一の中かっこ {variable_name} を使用します。

たとえば、ユーザーを認証してからツールを使用して特定のアカウントの詳細を検索する必要があるエージェントを作成する場合は、次のような手順を使用できます。

If the user asks for their balance, call the {@TOOL: LookupBalance}.
The tool will update the {current_account_balance} variable.
Always share the {current_account_balance} with the user.

変数データ

変数には次のデータがあります。

  • 名前: スネークケースを使用した変数名
  • タイプ: 基盤となるデータ型:
    • テキスト: 文字列の値
    • 数値: 数値
    • はい/いいえ: ブール値
    • カスタム オブジェクト: オブジェクトのスキーマを指定します
    • リスト: 変数のリスト。値をカンマ区切りのリストとして指定します。
  • デフォルト値: 変数のデフォルト値
  • 説明: 変数の説明（省略可）

変数の値を更新する

エージェント自体は変数の値を更新できませんが、ツールとコールバックは変数の値を更新できます。

エージェント変数は ADK コンテキストの状態を使用します。 これを使用して変数を更新できます。 context というグローバル変数を Python ツールコードで使用できます。たとえば、Python ツールで次のステートメントを使用して、ADK 機能を使用して変数を更新できます。

context.state["variable_name"] = value

組み込みセッション コンテキスト変数

カスタム変数に加えて、OpenAPI ツールと MCP ツールは組み込みセッション コンテキスト変数を参照できます。これらはデフォルトで使用でき、HTTP ヘッダーまたはリクエスト パラメータ内で渡すことができます。これらの変数は手順で参照できず、手動で上書きすることもできません。 次の組み込み変数を使用できます。