Variables

Variables are used to store and retrieve data across conversational turns. They enable agents to remember information and maintain context. When you write prompt instructions for your agent, you can include references to these variables.

Variable types

The agent builder supports two distinct types of variables in instructions: static variables and dynamic variables.

Choosing the right type depends on whether the variable's value needs to change during the user's session, and how much you need to optimize for latency.

Static variables

Static variables are compiled directly into the agent prompt before the model call happens. They act as a direct 1:1 text substitution and are updated infrequently.

Static variables maximize instruction following quality and are suitable for conditional instructions for many scenarios. Use static variables for configuration data, rigid business rules, or large contextual payloads that don't change over the life of a single conversation.

To reference a static variable by name in your instructions, use double curly braces: {{variable_name}}.

For example, if you are creating a retail agent with a large, static product catalog, you could use an instruction like:

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

Warning: Updating static variable values invalidates prompt caching, which can potentially lead to higher model call latency.

Dynamic variables

Dynamic variables can be updated at any point during a conversation by tools, callbacks, or API requests. They are not directly substituted into your prompt's text. Instead, when they are updated, their new values are appended as state update events to the conversation history. For example: <state_update>var_name: value</state_update>.

Use dynamic variables for information extracted from the user during the session, outputs retrieved from external APIs (tools), or any state that mutates as the conversation progresses.

The following disadvantages apply to dynamic variables:

• Dynamic variables are appended to conversation history, so if a long session exceeds the context window limit, the agent may forget variable values that get lost when trimming the history.
• Dynamic variables could lead to slightly lower instruction adherence compared to static variables. This is due to the variable values being defined further away from instructions. This can also add latency, as model thinking needs to find the value further away from the instruction.

To reference a dynamic variable by name in your instructions, use single curly braces: {variable_name}.

For example, if you're creating an agent that needs to authenticate a user and then look up their specific account details using a tool, you could use an instruction like:

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.

Variable data

Variables have the following data:

• Name: Variable name using snake case
• Type: Underlying data type:
  • Text: String values
  • Number: Numeric values
  • Yes/No: Boolean values
  • Custom Object: You provide a schema for the object
  • List: List of variables. Provide values as a comma delimited list.
• Default value: Default value for the variable
• Description: Optional description of the variable

Updating variable values

The agent itself cannot update the value of a variable, but tools and callbacks can update variable values.

Agent variables use the ADK context state, which can be used to update variables. A global variable called context is available to use in your Python tool code. For example, you can use the following statement in a Python tool to update a variable using ADK features:

context.state["variable_name"] = value