Instruction Injection

Purpose

The Instruction Injection subtopic addresses the need to dynamically customize large language model (LLM) instruction templates by embedding runtime session state and artifact data. Within the broader domain of specialized LLM agents that manage configurable models, tools, and instructions, this subtopic ensures that instructions sent to the LLM are context-aware and personalized to the current session.

Specifically, it solves the problem of how to automatically replace placeholders in instruction templates with up-to-date session variables or artifact contents. This facilitates dynamic prompt generation where the LLM receives instructions tailored to the user’s session context, improving relevance and coherence in multi-turn conversations.

This mechanism is essential for the LLM Integration and Agents topic (80562) and complements related subtopics like Artifact Management and Session Management by bridging their stored data into the agent’s instruction pipeline.

Functionality

Instruction Injection works by scanning instruction templates for placeholders enclosed in curly braces—for example, {user_name}, {app:current_topic}, or {artifact.report}—and replacing these placeholders with actual values fetched from the session state or artifact storage.

Key workflows and components include:

1. Template Parsing and Placeholder Detection
   A regular expression ({+[^{}]*}+) identifies placeholders in instructions. The processor extracts each placeholder’s key name and determines whether it refers to a session state variable or an artifact.

2. Session State Variable Injection
   Placeholders like {user_name} or prefixed keys such as {app:current_status} are resolved by querying the session’s state store. The injection logic validates the variable name format (e.g., must be a valid identifier or use known prefixes like app:, user:, temp:), then retrieves the corresponding value from the session.

3. Artifact Data Injection
   Placeholders prefixed with artifact., such as {artifact.file_name}, trigger calls to the artifact service to load the textual content of a named artifact file. This content is then embedded directly into the instruction string.

4. Optional Placeholders
   A placeholder variable can be marked optional by suffixing ? (e.g., {optional_key?}). If the optional key is missing from session state or artifacts, the injection returns an empty string instead of raising an error, allowing templates to gracefully handle missing data.

5. Error Handling
   If a required key is missing or the artifact service is unavailable, injection returns an error, preventing the agent from sending incomplete or misleading instructions to the LLM.

6. Integration with Instruction Providers
   The injection logic is invoked by the agent’s instruction provider functions that prepare the final instructions for the LLM request. It is used for both agent-specific instructions and global instructions appended to every request.

Code Interaction Example

From the core injection processor (internal/llminternal/instruction_processor.go), the main method InjectSessionState takes an invocation context and a template string, then returns the processed instruction:

func InjectSessionState(ctx agent.InvocationContext, template string) (string, error) {
    // Finds placeholders and replaces each by calling replaceMatch.
    // ...
}

The replaceMatch function handles each placeholder:

• For {artifact.file}, it calls ctx.Artifacts().Load(...) to fetch artifact text.

• For session keys like {user_name}, it calls ctx.Session().State().Get(key).

The utility function appendInstructions shows how instructions are processed and injected before being appended to an LLM request:

func appendInstructions(ctx agent.InvocationContext, req *model.LLMRequest, agentState *State) error {
    inst, err := InjectSessionState(ctx, agentState.Instruction)
    if err != nil {
        return fmt.Errorf("failed to inject session state into instruction: %w", err)
    }
    utils.AppendInstructions(req, inst)
    return nil
}

This workflow ensures that when an LLM agent sends instructions to the model, all session and artifact-dependent placeholders are resolved dynamically.

Integration

Instruction Injection integrates tightly with the parent topic LLM Integration and Agents (80562) by serving as the mechanism to generate the final textual instructions provided to the LLM. It complements:

• Session Management: Uses session state variables managed and persisted by session services.

• Artifact Management: Loads artifact contents stored by artifact services to embed data into instructions.

• Instruction Template Processing: Shares conceptual goals but Instruction Injection specifically implements runtime placeholder replacement logic.

• Agent Workflow and Runner components: The instruction injection occurs during agent invocation to prepare prompt content before LLM calls.

By injecting real-time context, this subtopic enhances agent responsiveness, enabling personalized and contextually aware LLM prompts that drive improved agent behavior.

sequenceDiagram
participant Agent as LLM Agent
participant Inject as Instruction Injection
participant Session as Session Service
participant Artifact as Artifact Service
participant LLM as LLM Model
Agent->>Inject: Request instruction template processing
Inject->>Agent: Get current InvocationContext
loop For each placeholder in template
Inject->>Session: Query state variable (if placeholder is state)
Session-->>Inject: Return state value
Inject->>Artifact: Load artifact content (if placeholder is artifact)
Artifact-->>Inject: Return artifact text
end
Inject-->>Agent: Return injected instruction string
Agent->>LLM: Send final instruction prompt
LLM-->>Agent: Return response

This sequence shows the dynamic retrieval of session and artifact data for each placeholder, combined into a fully injected instruction before interacting with the LLM.