Feature: Allow for templating of nested objects in instructions

[whoisarpit]

Fixes #575

Summary

Adds support for nested dot-separated references in instruction templates. Users can now access deeply nested values in the state object using a simple dot notation, with optional markers at any level of the path.

This is useful when templating structured data from a previous LlmAgent using output_schema.

Changes

• Enhanced _populate_values function to handle nested dot-separated references
• Supports optional markers at any level with ? suffix (e.g., {user?.profile?.name?})
• Updated existing tests and added new test cases for the nested templating functionality

Examples

Before:

# Only simple values were supported
"{customerId}" -> "1234567890"
"{user:profile}" -> "basic"
"{user.profile.name}" -> "{user.profile.name}"

After:

# Now supports nested references
"{user.profile.name}" -> "John Doe"
"{user.settings.theme}" -> "dark"

# Optional markers at any level
"{user?.profile?.email}" -> "[email protected]"
"{user?.preferences?.theme?}" -> "" (empty if path doesn't exist)

# Invalid paths without optional markers will not be templated instead of throwing an error to avoid breaking changes
"{user.invalid.path}" -> "{user.invalid.path}"

Use Cases

• Accessing complex nested objects in state
• Optional references that gracefully handle missing values
• Better organization of state data with hierarchical structures

This feature enables more flexible template interpolation, allowing for cleaner, more organized state structures while maintaining backward compatibility with the existing flat state model.

[hangfei]

@Jacksunwei PTAL.

[surajksharma07]

Hi @whoisarpit and thanks to everyone who participated in this thread.

We're currently doing some housekeeping on our pull request queue. Given the rapid pace of development and the number of updates since this was last active, there's a good chance this pull request needs to be caught up to the latest version. To help us keep our backlog focused on current pull requests, we are closing this as stale.

If you're still interested in contributing to this change, could you please update to the very latest version of the library and create a new pull request? Our team will be glad to help with the refreshed PRs and answer any questions!

Thanks for your contribution and understanding!”

[boyangsvl]

This is a good feature to have. @ryanaiagent could you help to review?

[adk-bot]

Response from ADK Triaging Agent

Hello @whoisarpit, thank you for your contribution! This is a great feature.

For future PRs, please remember to include a testing plan section in the description. This helps reviewers understand how you've tested the changes and speeds up the review process.

Thanks again!

[ryanaiagent]

Hi @whoisarpit, This PR has merge conflicts that require changes from your end. Could you please rebase your branch with the latest main branch to address these? Once this is complete, please let us know so we can proceed with the review.

[hangfei]

Closing due to inactivity. Please raise a new PR after you fix the conflicts.