Description
The ADK documentation states that double braces ({{ and }}) should be used to escape literal curly braces in agent instructions, but the implementation in instructions_utils.py does not properly handle this escaping mechanism.
Expected Behavior
According to the State documentation:
If your instruction text legitimately needs to include literal curly braces (e.g., as part of a code example or JSON snippet), you need to escape them... a common approach is doubling the braces: {{ becomes { and }} becomes }.
When using {{variable_name}} in an instruction, it should render as {variable_name} without attempting template substitution.
Actual Behavior
The regex pattern {+[^{}]*}+ in inject_session_state() matches {{variable_name}} and attempts to substitute it from session state, causing a KeyError when the variable doesn't exist.
The issue is in these lines of google/adk/utils/instructions_utils.py:
Line 124: Regex matches {{variable}}
return await _async_sub(r'{+[^{}]*}+', _replace_match, template)
Lines 82-83: Strips all braces, leaving just 'variable'
async def _replace_match(match) -> str:
var_name = match.group().lstrip('{').rstrip('}').strip()
Line 143: 'variable' passes identifier check
return var_name.isidentifier()
Lines 109-122: Tries to inject from state and fails
if var_name in invocation_context.session.state:
...
else:
raise KeyError(f'Context variable not found: {var_name}.')## Steps to Reproduce
- Create an agent with an instruction containing code examples with template literals:
instruction = """
Example Python code:
logger.error(f"User not found: {{user_id}}")
Example TypeScript code:
console.log(User: ${{userId}});
"""2. Run the agent
3. Observe: KeyError: 'Context variable not found: 'user_id'.
Environment
- ADK Version: 1.18.0 (tested with google-adk>=1.18.0)
- Python Version: 3.12
- OS: macOS 24.6.0
Workaround
Use property access (dots) in code examples instead of simple identifiers, since _is_valid_state_name() returns False for non-identifiers:
This works because 'user.id' is not a valid identifier
logger.error(f"User not found: {{user.id}}")## Suggested Fix
The _replace_match function should detect double-brace patterns and return the literal content without attempting substitution:
async def _replace_match(match) -> str:
matched_text = match.group()
# Check if this is an escaped pattern (starts with {{ )
if matched_text.startswith('{{') and matched_text.endswith('}}'):
# Return with single braces (unescape)
return matched_text[1:-1]
# Existing logic for template substitution
var_name = matched_text.lstrip('{').rstrip('}').strip()
...Alternatively, update the regex to exclude double-brace patterns from matching, though this is more complex.
Impact
This bug prevents using realistic code examples (especially Python f-strings and TypeScript/JavaScript template literals) in agent instructions, which is critical for code generation and software engineering agents.
Description
The ADK documentation states that double braces (
{{and}}) should be used to escape literal curly braces in agent instructions, but the implementation ininstructions_utils.pydoes not properly handle this escaping mechanism.Expected Behavior
According to the State documentation:
When using
{{variable_name}}in an instruction, it should render as{variable_name}without attempting template substitution.Actual Behavior
The regex pattern
{+[^{}]*}+ininject_session_state()matches{{variable_name}}and attempts to substitute it from session state, causing aKeyErrorwhen the variable doesn't exist.The issue is in these lines of
google/adk/utils/instructions_utils.py:Line 124: Regex matches {{variable}}
return await _async_sub(r'{+[^{}]*}+', _replace_match, template)
Lines 82-83: Strips all braces, leaving just 'variable'
async def _replace_match(match) -> str:
var_name = match.group().lstrip('{').rstrip('}').strip()
Line 143: 'variable' passes identifier check
return var_name.isidentifier()
Lines 109-122: Tries to inject from state and fails
if var_name in invocation_context.session.state:
...
else:
raise KeyError(f'Context variable not found:
{var_name}.')## Steps to Reproduceinstruction = """
Example Python code:
logger.error(f"User not found: {{user_id}}")
Example TypeScript code:
console.log(
User: ${{userId}});"""2. Run the agent
3. Observe:
KeyError: 'Context variable not found: 'user_id'.Environment
Workaround
Use property access (dots) in code examples instead of simple identifiers, since
_is_valid_state_name()returnsFalsefor non-identifiers:This works because 'user.id' is not a valid identifier
logger.error(f"User not found: {{user.id}}")## Suggested Fix
The
_replace_matchfunction should detect double-brace patterns and return the literal content without attempting substitution:async def _replace_match(match) -> str:
matched_text = match.group()
Impact
This bug prevents using realistic code examples (especially Python f-strings and TypeScript/JavaScript template literals) in agent instructions, which is critical for code generation and software engineering agents.