feat: add an opt-in to leave escaped placeholders in instructions as written

`InstructionUtils.injectSessionState` resolves a placeholder right after `$` or
`\` like any other and keeps the character in front: `Price: ${price}` becomes
`Price: $9.99`, and `${expression}` fails the request when `expression` is not
in the state. adk-python leaves such placeholders as written since 2.10.0
(google/adk-python@0caecd2).

`LlmAgent.Builder.preserveEscapedPlaceholders(boolean)`, also available as
`preserve_escaped_placeholders` in YAML agent configs, lets an agent opt into the
same rule. The agent's flag applies to its instruction and the root agent's flag
to the global instruction; `GlobalInstructionPlugin` takes it as a constructor
argument. The default is unchanged.

Author: Laurianti

core/src/main/java/com/google/adk/agents/Instruction.java

@@ -29,7 +29,10 @@
  * {artifact.artifact_name}}. These are replaced with values from the agent's session state or
  * loaded artifacts, respectively. For example, an instruction like {@code "Translate the following
  * text to {language}: {user_query}"} would substitute {@code {language}} and {@code {user_query}}
- * with their corresponding values from the session state.
+ * with their corresponding values from the session state. A placeholder right after {@code $} or
+ * {@code \}, such as {@code ${language}}, is resolved in the same way unless the agent is built
+ * with {@link LlmAgent.Builder#preserveEscapedPlaceholders(boolean)} set to {@code true}, in which
+ * case it is left as written, backslash included.
  *
  * <p>Instructions can also be dynamically constructed using {@link Instruction.Provider}. This
  * allows for more complex logic where the instruction text is generated based on the current {@link

core/src/main/java/com/google/adk/agents/LlmAgent.java

@@ -101,6 +101,7 @@ public enum IncludeContents {
   private final ImmutableList<BaseToolset> toolsets;
   private final Optional<GenerateContentConfig> generateContentConfig;
   private final IncludeContents includeContents;
+  private final boolean preserveEscapedPlaceholders;
 
   private final boolean planning;
   private final Optional<Integer> maxSteps;
@@ -134,6 +135,8 @@ protected LlmAgent(Builder builder) {
         requireNonNullElse(builder.globalInstruction, new Instruction.Static(""));
     this.generateContentConfig = Optional.ofNullable(builder.generateContentConfig);
     this.includeContents = requireNonNullElse(builder.includeContents, IncludeContents.DEFAULT);
+    this.preserveEscapedPlaceholders =
+        requireNonNullElse(builder.preserveEscapedPlaceholders, false);
     this.planning = requireNonNullElse(builder.planning, false);
     this.maxSteps = Optional.ofNullable(builder.maxSteps);
     this.disallowTransferToParent = requireNonNullElse(builder.disallowTransferToParent, false);
@@ -181,6 +184,7 @@ public static class Builder extends BaseAgent.Builder<Builder> {
     private ImmutableList<Object> toolsUnion;
     private GenerateContentConfig generateContentConfig;
     private IncludeContents includeContents;
+    private Boolean preserveEscapedPlaceholders;
     private Boolean planning;
     private Integer maxSteps;
     private Boolean disallowTransferToParent;
@@ -258,6 +262,20 @@ public Builder includeContents(IncludeContents includeContents) {
       return this;
     }
 
+    /**
+     * Sets whether a placeholder right after {@code $} or {@code \} in the instruction is left as
+     * written, backslash included: {@code ${key}}, {@code ${{key}}} and {@code \{key}} reach the
+     * model unchanged. Defaults to {@code false}, which resolves such a placeholder and keeps the
+     * {@code $} or {@code \} before it, so {@code ${price}} becomes {@code $9.99}. The global
+     * instruction follows the root agent's setting. An {@link Instruction.Provider} is not
+     * templated either way.
+     */
+    @CanIgnoreReturnValue
+    public Builder preserveEscapedPlaceholders(boolean preserveEscapedPlaceholders) {
+      this.preserveEscapedPlaceholders = preserveEscapedPlaceholders;
+      return this;
+    }
+
     @CanIgnoreReturnValue
     public Builder planning(boolean planning) {
       this.planning = planning;
@@ -902,6 +920,14 @@ public IncludeContents includeContents() {
     return includeContents;
   }
 
+  /**
+   * Returns whether a placeholder right after {@code $} or {@code \} in the instruction is left as
+   * written. See {@link Builder#preserveEscapedPlaceholders(boolean)}.
+   */
+  public boolean preserveEscapedPlaceholders() {
+    return preserveEscapedPlaceholders;
+  }
+
   public Single<List<BaseTool>> tools() {
     return canonicalTools().toList();
   }
@@ -1145,6 +1171,11 @@ public static LlmAgent fromConfig(LlmAgentConfig config, String configAbsPath)
       builder.includeContents(config.includeContents());
     }
 
+    // Set optional preserve_escaped_placeholders
+    if (config.preserveEscapedPlaceholders() != null) {
+      builder.preserveEscapedPlaceholders(config.preserveEscapedPlaceholders());
+    }
+
     // Set optional generateContentConfig
     if (config.generateContentConfig() != null) {
       builder.generateContentConfig(config.generateContentConfig());

core/src/main/java/com/google/adk/agents/LlmAgentConfig.java

@@ -34,6 +34,7 @@ public class LlmAgentConfig extends BaseAgentConfig {
   private String outputKey;
   private List<ToolConfig> tools;
   private IncludeContents includeContents;
+  private Boolean preserveEscapedPlaceholders;
   private GenerateContentConfig generateContentConfig;
 
   // Callback configuration (names resolved via ComponentRegistry)
@@ -103,6 +104,14 @@ public void setIncludeContents(IncludeContents includeContents) {
     this.includeContents = includeContents;
   }
 
+  public Boolean preserveEscapedPlaceholders() {
+    return preserveEscapedPlaceholders;
+  }
+
+  public void setPreserveEscapedPlaceholders(Boolean preserveEscapedPlaceholders) {
+    this.preserveEscapedPlaceholders = preserveEscapedPlaceholders;
+  }
+
   public GenerateContentConfig generateContentConfig() {
     return generateContentConfig;
   }

core/src/main/java/com/google/adk/flows/llmflows/Instructions.java

@@ -44,12 +44,19 @@ public Single<RequestProcessor.RequestProcessingResult> processRequest(
     if (agent.rootAgent() instanceof LlmAgent rootAgent) {
       builderSingle =
           appendInstruction(
-              builderSingle, context, rootAgent.canonicalGlobalInstruction(readonlyContext));
+              builderSingle,
+              context,
+              rootAgent.canonicalGlobalInstruction(readonlyContext),
+              rootAgent.preserveEscapedPlaceholders());
     }
 
     // Process agent-specific instruction
     builderSingle =
-        appendInstruction(builderSingle, context, agent.canonicalInstruction(readonlyContext));
+        appendInstruction(
+            builderSingle,
+            context,
+            agent.canonicalInstruction(readonlyContext),
+            agent.preserveEscapedPlaceholders());
 
     return builderSingle.map(
         finalBuilder ->
@@ -60,7 +67,8 @@ public Single<RequestProcessor.RequestProcessingResult> processRequest(
   private Single<LlmRequest.Builder> appendInstruction(
       Single<LlmRequest.Builder> builderSingle,
       InvocationContext context,
-      Single<Map.Entry<String, Boolean>> instructionEntrySingle) {
+      Single<Map.Entry<String, Boolean>> instructionEntrySingle,
+      boolean preserveEscapedPlaceholders) {
     return builderSingle.flatMap(
         builder ->
             instructionEntrySingle.flatMap(
@@ -73,7 +81,8 @@ private Single<LlmRequest.Builder> appendInstruction(
                   if (bypassStateInjection) {
                     return Single.just(builder.appendInstructions(ImmutableList.of(instruction)));
                   }
-                  return InstructionUtils.injectSessionState(context, instruction)
+                  return InstructionUtils.injectSessionState(
+                          context, instruction, preserveEscapedPlaceholders)
                       .map(
                           resolvedInstr ->
                               builder.appendInstructions(ImmutableList.of(resolvedInstr)));

core/src/main/java/com/google/adk/plugins/GlobalInstructionPlugin.java

@@ -39,19 +39,23 @@
  * <p>The plugin operates through the before_model_callback, allowing it to modify LLM requests
  * before they are sent to the model by prepending the global instruction to any existing system
  * instructions provided by the agent.
+ *
+ * <p>A string global instruction is templated like an agent instruction. A placeholder right after
+ * {@code $} or {@code \} is resolved unless the plugin is created with {@code
+ * preserveEscapedPlaceholders} set to {@code true}, whatever the setting of the current agent.
  */
 public class GlobalInstructionPlugin extends BasePlugin {
 
   private final Function<CallbackContext, Maybe<String>> instructionProvider;
 
   private static Function<CallbackContext, Maybe<String>> createInstructionProvider(
-      String globalInstruction) {
+      String globalInstruction, boolean preserveEscapedPlaceholders) {
     return callbackContext -> {
       if (globalInstruction == null) {
         return Maybe.empty();
       }
       return InstructionUtils.injectSessionState(
-              callbackContext.invocationContext(), globalInstruction)
+              callbackContext.invocationContext(), globalInstruction, preserveEscapedPlaceholders)
           .toMaybe();
     };
   }
@@ -61,7 +65,21 @@ public GlobalInstructionPlugin(String globalInstruction) {
   }
 
   public GlobalInstructionPlugin(String globalInstruction, String name) {
-    this(createInstructionProvider(globalInstruction), name);
+    this(globalInstruction, name, false);
+  }
+
+  /**
+   * Creates a plugin with a string global instruction.
+   *
+   * @param globalInstruction The global instruction, templated with values from the session state
+   *     or artifacts.
+   * @param name The name of the plugin.
+   * @param preserveEscapedPlaceholders Whether a placeholder right after {@code $} or {@code \} in
+   *     the global instruction is left as written, backslash included, instead of being resolved.
+   */
+  public GlobalInstructionPlugin(
+      String globalInstruction, String name, boolean preserveEscapedPlaceholders) {
+    this(createInstructionProvider(globalInstruction, preserveEscapedPlaceholders), name);
   }
 
   public GlobalInstructionPlugin(Function<CallbackContext, Maybe<String>> instructionProvider) {

core/src/main/java/com/google/adk/utils/InstructionUtils.java

@@ -17,6 +17,7 @@
 package com.google.adk.utils;
 
 import com.google.adk.agents.InvocationContext;
+import com.google.adk.agents.LlmAgent;
 import com.google.adk.sessions.Session;
 import com.google.adk.sessions.State;
 import com.google.common.collect.ImmutableSet;
@@ -35,6 +36,11 @@ public final class InstructionUtils {
   private static final Pattern INSTRUCTION_PLACEHOLDER_PATTERN =
       Pattern.compile("\\{+[^\\{\\}]*\\}+");
 
+  // Also skips braces preceded by '$', '{' or '\', so ${key}, ${{key}} and \{key} are left as
+  // written. The '{' keeps the inner braces of ${{key}} and \{{key}} from matching on their own.
+  private static final Pattern ESCAPE_PRESERVING_PLACEHOLDER_PATTERN =
+      Pattern.compile("(?<![\\$\\{\\\\])\\{+[^\\{\\}]*\\}+");
+
   private InstructionUtils() {}
 
   /**
@@ -74,9 +80,20 @@ private InstructionUtils() {}
    *         <li>If an optional placeholder cannot be resolved (e.g., variable not found, artifact
    *             not found), it is replaced with an empty string.
    *       </ul>
+   *   <li><b>Escaped Placeholders:</b> A placeholder right after {@code $} or {@code \}, such as
+   *       {@code ${key}}, {@code ${{key}}} or {@code \{key}}.
+   *       <ul>
+   *         <li>When {@code preserveEscapedPlaceholders} is {@code true}, it is left as written,
+   *             backslash included.
+   *         <li>When it is {@code false}, it is resolved like any other placeholder and the {@code
+   *             $} or {@code \} before it is kept, so {@code ${key}} with {@code key} set to {@code
+   *             9.99} becomes {@code $9.99}.
+   *         <li>This method uses the {@link LlmAgent#preserveEscapedPlaceholders()} setting of the
+   *             context's agent when it is an {@link LlmAgent}, and {@code false} otherwise.
+   *       </ul>
    * </ul>
    *
-   * <b>Example Usage:</b>
+   * <p><b>Example Usage:</b>
    *
    * <pre>{@code
    * InvocationContext context = ...; // Assume this is initialized with session and artifact service
@@ -107,13 +124,36 @@ private InstructionUtils() {}
    * @throws IllegalArgumentException if a non-optional variable or artifact is not found.
    */
   public static Single<String> injectSessionState(InvocationContext context, String template) {
+    return injectSessionState(context, template, preservesEscapedPlaceholders(context));
+  }
+
+  /**
+   * Populates placeholders in an instruction template string with values from the session state or
+   * loaded artifacts, as {@link #injectSessionState(InvocationContext, String)} does, with the
+   * handling of escaped placeholders given explicitly instead of taken from the context's agent.
+   *
+   * @param context The invocation context providing access to session state and artifact services.
+   * @param template The instruction template string containing placeholders to be populated.
+   * @param preserveEscapedPlaceholders Whether a placeholder right after {@code $} or {@code \} is
+   *     left as written, backslash included, instead of being resolved.
+   * @return A {@link Single} that will emit the populated instruction string upon successful
+   *     resolution of all non-optional placeholders.
+   * @throws NullPointerException if the template or context is null.
+   * @throws IllegalArgumentException if a non-optional variable or artifact is not found.
+   */
+  public static Single<String> injectSessionState(
+      InvocationContext context, String template, boolean preserveEscapedPlaceholders) {
     if (template == null) {
       return Single.error(new NullPointerException("template cannot be null"));
     }
     if (context == null) {
       return Single.error(new NullPointerException("context cannot be null"));
     }
-    Matcher matcher = INSTRUCTION_PLACEHOLDER_PATTERN.matcher(template);
+    Pattern placeholderPattern =
+        preserveEscapedPlaceholders
+            ? ESCAPE_PRESERVING_PLACEHOLDER_PATTERN
+            : INSTRUCTION_PLACEHOLDER_PATTERN;
+    Matcher matcher = placeholderPattern.matcher(template);
     List<Single<String>> parts = new ArrayList<>();
     int lastEnd = 0;
 
@@ -144,6 +184,12 @@ public static Single<String> injectSessionState(InvocationContext context, Strin
         });
   }
 
+  private static boolean preservesEscapedPlaceholders(InvocationContext context) {
+    return context != null
+        && context.agent() instanceof LlmAgent llmAgent
+        && llmAgent.preserveEscapedPlaceholders();
+  }
+
   private static Single<String> resolveMatchAsync(InvocationContext context, MatchResult match) {
     String placeholder = match.group();
     String varNameFromPlaceholder =

core/src/test/java/com/google/adk/agents/ConfigAgentUtilsTest.java

@@ -1561,4 +1561,39 @@ public void fromConfig_validYamlLoopAgent_createsLoopAgent()
     assertThat(agent).isNotNull();
     assertThat(agent).isInstanceOf(LoopAgent.class);
   }
+
+  @Test
+  public void fromConfig_withPreserveEscapedPlaceholders_setsFlagOnAgent()
+      throws IOException, ConfigurationException {
+    File configFile = tempFolder.newFile("preserve_escaped_placeholders.yaml");
+    Files.writeString(
+        configFile.toPath(),
+        """
+        name: preserving_agent
+        instruction: "Show ${expression} as written."
+        preserve_escaped_placeholders: true
+        """);
+
+    BaseAgent agent = ConfigAgentUtils.fromConfig(configFile.getAbsolutePath());
+
+    assertThat(agent).isInstanceOf(LlmAgent.class);
+    assertThat(((LlmAgent) agent).preserveEscapedPlaceholders()).isTrue();
+  }
+
+  @Test
+  public void fromConfig_withoutPreserveEscapedPlaceholders_defaultsToFalse()
+      throws IOException, ConfigurationException {
+    File configFile = tempFolder.newFile("default_escaped_placeholders.yaml");
+    Files.writeString(
+        configFile.toPath(),
+        """
+        name: default_agent
+        instruction: Resolve {placeholders}.
+        """);
+
+    BaseAgent agent = ConfigAgentUtils.fromConfig(configFile.getAbsolutePath());
+
+    assertThat(agent).isInstanceOf(LlmAgent.class);
+    assertThat(((LlmAgent) agent).preserveEscapedPlaceholders()).isFalse();
+  }
 }

core/src/test/java/com/google/adk/agents/LlmAgentTest.java

@@ -935,4 +935,53 @@ public void runAsync_resumeFromTransferToPeer_runsTransferredPeerAgent() {
     assertThat(simplifyEvents(events)).contains("agent_b: agent B response");
     assertThat(simplifyEvents(events)).doesNotContain("agent_a: agent A should not re-run");
   }
+
+  @Test
+  public void testBuild_withoutPreserveEscapedPlaceholders_defaultsToFalse() {
+    LlmAgent agent = createTestAgentBuilder(createTestLlm(LlmResponse.builder().build())).build();
+
+    assertThat(agent.preserveEscapedPlaceholders()).isFalse();
+  }
+
+  @Test
+  public void testBuild_withPreserveEscapedPlaceholders_setsFlag() {
+    LlmAgent agent =
+        createTestAgentBuilder(createTestLlm(LlmResponse.builder().build()))
+            .preserveEscapedPlaceholders(true)
+            .build();
+
+    assertThat(agent.preserveEscapedPlaceholders()).isTrue();
+  }
+
+  @Test
+  public void run_withPreserveEscapedPlaceholders_sendsEscapedPlaceholdersToModel() {
+    TestLlm testLlm = createTestLlm(createTextLlmResponse("response"));
+    LlmAgent agent =
+        createTestAgentBuilder(testLlm)
+            .instruction("{name} shows ${price}.")
+            .preserveEscapedPlaceholders(true)
+            .build();
+    InvocationContext invocationContext = createInvocationContext(agent);
+    invocationContext.session().state().put("name", "TestBot");
+    invocationContext.session().state().put("price", 9.99);
+
+    List<Event> unused = agent.runAsync(invocationContext).toList().blockingGet();
+
+    assertThat(getOnlyElement(testLlm.getLastRequest().getSystemInstructions()))
+        .startsWith("TestBot shows ${price}.\n\n");
+  }
+
+  @Test
+  public void run_withoutPreserveEscapedPlaceholders_sendsResolvedPlaceholdersToModel() {
+    TestLlm testLlm = createTestLlm(createTextLlmResponse("response"));
+    LlmAgent agent = createTestAgentBuilder(testLlm).instruction("{name} shows ${price}.").build();
+    InvocationContext invocationContext = createInvocationContext(agent);
+    invocationContext.session().state().put("name", "TestBot");
+    invocationContext.session().state().put("price", 9.99);
+
+    List<Event> unused = agent.runAsync(invocationContext).toList().blockingGet();
+
+    assertThat(getOnlyElement(testLlm.getLastRequest().getSystemInstructions()))
+        .startsWith("TestBot shows $9.99.\n\n");
+  }
 }