How Do Agents Access State Variables? Understanding State Value Retrieval in LLM Agents

[shenshiqiSSQ]

I have a question: In the instruction for an agent like this:

instruction="Read state['current_code'] (if exists) and state['requirements']. Generate/refine Python code to meet requirements. Save to state['current_code']."
I'm unsure whether the agent actually knows the contents of state or if it retrieves information from the context. I know that using {{}} (e.g., {{current_code}}) in the instruction will trigger state value substitution, but does the agent automatically fetch values when the format is state['current_code'] or just 'current_code'?

[adk-bot]

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

TLDR: The {{variable}} syntax in an agent's instruction is for automatically injecting values from the session state into the instruction string. In contrast, state['variable'] is used for programmatically accessing the state within the code of tools, callbacks, and custom agents.

---

Hello! I can provide some information on how agents access state variables in ADK.

There are two primary ways to interact with the session state:

1. Automatic State Injection in Instructions: When you use the {{variable}} syntax in an agent's instruction string, the ADK framework automatically substitutes that placeholder with the value of session.state['variable'] before the instruction is sent to the LLM. This is a convenient way to provide context to your agents without writing extra code.

   For example, if you have session.state['topic'] = 'dolphins' and your instruction is Write a poem about {{topic}}, the final instruction sent to the LLM will be Write a poem about dolphins. [1]

2. Programmatic Access via Context Objects: Inside the code of your tools, callbacks, or custom agents, you can directly access and manipulate the session state.

   • Tools: Tools can access the session state via tool_context.state. [2]
   • Callbacks: Callbacks can access the session state via callback_context.state. [3]
   • Custom Agents: In custom agents, you can access the state directly. [4]

In your example, state['current_code'] would be used in the code of a tool or callback to get the value of current_code from the session state. The agent's instruction would then be something like Read the code and generate/refine it to meet the requirements: {{current_code}}.

You can also have an agent automatically save its output to the session state by using the output_key parameter. For example, if you set output_key='refined_code', the agent's response will be saved to session.state['refined_code']. [5]

I hope this helps clarify how state variables are accessed in ADK!

---

[1] https://google.github.io/adk-docs/agents/custom-agents/
[2] https://google.github.io/adk-docs/tools/
[3] https://google.github.io/adk-docs/context/
[4] https://google.github.io/adk-docs/sessions/state/
[5] https://google.github.io/adk-docs/agents/multi-agents/

[xuanyang15]

@shenshiqiSSQ Thanks for your question! LLM doesn't have direct access to the session states, so using state['current_code'] in the instruction to let LLM read or write state values will not work.

[wdanxna]

Thanks for you answer, but how do you explain that in this official demo at this line: deep_research, the instruction explicitly asks the llm to inspect certain key(research_plan) in seession state, as if the llm is aware of the concept of session state and how to retrieve it? The same "refered but not injected" pattern can also be seen here

Is that a mistake?

[xuanyang15]

Hi @wdanxna, thanks for your question! It is actually a great question that touches on a subtle but important distinction in how ADK agents receive information.

TLDR: the from the 'research_plan' state key instruction doesn't make LLM read the research_plan directly from the session state, because it doesn't has the access. However, the LLM can find the research plan through conversation history.

The demo code was not added by ADK developers, so I'm not sure the author's intention:

• If the intention is to tell the LLM to directly access session state, then yes, it is a mistake
• If the intention is just a descriptive comment explaining where the information originates, it makes sense

Why the deep-search Example Works

In the deep-search sample, the research_pipeline is a SequentialAgent with this structure:

SequentialAgent(
    name="research_pipeline",
    sub_agents=[
        section_planner,      # Runs first
        section_researcher,   # Runs second - sees previous agent's output
        ...
    ]
)

Here's what happens:

1. interactive_planner_agent (or plan_generator) runs first and outputs the research plan. It has output_key="research_plan", which saves its output to session.state['research_plan'].
2. More importantly, the text output of that agent is stored as an Event in the session.
3. When section_researcher runs, ADK's _present_other_agent_message function converts the previous agent's output into user-role context:

For context:
[plan_generator] said: <the actual research plan content here>

4. This content is included in the LLM's context, so section_researcher can "see" the research plan through conversation history.

Summary of two Mechanisms for Passing Information to Agents

Mechanism	Syntax	How It Works
State Injection	{variable_name}	ADK substitutes the state value directly into the instruction string before sending to LLM
Conversation History	No special syntax needed	Previous agent outputs are automatically included in the LLM context

Conclusion

• LLMs cannot directly access session state - this is correct
• {variable_name} syntax injects state values into instructions - this is recommended, since the Conversation History approach is not always working
• Conversation history automatically passes previous agent outputs to subsequent agents in a SequentialAgent
• The deep-search example works because the research plan flows through conversation history, not because the LLM reads state directly
• The instruction text mentioning "state key" is descriptive documentation, not a functional directive

[surajksharma07]

@shenshiqiSSQ To recap: the LLM never reads session state directly. {{variable}} in an instruction injects the value before the prompt is sent while state['key'] only works from tool/callback/custom-agent code. The deep_research sample's wording just describes where the value comes from, it actually reaches the LLM through conversation history in the SequentialAgent pipeline. Closing this out since it looks addressed, feel free to reopen or comment if anything's still unclear.