State changes made in before_agent_callback not reflected in Llm_Request

[sigott]

In a pure test scenario, I am trying to use the before_agent_callback to change a user question before it gets processed by the LLM. In the below code, before_agent_callback saves the changed question to the session state key 'user_question'. Then I try to include the updated question in the model instructions by using the variable {user_question}.

In the below code , a user asks for the highest price of appl in Jan 2025, the callback changes it to ask for the lowest price then returns None so the operation proceeds. I would expect the LLM to answer the lowest price question but it doesn't. It answers the highest price question.

At the very bottom of the code snippet, I print session and you can see the state['user_question'] contains the lowest price question and the session events contain the, user supplied, highest price question.

I guess I have a few questions:

1. What is the best way to make sure the model gets lowest price question, in this example?
2. Is there any documentation that explains how ADK processes variable interpolation in model instructions? Especially in a case like this where it can come from either the state or the context?

--------Begin Code ---------

def save_question_in_state(callback_context: CallbackContext) -> Optional[types.Content]:
   # Change question to ask for 'LOWEST' price.
    callback_context.state['user_question'] = 'what was the LOWEST price of aapl in Jan 2025?'
    return None

def get_model_instruction() -> str:
    return """blah blah blah {user_question} blah blah blah"""

question_agent= LlmAgent(
    name="question_agent",
    model="gemini-2.5-flash-preview-09-2025",
    instruction=get_model_instruction(),
    description=get_agent_description(),
    before_agent_callback=save_question_in_state
)

async def call_agent_async(user_question: str, runner: Runner, user_id: str, session_id: str):

    content = types.Content(role='user', parts=[types.Part(text=user_question)])
    final_response = "Unable to process question. Please try again." # Default response value

    async for event in runner.run_async(user_id=user_id,session_id=session_id, new_message=content):
        if event.is_final_response():
            if event.content and event.content.parts:
                final_response = event.content.parts[0].text

    return final_response

#####################
# Skip create runner and create session code
#####################

user_question = 'what was the HIGHEST price of aapl in Jan 2205?
agent_response  = await call_agent_async(user_question, runner, user_id, session.id

#--- Print Session ---
latest_session = await session_service.get_session(app_name=app_name, user_id=user_id, session_id=session.id)
pprint.pprint(latest_session, indent=2

Session(
id='user-4-20251008-154225', 
app_name='test_app', 
user_id='user-4', 
state={'user_question': 'what was the LOWEST price of aapl in Jan 2025?'}, 
events=[Event(content=Content(
  parts=[
    Part(
      text='what was the HIGHEST price of appl in Jan 2025?'
    ),
  ],
  role='user'
), 
Event(content=Content(
  parts=[
    Part(
      text="""1. Did you mean Apple Inc. (AAPL)?
2. Since January 2025 is in the future, are you asking for a prediction or forecast of the highest price, or did you intend to ask about a past month (e.g., January 2024)?
3. If you are looking for a prediction, are you interested in analyst consensus targets, technical analysis projections, or implied volatility estimates?
4. Are you interested in the highest intraday trading price reached during the month, or the highest daily closing price?
5. Are you referring to the price on the NASDAQ exchange?"""
    ),
  ],
  role='model'

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The easiest way to ensure the model receives your modified question is to use a different variable name in your agent's instruction. The name user_question is likely conflicting with a variable implicitly created from the user's direct input.

---

Hello! Thanks for the detailed question. Here’s an explanation of what's happening and how you can achieve your goal.

1. How to ensure the model gets the modified question

Your current approach isn't working because of the order in which ADK resolves variables for prompt templating. When you provide a new_message to runner.run_async, its contents are made available to the agent in the immediate context. It appears the template variable {user_question} is being filled from this context, which contains the original, user-provided question. This happens before the framework looks at the session state.

The most straightforward solution is to avoid this variable name collision.

Recommended Change:

1. In your before_agent_callback, save the modified question to a differently named key in the session state.
2. Update your model instruction to use this new variable name.

Here is the updated code:

# In your callback, use a new key, e.g., 'modified_question'
def save_question_in_state(callback_context: CallbackContext) -> Optional[types.Content]:
   # Change question to ask for 'LOWEST' price.
    callback_context.state['modified_question'] = 'what was the LOWEST price of aapl in Jan 2025?'
    return None

# Update the instruction to refer to the new state variable
def get_model_instruction() -> str:
    return """blah blah blah {modified_question} blah blah blah"""

# Your agent definition remains the same
question_agent= LlmAgent(
    name="question_agent",
    model="gemini-2.5-flash-preview-09-2025",
    instruction=get_model_instruction(),
    description=get_agent_description(),
    before_agent_callback=save_question_in_state
)

By using {modified_question}, you are explicitly telling ADK to pull this value from the session state, bypassing the conflict with the original user input. Using the session state to pass information between turns or agents is a core pattern in ADK. [1]

2. Documentation on Variable Interpolation

You're correct that this behavior stems from how ADK handles variable interpolation. The framework automatically makes values available for templating in your agent's instructions.

While the documentation may not specify a rigid order of precedence, the behavior you've observed is intentional: variables from the immediate context (like the current user message) are prioritized over variables from the general session state. This ensures that agents are responsive to the most recent user input.

The documentation on Session State mentions that you can inject values from the state into an instruction using the {variable_name} syntax, which is exactly what the solution above does. [1]

For more advanced scenarios, such as modifying the final request sent to the LLM, you could also use the before_model_callback. This callback gives you access to the LlmRequest object just before the API call is made. [2] However, for your use case, simply using a different state variable is the cleanest and recommended approach.

Hopefully, this clarifies things!

---

[1] Session State - ADK Documentation (https://google.github.io/adk-docs/sessions/state/)
[2] Types of Callbacks - ADK Documentation (https://google.github.io/adk-docs/callbacks/types-of-callbacks/)

[sigott]

Changing the prompt template to use{modified_question} did not work.
The prompt still contained the value from context (user supplied) and not the value assigned to session.state.

If I comment out the line that sets the session key
callback_context.state['modified_question'] = 'what was the LOWEST price of aapl in Jan 2025?'

I get the error KeyError: 'Context variable not found: modified_question.'

The behavior is such that, if I do not set session.state['modified_question'] in the callback function, I get a KeyError but if I do set it, the prompt variable gets interpolated from the context value and not the session.state value.