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.