[Python] How to pass session.state variable to LlmAgent's global_instruction in google.adk?...

I'm using the Google Agent Development Kit (google.adk) to build an LlmAgent and serving it as an A2A server using the to_a2a utility.

I am trying to use a format string variable ({domain_instructions}) in the LlmAgent's global_instruction to provide different instructions per session.

My Agent Setup (Python)


Here is my LlmAgent configuration and uvicorn server code:

from dotenv import find_dotenv, load_dotenv
from google.adk.agents import LlmAgent
from google.adk.a2a.utils.agent_to_a2a import to_a2a
from google.adk.models.llm_request import LlmRequest
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from google.adk.a2a.converters.request_converter import convert_a2a_request_to_adk_run_args
import uvicorn

# load_dotenv(find_dotenv()) # If needed

orchestrator_agent = LlmAgent(
model='gemini-2.0-flash',
name='SupervisorAgent',
description='Analysis Agent', # Custom data analysis agent per user
instruction="{domain_instructions}", # You are a data analysis agent.
)

a2a_app = to_a2a(orchestrator_agent, port=9000)

if __name__ == "__main__":
uvicorn.run(a2a_app, host="0.0.0.0", port=8008)

The JSON-RPC Request I'm Sending


I am trying to pass the value "Only french" to the {domain_instructions} variable via the session.state object:

{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"message": {
"messageId": "msg-002",
"parts": [
{
"text": "Hello?"
}
],
"role": "user"
}
},
"session": {
"state": {
"domain_instructions": "Only french"
}
},
"id": "req-002"
}

The Problem (Error)


When I send this request, the server logs the following KeyError:

KeyError: 'Context variable not found: 'domain_instructions'

This error seems to mean that the ADK framework could not find the domain_instructions variable when trying to format the global_instruction string.

My Question


What is the correct way to inject a variable from session.state (or elsewhere in the A2A request) into the global_instruction format string of an LlmAgent?

Is using session.state the correct approach, or do I need a different configuration when setting up the LlmAgent?

Error Traceback

2025-09-15 13:23:43,202 - ERROR - a2a_agent_executor.py:154 - Error handling A2A request: 'Context variable not found: `domain_instructions`.'

Traceback (most recent call last):
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\a2a\executor\a2a_agent_executor.py", line 152, in execute
await self._handle_request(context, event_queue)
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\a2a\executor\a2a_agent_executor.py", line 219, in _handle_request
async for adk_event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\runners.py", line 250, in run_async
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\runners.py", line 246, in _run_with_trace
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\runners.py", line 290, in _exec_with_plugin
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\runners.py", line 240, in execute
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\agents\base_agent.py", line 236, in run_async
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\agents\base_agent.py", line 226, in _run_with_trace
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\agents\llm_agent.py", line 288, in _run_async_impl
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\flows\llm_flows\base_llm_flow.py", line 346, in run_async
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\flows\llm_flows\base_llm_flow.py", line 365, in _run_one_step_async
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\flows\llm_flows\base_llm_flow.py", line 412, in _preprocess_async
async for event in agen:
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\flows\llm_flows\instructions.py", line 76, in run_async
si = await instructions_utils.inject_session_state(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\utils\instructions_utils.py", line 113, in inject_session_state
return await _async_sub(r'{+[^{}]*}+', _replace_match, template)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\utils\instructions_utils.py", line 72, in _async_sub
replacement = await repl_async_fn(match)
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\ktaek\anaconda3\envs\a2a\Lib\site-packages\google\adk\utils\instructions_utils.py", line 111, in _replace_match
raise KeyError(f'Context variable not found: `{var_name}`.')

KeyError: 'Context variable not found: `domain_instructions`.'

Continue reading...