-
Notifications
You must be signed in to change notification settings - Fork 2.4k
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": "[email protected]"
}
}
}
# 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}).