Class InstructionUtils

java.lang.Object
com.google.adk.utils.InstructionUtils
public final class InstructionUtils extends Object
Utility methods for handling instruction templates.

  • Method Details

    • injectSessionState

      public static io.reactivex.rxjava3.core.Single<String> injectSessionState(InvocationContext context, String template)
      Populates placeholders in an instruction template string with values from the session state or loaded artifacts.

      Placeholder Syntax:

      Placeholders are enclosed by one or more curly braces at the start and end, e.g., {key} or {{key}}. The core key is extracted from whatever is between the innermost pair of braces after trimming whitespace and possibly removing the ? which denotes optionality (e.g. {key?}). The key itself must not contain curly braces. For typical usage, a single pair of braces like {my_variable} is standard.

      The extracted key determines the source and name of the value:

      • Session State Variables: The key (e.g., "variable_name" or "prefix:variable_name") refers to a variable in session state.
        • Simple name: {variable_name}. The variable_name part must be a valid identifier as per isValidStateName(String). Invalid names will result in the placeholder being returned as is.
        • Prefixed name: {prefix:variable_name}. Valid prefixes are: "app:", "user:", and "temp:" The part of the name following the prefix must also be a valid identifier. Invalid prefixes will result in the placeholder being returned as is.
      • Artifacts: The key starts with "artifact." (e.g., "artifact.file_name").
      • Optional Placeholders: A key can be marked as optional by appending a question mark ? at its very end, inside the braces.
        • Example: {optional_variable?}, {{artifact.optional_file.txt?}}
        • If an optional placeholder cannot be resolved (e.g., variable not found, artifact not found), it is replaced with an empty string.
      Example Usage: 
      
 InvocationContext context = ...; // Assume this is initialized with session and artifact service
 Session session = context.session();

 session.state().put("user:name", "Alice");

 context.artifactService().saveArtifact(
     session.appName(), session.userId(), session.id(), "knowledge.txt", Part.fromText("Origins of the universe: At first, there was-"));

 String template = "You are {user:name}'s assistant. Answer questions based on your knowledge. Your knowledge: {artifact.knowledge.txt}." +
                   " Your extra knowledge: {artifact.missing_artifact.txt?}";

 Single<String> populatedStringSingle = InstructionUtils.injectSessionState(context, template);
 populatedStringSingle.subscribe(
     result -> System.out.println(result),
     // Expected: "You are Alice's assistant. Answer questions based on your knowledge. Your knowledge: Origins of the universe: At first, there was-. Your extra knowledge: "
     error -> System.err.println("Error populating template: " + error.getMessage())
 );
      Parameters:
      context - The invocation context providing access to session state and artifact services.
      template - The instruction template string containing placeholders to be populated.
      Returns:
      A Single that will emit the populated instruction string upon successful resolution of all non-optional placeholders. Emits the original template if it is empty or contains no placeholders that are processed.
      Throws:
      NullPointerException - if the template or context is null.
      IllegalArgumentException - if a non-optional variable or artifact is not found.