feat: support nested state values in instruction templates

[Ankitajainkuniya]

Summary

Adds support for dot-separated nested state value references in instruction templates.

Before: Only flat top-level keys worked — {user_name} resolves state['user_name']

After: Nested paths work — {user.profile.name} resolves state['user']['profile']['name']

Motivation

When agents use output_schema to receive structured LLM responses, the session state often contains nested dictionaries. Currently, developers must manually flatten these into top-level keys before referencing them in instructions, which is verbose and error-prone.

# Before: manual flattening required
state['user_profile_name'] = state['user']['profile']['name']
instruction = "Hello {user_profile_name}"

# After: direct nested reference
instruction = "Hello {user.profile.name}"

Changes

src/google/adk/utils/instructions_utils.py:

• Added _resolve_nested() helper that traverses nested dicts via dot-separated paths
• Updated _replace_match() to use nested resolution when the variable name contains dots
• Updated _is_valid_state_name() to accept dot-separated identifiers

Backward compatibility preserved:

• Flat keys ({user_name}) — unchanged
• Artifact references ({artifact.file_name}) — unchanged, checked first
• Namespaced keys ({app:key}, {user:key}, {temp:key}) — unchanged
• Optional suffix ({user.missing.key?}) — returns empty string

Tests

Added 5 test cases in tests/unittests/utils/test_instructions_utils.py:

• Nested value resolution ({user.profile.name})
• Missing nested key raises KeyError
• Optional missing nested key returns empty string
• Nested values don't conflict with artifact. prefix
• Flat keys still work as before

Fixes #575

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.