Session State Injection

Purpose

Within the broader scope of Instruction Template Processing, Session State Injection addresses the need to dynamically replace placeholders embedded in LLM instruction templates with actual runtime values drawn from the current session state or artifact contents. This capability enables agents to produce contextually enriched prompts by incorporating relevant user data, temporary computational results, or external artifact content directly into instructions before they are sent to the LLM model.

The problem it solves is the mismatch between static instruction templates and the dynamic, evolving context of an agent's session. By injecting session-specific values at runtime, agents can adapt their behavior based on prior interactions, stored state variables, or loaded artifacts, enhancing the relevance and accuracy of generated LLM prompts.

Functionality

Session State Injection operates primarily by parsing instruction templates for placeholders enclosed in curly braces (e.g., {variable}, {artifact.file_name}) and replacing them with corresponding runtime values:

• Placeholder Identification:
  The system scans the instruction string for placeholders using regex ({+[^{}]*}+). These tokens represent variable names or artifact references.

• Variable Name Parsing and Validation:
  Each placeholder is extracted and trimmed of braces to obtain the variable name. Variable names may be optionally marked with a trailing ? to indicate that missing values should be ignored gracefully. The variable names are validated to ensure they conform to acceptable identifier patterns or include recognized prefixes (app:, user:, temp:).

• Session State Lookup:
  For placeholders representing session state variables (e.g., {user:name}), the system queries the session state store via ctx.Session().State().Get(varName) to fetch the current value. If the variable does not exist and is not marked optional, an error is raised.

• Artifact Content Injection:
  For placeholders of the form {artifact.file_name}, the system accesses the artifact service through ctx.Artifacts().Load(ctx, fileName) to retrieve the artifact's textual content and inject it into the instruction.

• Error Handling:
  Optional placeholders (with ?) suppress errors if the state key or artifact is missing, injecting an empty string instead. Otherwise, failures propagate as errors halting instruction processing.

• String Reconstruction:
  The instruction template is reconstructed by replacing each placeholder with its resolved value, preserving surrounding text intact.

This process is encapsulated in the core function InjectSessionState (in internal/llminternal/instruction_processor.go), which takes an invocation context and a template string, returning the fully expanded instruction.

Key Code Snippet

func InjectSessionState(ctx agent.InvocationContext, template string) (string, error) {
    // For each placeholder match in the template:
    //   - Extract variable name
    //   - If artifact reference, load artifact content
    //   - Else fetch session state value
    //   - Replace placeholder with resolved value
    // Return the fully expanded string or error if any required value missing
}

The function replaceMatch handles individual placeholder resolution, distinguishing between artifact and session state references and enforcing validation rules.

Integration

Session State Injection integrates tightly with the parent topic, Instruction Template Processing, by serving as the mechanism that concretely fulfills the dynamic injection requirement. When an agent prepares its instructions for an LLM request, the parent topic calls into this subtopic to resolve placeholders before sending the instructions to the model.

It also depends on the Session Management ([80559]) and Artifact Management ([80557]) services:

• The session state store provides persistent or ephemeral key-value pairs representing user, app, or temporary data.

• The artifact service manages storage and retrieval of files or blobs whose contents may be relevant for prompt construction.

By leveraging these services' interfaces, Session State Injection ensures that instruction templates reflect the current session's data and available artifacts.

Furthermore, this subtopic complements related subtopics that provide instruction templates or global instruction providers. The injection is typically invoked during the agent's instruction assembly phase (e.g., in appendInstructions and appendGlobalInstructions), enabling both global and agent-specific instructions to embed dynamic state.

Diagram

sequenceDiagram
participant Agent as Agent
participant Inject as SessionStateInjection
participant Session as SessionService
participant Artifact as ArtifactService
Agent->>Inject: Provide instruction template with placeholders
loop For each placeholder
Inject->>Inject: Parse placeholder
alt placeholder is artifact
Inject->>Artifact: Load artifact content
Artifact-->>Inject: Return artifact text
else placeholder is session state variable
Inject->>Session: Get state variable value
Session-->>Inject: Return state value or error
end
Inject->>Inject: Replace placeholder with value
end
Inject-->>Agent: Return fully injected instruction string

This sequence illustrates the iterative process of scanning each placeholder in an instruction template, retrieving corresponding data from session state or artifact storage, and producing the final instruction string ready for the LLM prompt.

This subtopic is essential for making instruction templates adaptive and context-aware, enabling sophisticated prompt engineering that reflects both user interaction state and external information artifacts.