Fix double-brace escaping in inject_session_state

[ItsMacto]

• Add check in _replace_match() to detect {{variable}} patterns
• Return unescaped content without attempting state lookup
• Add 6 regression tests covering basic escaping, mixed usage, and real-world code examples
• Fixes Template variable escaping with double braces doesn't work as documented #3527

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: Template variable escaping with double braces doesn't work as documented #3527

Problem:
The ADK documentation states that double braces ({{ / }}) escape literal curly braces in instructions (e.g., {{user_id}} should render as {user_id}), but inject_session_state() currently matches {{...}} and attempts template substitution from session state. This can raise a KeyError when the variable is not present and prevents including realistic code examples (Python f-strings / JS template literals) in instructions.

Solution:
In instructions_utils.py, _replace_match() now detects {{...}} matches and returns the unescaped content ({...}) without attempting state/artifact lookup. This implements the documented escaping behavior while preserving existing substitution behavior for normal {name} patterns.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Passed pytest summary:

• pytest tests/unittests/utils/test_instructions_utils.py -q (passed)
• pytest tests/unittests -q (passed)

Manual End-to-End (E2E) Tests:
Not required for this change. This is a pure string-templating behavior fix covered by unit tests, and no runtime configuration or external services are involved.

Checklist

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

This change follows the behavior documented in the ADK State docs: double braces are used to include literal braces in instructions. Tests cover basic escaping, mixed escaping + substitution, and the real-world examples called out in the issue (Python f-strings and TypeScript/JavaScript template literals).

[gemini-code-assist]

Summary of Changes

Hello @ItsMacto, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request resolves a critical issue in the inject_session_state function where double curly braces, intended for literal brace escaping, were erroneously treated as template variables. The implemented solution ensures that the utility now correctly processes these patterns, enhancing the robustness and adherence to documentation for instruction templating. This change prevents unexpected errors and improves the ability to include code examples containing curly braces within instructions.

Highlights

• Double-brace escaping: The inject_session_state utility now correctly interprets {{variable}} as an escaped literal {variable} instead of attempting a template substitution, aligning with ADK documentation.
• Core Logic Update: The _replace_match() function in instructions_utils.py has been enhanced to detect double-brace patterns and return the unescaped content, preventing KeyError exceptions.
• Comprehensive Testing: Six new regression tests have been added to cover various scenarios, including basic escaping, mixed substitution, and real-world examples like Python f-strings and TypeScript template literals.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/google/adk/utils/instructions_utils.py
  • Updated string literals from single quotes to double quotes for consistency.
  • Modified _replace_match function to detect {{...}} patterns and return the inner content with single braces, implementing the documented escaping mechanism.
  • Adjusted string formatting for logging and KeyError messages to use double quotes.
  • Updated the regex pattern in _async_sub to use double quotes.
  • Changed string splitting and prefix checking in _is_valid_state_name to use double quotes.
• tests/unittests/utils/test_instructions_utils.py
  • Added test_inject_session_state_with_double_brace_escaping to verify basic double-brace escaping.
  • Added test_inject_session_state_with_double_brace_escaping_and_normal_substitution to test mixed scenarios.
  • Included test_inject_session_state_with_python_fstring_example to ensure Python f-string syntax is handled correctly.
  • Added test_inject_session_state_with_typescript_template_literal for TypeScript template literal compatibility.
  • Introduced test_inject_session_state_with_multiple_double_brace_patterns to validate multiple escaped patterns.

Activity

• The pull request was created by ItsMacto.
• The changes address and close issue Template variable escaping with double braces doesn't work as documented #3527, which reported the incorrect handling of double braces.
• The author has added new unit tests to cover the introduced functionality and confirmed all existing and new unit tests pass locally.
• A self-review was performed, and code comments were added where necessary.
• Manual end-to-end testing was deemed not required as the fix is a pure string-templating behavior change covered by unit tests.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request correctly implements escaping for double-braced variables like {{variable}} in inject_session_state. The logic change is clear and accompanied by a comprehensive set of regression tests that cover various use cases. The overall code quality is good. My only concern is a subtle change in behavior for nested braces like {{{variable}}} which I've detailed in a specific comment. Otherwise, this is a solid fix.

[ryanaiagent]

Hi @ItsMacto , Thank you for your contribution! We appreciate you taking the time to submit this pull request. Can you please address the suggestion above.

[ItsMacto]

Yes @ryanaiagent doing it now

[ItsMacto]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively addresses the issue of double-brace escaping in inject_session_state. The logic added to _replace_match correctly handles {{...}} patterns by unescaping them, while leaving single-brace and triple-brace patterns to be processed as template variables. The addition of several regression tests, including for real-world code examples like Python f-strings and JS template literals, is excellent and ensures the fix is robust. The code is clean and the changes are well-tested. I have one minor suggestion to simplify the condition for detecting escaped braces.

[ItsMacto]

@ryanaiagent I have addressed the comments. Thanks