Repository navigation
Support templating of nested values in instruction template #575
Description
Is your feature request related to a problem? Please describe.
Currently, ADK's instruction templating only supports referencing flat state values via {state_key} syntax. When working with structured data from LLM responses (via output_schema) or organizing state in hierarchical structures, developers are forced to flatten these structures or create redundant state entries.
This makes it difficult to:
- Reference nested values from structured LLM outputs directly in templates
- Maintain clean, organized state with natural hierarchies
- Handle optional values gracefully without error checking
For example, when an LLM returns a structured user profile with nested fields, developers must currently flatten it to reference in templates:
state = {
"user_profile_name": user_profile["name"], # Redundant flattening
"user_profile_email": user_profile["email"], # Redundant flattening
}This leads to verbose, error-prone code and cluttered state objects.
Describe the solution you'd like
Add support for nested dot-separated references in instruction templates that can traverse nested dictionaries in the state object.
For example:
# With a state like:
state = {
"user": {
"profile": {
"name": "John Doe",
"email": "john@example.com"
}
}
}
# Template can use:
instruction = "Hello {user.profile.name}, your email is {user.profile.email}"Additionally, add support for optional path segments with ? suffix to gracefully handle missing values:
# Optional reference that returns empty string if path doesn't exist
"{user?.preferences?.theme?}" -> ""Describe alternatives you've considered
- Flatten State: Add additional code between agent executions to flatten nested structures into dot-notation keys, but this duplicates data and clutters the state.
- InstructionProvider: Pass instruction as a lambda that templates from the state, but this adds complexity to the code flow.
Additional context
This feature would align with modern templating systems found in many frameworks. The dot notation is intuitive for developers and follows common patterns from JavaScript, Python, and other languages for accessing nested properties.
The feature should maintain backward compatibility with existing templates by preserving the current behavior for simple keys and namespaced keys (e.g., {app:key}).
Activity
aschopra11 commentedon Sep 12, 2025
Hi everyone, facing a similar issue where I can't inject a nested key-val pair from my state into our prompt, is there any update here? Thanks!
hangfei commentedon Nov 8, 2025
We are trying to see if we can merge: #574
feat(utils): Add support for nested state access in template injection
docs: Add nested state access documentation for template injection
feat(utils): Add support for nested state access in template injection
Jainish-S commentedon Nov 22, 2025
@hangfei I have raise the PR #3673 and for the docs google/adk-docs#1003
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection
klateefa commentedon Nov 25, 2025
@whoisarpit Thank you for reporting this. I understand the request is currently under review. Please keep me posted if anything else is needed. Thanks for your patience.
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection
berohitverma commentedon Jan 19, 2026
Are there any updates on this fix and when can this be released. We are looking to get this feature asap. This is also a nice way to limit the input tokens so we would like to use it for the optimization of token consumed.
In addition to that @Jainish-S / @Jacksunwei / @hangfei : The feature works nicely with the nested variables in state however when it comes to lists inside state variable having nested json is still an issue. Are you also looking to enhance so it can handle list of nested json/s inside a variable/list?
feat(utils): Add support for nested state access in template injection
Jainish-S commentedon Jan 23, 2026
@berohitverma I have raise a PR - google/adk-python-community#30 so instead of handling each and every cases here, we can use any of the existing templating like Jinja2 and others
feat: support dot-separated nested state values in instruction templates
feat(utils): Add support for nested state access in template injection
feat(utils): Add support for nested state access in template injection