Prompt Template in Go

The Problem

Agent prompt strings concatenated inline — "You are a " + role + " assistant. The user asked: " + query — are impossible to review, test independently, or version. A one-character change to a prompt buried in a 500-line agent file can silently break behavior. As prompts grow to hundreds of tokens with multiple sections, inline construction becomes unmanageable.

The Solution

Store each prompt section as a named PromptTemplate with a version string and a text/template body. A Registry compiles templates at registration time — syntax errors surface immediately rather than at runtime. Registry.Render(name, vars) performs substitution with missingkey=error, so a forgotten variable is a compile-time-equivalent panic, not a silent blank. A PromptBuilder assembles multi-section prompts by rendering and concatenating named templates in order.

Structure

Prompt Template Pattern

Step 1 of 3

Registration and Validation

Templates are registered at package init or server startup via MustRegister(). text/template.Parse() runs immediately — a malformed template panics early rather than failing during a live LLM call.

flowchart TD
Registry["Registry
MustRegister() / Render()"]
System["system template
v1.0.0"]
UserTurn["user_turn template
v1.0.0"]
ToolResult["tool_result template
v1.0.0"]
Builder["PromptBuilder
Build()"]
Final["Final Prompt String"]
LLM["LLM"]

System -.->|"registered"| Registry
UserTurn -.->|"registered"| Registry
ToolResult -.->|"registered"| Registry
Builder -->|"Render(system, vars)"| Registry
Builder -->|"Render(user_turn, vars)"| Registry
Builder -->|"Render(tool_result, vars)"| Registry
Registry --> Final
Final --> LLM

Implementation

package main

// PromptTemplate holds a named, versioned text/template for prompt construction.
type PromptTemplate struct {
	Name    string
	Version string
	Raw     string
}

// RenderedPrompt is the final prompt string after variable substitution.
type RenderedPrompt struct {
	TemplateName string
	Content      string
}

// TemplateVars is a free-form map of variable substitutions.
type TemplateVars map[string]any

package main

import (
	"bytes"
	"fmt"
	"text/template"
)

// Registry holds compiled, validated prompt templates by name.
type Registry struct {
	templates map[string]*compiledTemplate
}

type compiledTemplate struct {
	meta     PromptTemplate
	compiled *template.Template
}

func NewRegistry() *Registry {
	return &Registry{templates: make(map[string]*compiledTemplate)}
}

// Register parses and validates the template at registration time.
func (r *Registry) Register(pt PromptTemplate) error {
	tmpl, err := template.New(pt.Name).Option("missingkey=error").Parse(pt.Raw)
	if err != nil {
		return fmt.Errorf("parse template %q: %w", pt.Name, err)
	}
	r.templates[pt.Name] = &compiledTemplate{meta: pt, compiled: tmpl}
	return nil
}

// MustRegister panics if registration fails — safe for package-level init.
func (r *Registry) MustRegister(pt PromptTemplate) {
	if err := r.Register(pt); err != nil {
		panic(err)
	}
}

// Render substitutes vars into the named template and returns the result.
func (r *Registry) Render(name string, vars TemplateVars) (RenderedPrompt, error) {
	ct, ok := r.templates[name]
	if !ok {
		return RenderedPrompt{}, fmt.Errorf("template %q not found", name)
	}
	var buf bytes.Buffer
	if err := ct.compiled.Execute(&buf, vars); err != nil {
		return RenderedPrompt{}, fmt.Errorf("render %q: %w", name, err)
	}
	return RenderedPrompt{TemplateName: name, Content: buf.String()}, nil
}

// PromptBuilder assembles multi-section prompts by rendering several templates.
type PromptBuilder struct {
	registry *Registry
}

func NewPromptBuilder(r *Registry) *PromptBuilder {
	return &PromptBuilder{registry: r}
}

func (b *PromptBuilder) Build(sections []struct {
	Name string
	Vars TemplateVars
}) (string, error) {
	var buf bytes.Buffer
	for _, s := range sections {
		rendered, err := b.registry.Render(s.Name, s.Vars)
		if err != nil {
			return "", err
		}
		buf.WriteString(rendered.Content)
		buf.WriteByte('\n')
	}
	return buf.String(), nil
}

package main

import (
	"fmt"
	"log"
)

func main() {
	registry := NewRegistry()

	registry.MustRegister(PromptTemplate{
		Name:    "system",
		Version: "1.0.0",
		Raw:     "You are a helpful {{.Role}} assistant. Today is {{.Date}}.",
	})
	registry.MustRegister(PromptTemplate{
		Name:    "user_turn",
		Version: "1.0.0",
		Raw:     "User: {{.Query}}",
	})
	registry.MustRegister(PromptTemplate{
		Name:    "tool_result",
		Version: "1.0.0",
		Raw:     "Tool ({{.ToolName}}): {{.Output}}",
	})

	builder := NewPromptBuilder(registry)
	prompt, err := builder.Build([]struct {
		Name string
		Vars TemplateVars
	}{
		{"system", TemplateVars{"Role": "Go programming", "Date": "2026-01-01"}},
		{"user_turn", TemplateVars{"Query": "How do I use context cancellation?"}},
		{"tool_result", TemplateVars{"ToolName": "web_search", "Output": "Context cancellation docs..."}},
	})
	if err != nil {
		log.Fatalf("build: %v", err)
	}

	fmt.Print(prompt)
	// Output:
	// You are a helpful Go programming assistant. Today is 2026-01-01.
	// User: How do I use context cancellation?
	// Tool (web_search): Context cancellation docs...
}

Real-World Analogy

Legal document templates: a law firm maintains versioned contract templates with placeholder clauses. The paralegal fills in the blanks (client name, date, jurisdiction) for each engagement. The underlying template is reviewed, approved, and versioned independently from the data that populates it. Changing the indemnification clause means updating one template file, not hunting through every engagement letter.

Pros and Cons

Pros	Cons
Prompt text is reviewable, diffable, and versionable as plain files	`text/template` syntax is unfamiliar to non-Go contributors
`missingkey=error` surfaces missing vars at render time, not silently	Template logic (conditionals, ranges) can grow complex and hard to test
Registry validates syntax at startup, not during a live LLM call	Each new section type requires a new template registration
`PromptBuilder` decouples assembly order from template content	Templates are strings — IDE support for embedded syntax is limited

Best Practices

Version every template (Version: "1.0.0") and log the version alongside every LLM call — prompt regressions are easier to diagnose when you know which version was active.
Keep templates as logic-free as possible — use Go code for conditionals, not {{if}} blocks inside templates.
Write unit tests that call Registry.Render() with known vars and assert the output string — prompts are testable code.
Store template raw strings as .tmpl files in an embed.FS so they can be reviewed in pull requests without touching Go source.
Use TemplateVars (a map[string]any alias) consistently — resist the temptation to pass typed structs, which break the uniform Render signature.

When to Use

Any agent with more than one prompt section or more than two variable substitutions.
Teams where non-engineers need to review or edit prompt content.
Systems that run A/B experiments on prompt wording.

When NOT to Use

Trivial single-turn agents with a one-sentence system prompt — a string constant is fine.
Prompts with no variable substitution at all — just use a const.

Builder in Go Separate a multi-step construction workflow from the final representation so the same input can produce different outputs cleanly. Template Method in Go Define the skeleton of an algorithm once while letting concrete steps vary through narrow hook methods. Tool Use in Go Register typed tools by name so an agent can dispatch LLM-selected function calls to the right handler without embedding dispatch logic in the agent itself. Agent Loop (ReAct) in Go Drive an agent by alternating reasoning and acting steps inside a structured loop that terminates when the model signals a final answer.