fix: restore double-brace escaping in instruction templates

[stakeswky]

Summary

Fixes #4606

Double braces (e.g. {{city}}) should produce literal {city} in the rendered instruction, not trigger a session state lookup. This escaping worked in v1.25.0 but regressed in v1.25.1.

Root Cause

The regex r'{+[^{}]*}+' in instructions_utils.py matches {{city}}, and _replace_match strips all braces before looking up the variable name, treating it as a state variable city.

Fix

Added an early return in _replace_match: when the matched text starts with {{ and ends with }}, peel one layer of braces and return the literal string without any state/artifact lookup.

This is a minimal 3-line change in _replace_match:

raw = match.group()
if raw.startswith('{{') and raw.endswith('}}'):
    return raw[1:-1]

Changes

• src/google/adk/utils/instructions_utils.py: Added double-brace escape handling
• tests/unittests/utils/test_instructions_utils.py: 3 new regression tests

Testing

All 17 tests in test_instructions_utils.py pass (14 existing + 3 new):

• test_double_braces_escape_to_literal: {{city}} → {city}
• test_double_braces_mixed_with_state_variable: {user_name} resolves while {{placeholder}} escapes
• test_triple_braces_peel_one_layer: {{{example}}} → {{example}}

[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.

[gemini-code-assist]

Summary of Changes

Hello @stakeswky, 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 addresses a critical bug that caused instruction templates to misinterpret double-braced strings as dynamic variables, leading to incorrect rendering. The fix ensures that such patterns are now correctly escaped to their literal form, restoring expected behavior and improving the reliability of instruction generation.

Highlights

• Bug Fix: Resolved a regression where double braces (e.g., {{city}}) in instruction templates were incorrectly treated as session state lookups instead of literal strings, which was causing {city} to be rendered as an empty string if city was not in session state.
• Core Logic Update: Implemented an early return in the _replace_match function within instructions_utils.py to detect and correctly process double-braced patterns by peeling one layer of braces and returning the literal content.
• Test Coverage: Introduced three new regression tests to validate the double-brace escaping mechanism, covering scenarios such as literal escaping, mixed state variable resolution, and triple-brace peeling.

🧠 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
  • Added an early return condition in _replace_match to handle double-brace escape sequences, preventing them from being processed as state variables.
• tests/unittests/utils/test_instructions_utils.py
  • Added test_double_braces_escape_to_literal to verify that {{x}} correctly renders as {x}.
  • Added test_double_braces_mixed_with_state_variable to ensure double braces escape while single braces resolve state.
  • Added test_triple_braces_peel_one_layer to confirm that {{{x}}} correctly peels to {{x}}.

Activity

• The pull request was created by stakeswky to fix issue [Regression v1.25.1] Template variable escaping with double braces broken #4606, addressing a regression in instruction template parsing.

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. ↩

[adk-bot]

Response from ADK Triaging Agent

Hello @stakeswky, thank you for creating this PR!

Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

You can visit https://cla.developers.google.com/ to see your current agreements or to sign a new one.

This information will help reviewers to review your PR more efficiently. Thanks!

[gemini-code-assist]

Code Review

This pull request addresses a regression where double-braced expressions like {{city}} were not being correctly escaped. The fix introduces an early return to handle {{...}} syntax as an escape sequence, correctly converting it to {...}. The change is logical, and the accompanying new tests in test_instructions_utils.py provide good coverage for the fix, including cases with mixed variables and multiple layers of braces.

I have one suggestion regarding a pre-existing issue in the parsing logic that could misinterpret malformed syntax. Addressing this would further improve the robustness of the template rendering.

[gemini-code-assist]

The use of lstrip('{').rstrip('}') can lead to incorrect parsing for malformed brace syntax that isn't a valid escape sequence. For example, an input like '{{var}}}' would not be handled by the if condition for escaped sequences, and this line would incorrectly parse it as the variable 'var'. This is because lstrip and rstrip remove all occurrences of the specified characters from the ends of the string.

This appears to be a pre-existing issue, but it would be good to address it to make parsing more robust. A safer approach for handling single-brace variables would be to use slicing (e.g., raw[1:-1].strip()) after validating that there is exactly one opening and one closing brace.

[stakeswky]

Good catch! Applied in 302c575 — switched to raw[1:-1].strip() slicing for safer single-brace parsing.

[GWeale]

Hi closing out based on comment from issue. We are updating docs

Thank you for raising!