Skip to content

Chapter 8: The Handlebars Template Engine for Prompts

Theoretical Foundations

The fundamental challenge in building sophisticated AI agents is not the model's intelligence, but the precision of the instruction delivery. As explored in Book 7: The Architecture of Large Language Model Interactions, the transition from monolithic, static prompts to dynamic, context-aware systems is the hallmark of professional AI engineering. While simple string interpolation works for trivial cases, it collapses under the weight of complex business logic, variable data structures, and conditional reasoning required by modern agentic patterns. This is where the Handlebars templating engine becomes the backbone of prompt engineering within the Microsoft Semantic Kernel.

The Cognitive Load of Prompt Assembly

To understand the necessity of a templating engine like Handlebars, one must first visualize the architecture of a "Raw Prompt" versus a "Templated Prompt."

In a raw approach, an AI engineer is forced to perform string concatenation manually. This creates a high cognitive load and introduces fragility. Consider a scenario where an AI agent acts as a financial advisor. The prompt must change drastically depending on whether the user is a risk-averse retiree or an aggressive day trader. Without a template engine, the C# code would look like a tangled web of if-else blocks appending strings:

string prompt = "You are a financial advisor.";
if (userProfile == "Retiree") {
    prompt += " Focus on safety and capital preservation. ";
    if (hasDependents) prompt += "Ensure funds last for dependents. ";
} else {
    prompt += " Focus on high-growth potential. ";
}
prompt += "User query: " + query;

This is architectural debt. It mixes logic (the if-else blocks) with presentation (the actual text). It is untestable, unscalable, and impossible for a non-developer to review.

The Analogy: The Master Recipe Book

The "Raw String" Approach: You scream instructions across the kitchen for every single order. "Hey, for table 4, use chicken, but if they are allergic to nuts, use tofu, and if it's Tuesday, add the spicy sauce!" This is chaotic. If the kitchen gets busy, you will make mistakes. The cooks get confused by the long, run-on sentences. 2. The "Handlebars" Approach: You have a standardized "Recipe Card" system. You fill out a card based on the order ticket. The card has placeholders: * {{Protein}} * {{Sauce}} * {{SideDish}}

You don't write the full instruction every time. You just fill in the variables. Furthermore, the card has built-in logic: `{{#if isSpicy}} Add Jalapeños {{/if}}`.

Handlebars is that recipe card system. It separates the structure of the prompt (the template) from the data (the variables). It allows the AI engineer to design the "recipe" once and simply inject ingredients (data) to generate the final instruction.

The Mechanics of Handlebars in C

Handlebars is a logic-less templating engine, but "logic-less" is a misnomer; it means it lacks traditional imperative programming flow (like for loops or switch statements). Instead, it uses expressions and helpers to control the flow of data rendering.

In the context of the Semantic Kernel, we utilize the Handlebars.Net library. When we define a prompt template using Handlebars, we are essentially creating a function that takes a JSON object (the context) and returns a string (the fully formed prompt).

1. Variable Substitution (The {{ }})

Why this matters for AI: It ensures that the AI receives specific, accurate data. If we are building a "Code Review Agent," we cannot simply say "Review this code." We must say "Review this C# code: {{CodeSnippet}} which was written by {{Author}} and relates to {{ModuleName}}."

2. Contextual Awareness

The Semantic Kernel passes a KernelArguments object (essentially a dictionary of key-value pairs) to the template engine. Handlebars traverses this object graph.

If your data structure is nested: 

{
  "user": {
    "profile": {
      "tier": "Gold",
      "name": "Alice"
    }
  }
}
The template Hello {{user.profile.name}}, your tier is {{user.profile.tier}} resolves this automatically. This allows for deeply complex context injection without manual flattening of data.

3. Iteration (The {{#each}} Helper)

This is where the engine transforms from a simple formatter to a dynamic generator. In AI applications, we often need to provide the LLM with a list of examples or context.

Imagine we are building a Sentiment Analysis Agent. We want to provide "Few-Shot" examples to the model (referencing the concept of Few-Shot Learning from Book 3). We have a list of previous inputs and outputs.

Without a loop, we would have to manually concatenate strings: "Example 1: Input: 'Bad service', Output: Negative. Example 2: Input: 'Great food', Output: Positive."

With {{#each}}, the template becomes: 

Analyze the sentiment of the following user feedback.
Here are some examples:
Input: "{{this.text}}", Sentiment: {{this.label}}
{{/each}}

Now analyze this new input: "{{newInput}}"

The {{#each}} block iterates over the examples array. It is robust; if the array is empty, the block simply renders nothing, preventing syntax errors in the final prompt.

4. Conditional Logic (The {{#if}} / {{#unless}} Helpers)

This is the engine of Context-Awareness. AI agents often operate in modes. A "Customer Service Agent" might have access to a user's purchase history, but only if the user is logged in.

Using Handlebars, we can dynamically alter the system's persona and instructions:

You are a helpful assistant.
{{#if user.isAuthenticated}}
  You have access to the user's order history.
  Current Order Count: {{user.orderCount}}
  {{#if user.orderCount > 5}}
    The user is a VIP. Be extra polite and offer expedited shipping.
  {{/if}}
{{else}}
  The user is anonymous. Do not ask for personal data.
{{/if}}

This is the "Master Recipe Book" in action. The structure of the prompt remains constant, but the content morphs based on the user object. This reduces the token count (saving money) and reduces confusion (improving accuracy) by hiding irrelevant instructions.

Architectural Implications: The Template Store

One of the core tenets of the "Core of AI Engineering" is Separation of Concerns. In a robust system, the C# code should not contain the prompt text. The prompt text is a "content asset," not "code."

Using Handlebars allows us to store templates as physical files (.hbs files) in our file system or a database. The C# code simply loads the file and executes it.

// Conceptual Flow
string templateContent = File.ReadAllText("Prompts/CodeReviewer.hbs");
var prompt = Handlebars.Compile(templateContent)(data);

Versioning: You can git-diff a .hbs file much easier than a string inside a C# file. 2. A/B Testing: You can load Template_A or Template_B dynamically to test which prompt yields better results from the LLM. 3. Localization: You can have Prompt_en.hbs and Prompt_fr.hbs, swapping them out based on the user's locale without changing a single line of application logic.

Integration with Agentic Patterns

In the context of Agentic Patterns (Book 8), Handlebars acts as the "Plan" component of the ReAct (Reason + Act) loop.

The Problem: The LLM returns raw data (JSON). The agent needs to summarize this for the user. The summary style depends on the user's request. "Give me the temp" vs. "Write a poem about the weather." * The Solution: The agent selects a Handlebars template based on the user's intent. It feeds the raw JSON into the template. The template applies the requested style (poetic, concise, technical) and generates the final output.

Visualizing the Data Flow

To visualize how the Handlebars engine acts as the bridge between your C# application logic and the LLM's requirements:

A diagram illustrates how raw JSON data flows from a C# application into a Handlebars template engine, which applies a specific style (such as poetic, concise, or technical) before passing the formatted prompt to a Large Language Model (LLM) for final output generation.
Hold "Ctrl" to enable pan & zoom

A diagram illustrates how raw JSON data flows from a C# application into a Handlebars template engine, which applies a specific style (such as poetic, concise, or technical) before passing the formatted prompt to a Large Language Model (LLM) for final output generation.

Theoretical Foundations

It enforces consistency: Every prompt generated follows the defined structure. 2. It manages complexity: It allows developers to handle complex, nested data structures and conditional logic without polluting the application code. 3. It enables modularity: By treating prompts as templates, we can reuse, version, and swap instructions easily.

Without this tool, building an agent that can handle multiple users, multiple tasks, and dynamic context would result in unmaintainable "spaghetti code," rendering the agent brittle and impossible to iterate upon. Handlebars provides the robust scaffolding required to turn a simple LLM call into a production-grade AI system.

Basic Code Example

Here is a simple, 'Hello World' level code example demonstrating the Handlebars template engine within the Microsoft Semantic Kernel.

Real-World Context

Imagine you are building a customer support chatbot for an e-commerce platform. When a user asks about their order status, you cannot simply ask the AI to "check the order." You must provide structured data (order ID, current status, shipping carrier) and a specific format for the response. Hard-coding strings is messy and unscalable. Handlebars templates allow you to separate the logic of the prompt (the structure) from the data (the specific order details), enabling you to reuse the same prompt template for thousands of different orders.

Code Example

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using System.ComponentModel;
using System.Text.Json;
using System.Threading.Tasks;
using System.Console;

// 1. Define a simple plugin to simulate fetching real-time data.
public class OrderStatusPlugin
{
    [KernelFunction("get_order_details")]
    [Description("Retrieves the current status and details of a specific order.")]
    public string GetOrderDetails(
        [Description("The unique identifier for the order")] string orderId)
    {
        // In a real app, this would query a database or API.
        // Here we return a JSON string to simulate the data structure.
        var mockData = new
        {
            OrderId = orderId,
            Status = "Shipped",
            Carrier = "FedEx",
            TrackingNumber = "1234567890XYZ",
            EstimatedDelivery = "2023-10-25"
        };

        return JsonSerializer.Serialize(mockData);
    }
}

class Program
{
    static async Task Main(string[] args)
    {
        // 2. Initialize the Kernel. 
        // Note: For this example to run without an API key, we use a null client 
        // and focus purely on the template rendering logic. 
        // In a real scenario, you would configure AzureOpenAI or OpenAI here.
        var builder = Kernel.CreateBuilder();

        // 3. Register the OrderStatusPlugin so the template can access the data.
        builder.Plugins.AddFromType<OrderStatusPlugin>();

        var kernel = builder.Build();

        // 4. Define the Handlebars template.
        // {{...}} denotes variables.
        // {{#with ...}} creates a context block for the object properties.
        // {{#each ...}} iterates over a collection (not used in this basic example).
        string handlebarsTemplate = """
            You are a helpful customer support assistant. 
            Here is the status for order {{orderId}}:

            Order ID: {{orderDetails.OrderId}}
            Status: {{orderDetails.Status}}
            Carrier: {{orderDetails.Carrier}}
            Tracking #: {{orderDetails.TrackingNumber}}
            Estimated Delivery: {{orderDetails.EstimatedDelivery}}

            Please assist the customer based on this information.
            """;

        // 5. Create the prompt template config.
        // We explicitly tell the Kernel to use Handlebars as the template engine.
        var promptConfig = new PromptTemplateConfig(handlebarsTemplate)
        {
            TemplateFormat = "handlebars"
        };

        // 6. Create the function from the template.
        var promptFunction = kernel.CreateFunctionFromPrompt(promptConfig);

        // 7. Prepare the input data for the template.
        // We fetch the raw JSON string from our plugin first.
        var plugin = new OrderStatusPlugin();
        string rawJson = plugin.GetOrderDetails("ORD-7782");

        // Parse it to an object so Handlebars can access properties via dot notation.
        var orderData = JsonSerializer.Deserialize<JsonElement>(rawJson);

        // 8. Invoke the function with the variables required by the template.
        // The 'orderId' and 'orderDetails' keys match the {{variables}} in the template.
        var result = await kernel.InvokeAsync(promptFunction, new KernelArguments
        {
            ["orderId"] = "ORD-7782",
            ["orderDetails"] = orderData
        });

        // 9. Output the rendered prompt.
        // This string is what would actually be sent to the LLM.
        WriteLine("--- Rendered Prompt ---");
        WriteLine(result.ToString());
    }
}

Using Directives: We import Microsoft.SemanticKernel for the core framework and System.ComponentModel to add metadata to our functions, which helps the AI understand what data to expect. 2. OrderStatusPlugin Class: This acts as our data provider. In Semantic Kernel, plugins are collections of functions that the AI can call or use as data sources. We define a method GetOrderDetails decorated with [KernelFunction]. This attribute marks the method as callable by the kernel. 3. Mock Data Generation: Inside GetOrderDetails, we simulate a database response using an anonymous object and serialize it to JSON. This mimics a real-world scenario where an API returns structured data that needs to be injected into a prompt. 4. Kernel Initialization: Kernel.CreateBuilder() sets up the dependency injection container. We add our OrderStatusPlugin to the kernel's plugin collection. This makes the plugin's data accessible to our prompt templates. 5. Handlebars Template Definition: We use a C# raw string literal ("""...""") to define the prompt. * {{orderId}}: This is a placeholder for a scalar value passed directly to the function. * {{orderDetails.OrderId}}: This accesses a property of a complex object. Handlebars allows dot notation traversal of objects. * Why Handlebars?: Unlike simple string interpolation, Handlebars allows for loops ({{#each}}), conditionals ({{#if}}), and helpers (custom logic), which are essential for dynamic prompt generation. 6. PromptTemplateConfig: This configuration object tells the Semantic Kernel how to interpret the string. By setting TemplateFormat = "handlebars", we instruct the kernel to use the Handlebars engine rather than the default Liquid or basic string formatting. 7. CreateFunctionFromPrompt: This converts the template string into an executable KernelFunction. This function can now be invoked like any other native C# method attached to the kernel. 8. Data Preparation: We fetch the JSON data. Crucially, we deserialize it into a JsonElement. While you can pass anonymous objects, JsonElement is often safer when dealing with dynamic data sources to preserve the structure without defining specific C# DTO classes. 9. KernelArguments: This is a dictionary-like object where keys match the variable names in the template (orderId, orderDetails). The values are the actual data. 10. InvokeAsync: This triggers the rendering process. The Handlebars engine takes the template string and the arguments, merges them, and produces the final text. 11. Output: The result is the fully rendered string, ready to be sent to an LLM (like GPT-4) for processing.

Visualizing the Data Flow

The diagram illustrates the final stage of a data pipeline where a fully rendered string is generated and prepared for submission to a Large Language Model (LLM) such as GPT-4.
Hold "Ctrl" to enable pan & zoom

The diagram illustrates the final stage of a data pipeline where a fully rendered string is generated and prepared for submission to a Large Language Model (LLM) such as GPT-4.

Mismatched Template Format: * Mistake: Forgetting to set TemplateFormat = "handlebars" in the PromptTemplateConfig. * Result: The kernel defaults to the standard template format (often Liquid or simple string substitution). If your template uses {{#if}} or {{#each}} Handlebars syntax, the kernel will throw a parsing exception or render the raw tags as text. * Fix: Always explicitly define the TemplateFormat.

  1. Null Reference in Object Paths:

    • Mistake: Passing a null object or a property that doesn't exist when using dot notation (e.g., {{orderDetails.TrackingNumber}} where orderDetails is null).
    • Result: Handlebars typically renders an empty string for null values, but if you try to access a property on a null object during a helper execution, it may throw a runtime exception.
    • Fix: Use Handlebars conditionals: {{#if orderDetails}}...{{/if}} to guard against nulls.

  2. Data Type Confusion:

    • Mistake: Passing a JSON string directly as a value instead of deserializing it.
    • Result: If you pass the raw JSON string "{'Id': '1'}" as orderDetails, Handlebars will treat it as a string literal. Accessing {{orderDetails.Id}} will fail because orderDetails is a string, not an object.
    • Fix: Ensure complex data is deserialized to a dictionary or object structure before passing it to KernelArguments.

  3. Escaping Braces:

    • Mistake: Trying to include literal {{ or }} in the output text without escaping.
    • Result: Handlebars attempts to interpret them as tags, leading to rendering errors.
    • Fix: Use the "triple-stache" {{{variable}}} if you want to output raw HTML/JSON without escaping, or use the specific Handlebars escaping mechanism if you want to render the literal characters {{.

The chapter continues with advanced code, exercises and solutions with analysis, you can find them on the ebook on Leanpub.com or Amazon

Loading knowledge check...

Code License: All code examples are released under the MIT License. Github repo.

Content Copyright: Copyright © 2026 Edgar Milvus | Privacy & Cookie Policy. All rights reserved.

All textual explanations, original diagrams, and illustrations are the intellectual property of the author. To support the maintenance of this site via AdSense, please read this content exclusively online. Copying, redistribution, or reproduction is strictly prohibited.